Refinery Crude Processing
When to use this
Use this skill for NeqSim's existing crude-assay, petroleum-cut, refinery blend, crude-fractionation reference-case, product-boiling-range, hydrotreating balance, and catalytic-reforming stoichiometric APIs. Treat the APIs as connected building blocks, not as one turnkey refinery simulator.
The useful data flow is:
assay data -> OilAssayCharacterisation -> pseudo-component fluid -> blend plan/batch -> equilibrium column, hydrotreating balances, or reforming stoichiometry -> operating/economics receipts
Use neqsim-distillation-design for equilibrium-column setup and convergence details. Use neqsim-eos-regression when the job is to fit an EOS to measured PVT rather than convert an assay. The Doe Big Hill and Sarir classes are case-specific reference scenarios; reuse their construction pattern with a user-provided assay and operating basis instead of treating their constants as a general crude-unit design.
Class map
| Class | Package | What it does | Verified API surface |
|---|---|---|---|
OilAssayCharacterisation / nested AssayCut |
thermo.characterization |
Holds mass- or volume-yield cuts and applies them as petroleum pseudo-components. | system.getOilAssayCharacterisation(), clearCuts(), addCut(AssayCut), getCuts(), getResolvedMassFractions(), apply(); AssayCut(String), fluent withMassFraction(double), withWeightPercent(double), withVolumeFraction(double), withSpecificGravity(double), withApiGravity(double), withAverageBoilingPointCelsius(double), withMolarMassKgPerMol(double), withSulfurMassFraction(double), withNitrogenMassFraction(double). |
DoeBigHillSweetAssay |
thermo.characterization |
Supplies a named, fixed sweet-crude assay and a qualified vacuum-screening subset. | create(SystemInterface), create(SystemInterface, double), createVacuumScreeningFeed(SystemInterface, double). |
AlDiwiniyaAtmosphericReference |
thermo.characterization |
Stores published/reference atmospheric crude feed, products, TBP points, and measured reference properties. | getTbpCumulativeVolumePercent(), getTbpTemperatureCelsius(), getProducts(), getCrudeFeedRateM3PerHour(), getCrudeApiGravityAt15C(). |
RefineryAssayBlend / RefineryViscosityBlend |
thermo.characterization |
Reconstructs bulk density/API/sulfur/nitrogen and viscosity blend properties without mutating source systems. | fromAssays(OilAssayCharacterisation[], double[]), fromBulkProperties(double[], double[]) or the four-array quality overload; getters include getMassFractions(), getSpecificGravity(), getApiGravity(), getSulfurMassFraction(), getNitrogenMassFraction(). |
RefineryLinearBlendOptimizer |
thermo.characterization |
Minimizes source cost subject to API, sulfur, nitrogen, and viscosity bounds. | optimizeMinimumCost(double[] costs, double[] specificGravities, double[] sulfurFractions, double[] nitrogenFractions, double[] viscositiesCSt, double temperatureCelsius, double minimumApi, double maximumApi, double maximumSulfur, double maximumNitrogen, double minimumViscosityCSt, double maximumViscosityCSt); result getters include getSourceMassFractions(), getAssayBlend(), getViscosityBlend(), getUnitCostPerMass(), getQualityConstraintReceipt(). |
RefineryBinaryBlendEnvelope |
thermo.characterization |
Evaluates feasible first-source fractions for two-source quality constraints. | fromQualityConstraints(...), getMinimumFirstSourceMassFraction(), getMaximumFirstSourceMassFraction(), evaluateAtFirstSourceMassFraction(...). |
RefineryBlendBatch, RefineryBlendOptimizationPlan, RefineryBlendSourceLedger |
thermo.characterization |
Turns blend fractions into a mass/volume batch, links optimizer outputs to source identifiers, and preserves a source receipt ledger. | fromMassFractions(double, double[], double[]), batch fromOptimization(double, RefineryLinearBlendOptimizer.Result, double[]), plan fromOptimization(String[], double, double[], double[], RefineryLinearBlendOptimizer.Result), and ledger fromBatch(String[], RefineryBlendBatch); plan getters getOptimization(), getBatch(), getSourceLedger(), getSourceCostReceipts(). |
RefineryHydrotreatingSulfurNitrogenBalance |
thermo.characterization |
Closes screening-level sulfur/nitrogen removal, hydrogen consumption, H2S/NH3 production, and product mass. | calculate(double, double, double, double, double, double, double) or calculateForAssay(double, OilAssayCharacterisation, double, double, double, double); getters include getFeedMassKg(), getSulfurRemovedMassKg(), getNitrogenRemovedMassKg(), getProductMassKg(), getTotalMassBalanceResidualKg(). |
RefineryHydrotreating*Balance family |
thermo.characterization |
Carries staged hydrogen supply/recycle, utility, fired-heater, emissions, thermal-duty, throughput, sulfur, and nitrogen balance calculations. | Read each immutable result object's get... API; examples include RefineryHydrotreatingSulfurNitrogenThermalDutyBalance.calculate(...) and getSensibleHeatingDutyMegaWatt(). |
RefineryHydrotreating*Receipt family |
thermo.characterization |
Builds operating, product-distribution, net-intensity, and scenario-economics receipts from upstream balances. | RefineryHydrotreatingSulfurNitrogenOperatingReceipt.calculate(emissionsBalance); getFeedMassFlowKgPerHour(), getFreshHydrogenMassFlowKgPerHour(), getFreshHydrogenEnergyMWhPerTonneFeed(), getTotalScenarioCostPerHour(). |
RefineryCatalyticReformingStoichiometricBalance, RefineryCatalyticReformingFeedBalance, RefineryCatalyticReformingHydrogenRecoveryBalance |
thermo.characterization |
Close single- or multi-cut naphthene/paraffin reforming receipts and allocate produced hydrogen by an explicit recovery fraction. | Single-cut calculate(int, double, double, double, double); feed calculate(int[], double[], double[], double[], double[]); recovery calculate(feedBalance, recoveryFraction); getters include getReformateMassFlowKgPerHour(), getRecoveredHydrogenMassFlowKgPerHour(), getRecoveredHydrogenKgPerTonneFeed(), and closure residuals. |
RefineryHydrocrackingYieldBalance, RefineryHydrocrackingHydrogenSupplyBalance |
thermo.characterization |
Screen caller-owned hydrocracking conversion, hydrogen consumption, three product lumps, and recovered-reformer-hydrogen offset. | Yield calculate(feedKgPerHour, conversion, hydrogenKgPerTonne, lightGasFraction, naphthaFraction, middleDistillateFraction); supply calculate(yieldBalance, reformingRecoveryBalance); getters include product kg/h, imported/surplus H2 kg/h, demand coverage, and closure residuals. |
RefineryFccYieldBalance, RefineryFccCokeRegeneratorBalance |
thermo.characterization |
Screen caller-owned FCC conversion and five product lumps, then close coke carbon, dry-air demand, CO/CO2 allocation, and dry flue gas. | Yield calculate(feedKgPerHour, conversion, dryGasFraction, lpgFraction, gasolineFraction, lcoFraction, cokeFraction); regenerator calculate(yieldBalance, cokeCarbonFraction, burnFraction, carbonToCo2Fraction, dryAirO2Fraction, excessO2Fraction); getters include lump flows, air/flue-gas flows, and closure residuals. |
RefineryDelayedCokingYieldBalance, RefineryDelayedCokingUtilityBalance |
thermo.characterization |
Screen caller-owned delayed-coking conversion and five product lumps, then calculate feed-basis process duty, fuel, and steam. | Yield calculate(feedKgPerHour, conversion, gasFraction, naphthaFraction, lcgoFraction, hcgoFraction, cokeFraction); utility calculate(yieldBalance, dutyMJPerKgFeed, furnaceEfficiency, fuelLhvMJPerKg, steamKgPerTonneFeed); getters expose product flows and mass/energy residuals. |
DoeBigHillVacuumFractionationCase, SarirAtmosphericFractionationCase |
process.equipment.distillation |
Reproducible, data-bounded vacuum/atmospheric reference cases that assemble a DistillationColumn. |
Doe create(String, double, OperatingInputs); Sarir create(String, double[], double[], OperatingInputs) or createFromHeatingCase(String, SarirAtmosphericCrudeHeatingCase, OperatingInputs); case getters include getFeedStream(), getColumn(), getOperatingInputs(), and Sarir run(UUID). Inputs are case-specific. |
SarirAtmosphericPumparoundScreen, SarirAtmosphericSideStripperContactScreen |
process.equipment.distillation |
Evaluates explicitly mapped Sarir pumparound settings and a bounded side-stripper contact screen. | Pumparound configure(...); side-stripper class JavaDoc describes a single-contact screen, not a multistage column model. |
ProductBoilingPointDistribution |
process.equipment.distillation |
Reports a discrete mole-based normal-boiling-point distribution from a product stream's pseudo-components. | from(StreamInterface), getBoilingPointTemperaturesKelvin(), getCumulativeMoleFractions(), getMeanNormalBoilingPointKelvin(), getNormalBoilingPointQuantileKelvin(...). |
Standard_ASTM_D86, RiaziDaubertDistillationConversion |
standards.oilquality |
Calculates NeqSim's ASTM D86-style curve and exposes a published-point D86/TBP conversion. | new Standard_ASTM_D86(SystemInterface), calculate(), getDistillationCurve(), getTBPCurve(), getQualifiedD86Temperature(...); conversion methods convertD86ToTbpC(...), convertTbpToD86C(...). |
AsphalteneCharacterization, PedersenAsphalteneCharacterization, PedersenPlusModelSolver |
thermo.characterization |
Provides SARA/pseudocomponent or Pedersen-style heavy-end/asphaltene characterization and stability screening. | setSARAFractions(...), setC7plusProperties(...), evaluateStability(); Pedersen API includes characterize(), addAsphalteneToSystem(...), calculateOnsetPressure(...). |
BioFeedstock |
thermo.characterization |
Describes solids, elemental, lignocellulosic, digestion, and handling properties for biomass feedstocks; this is adjacent to refinery work, not a petroleum assay. | library(String), setElementalAnalysis(...), setSolidsAnalysis(...), validate(), toMap(). |
CharacterizationOptions, CharacterizationValidationReport |
thermo.characterization |
Configures supported characterization/recharacterization behavior and compares source/reference characterization results. | CharacterizationOptions.builder(), getNamingScheme(), isNormalizeComposition(), CharacterizationValidationReport.generate(...), isValid(), getWarnings(), getMassDifferencePercent(). |
Build pattern
This minimal path makes a two-cut assay, applies its pseudo-components to an EOS fluid, feeds a small equilibrium column, and independently computes the assay-based sulfur/nitrogen material balance. The balance is not a reacting hydrotreater model.
import neqsim.process.equipment.distillation.DistillationColumn;
import neqsim.process.equipment.stream.Stream;
import neqsim.thermo.characterization.OilAssayCharacterisation;
import neqsim.thermo.characterization.OilAssayCharacterisation.AssayCut;
import neqsim.thermo.characterization.RefineryHydrotreatingSulfurNitrogenBalance;
import neqsim.thermo.system.SystemInterface;
import neqsim.thermo.system.SystemSrkEos;
SystemInterface crude = new SystemSrkEos(298.15, 1.01325);
crude.setMixingRule("classic");
OilAssayCharacterisation assay = crude.getOilAssayCharacterisation();
assay.clearCuts();
assay.addCut(new AssayCut("Light").withMassFraction(0.40).withSpecificGravity(0.75)
.withAverageBoilingPointCelsius(200.0).withSulfurMassFraction(0.002).withNitrogenMassFraction(0.0005));
assay.addCut(new AssayCut("Heavy").withMassFraction(0.60).withSpecificGravity(0.90)
.withAverageBoilingPointCelsius(400.0).withSulfurMassFraction(0.012).withNitrogenMassFraction(0.002));
assay.setTotalAssayMass(1.0);
assay.apply();
Stream feed = new Stream("crude assay feed", crude);
feed.setFlowRate(10000.0, "kg/hr");
feed.setTemperature(100.0, "C");
feed.setPressure(3.0, "bara");
feed.run();
feed.getThermoSystem().initProperties();
DistillationColumn column = new DistillationColumn("screening crude column", 8, true, true);
column.addFeedStream(feed, 4);
column.setTopPressure(1.5);
column.setBottomPressure(2.0);
column.getReboiler().setOutletTemperature(650.0);
column.setCondenserRefluxRatio(0.5);
column.run();
RefineryHydrotreatingSulfurNitrogenBalance balance =
RefineryHydrotreatingSulfurNitrogenBalance.calculateForAssay(
1000.0, assay, 0.0001, 0.00005, 2.0, 4.0);
double productMassKg = balance.getProductMassKg();
double massClosureKg = balance.getTotalMassBalanceResidualKg();
Equivalent Python/JVM access pattern:
from neqsim import jneqsim
SystemSrkEos = jneqsim.thermo.system.SystemSrkEos
OilAssayCharacterisation = jneqsim.thermo.characterization.OilAssayCharacterisation
AssayCut = OilAssayCharacterisation.AssayCut
DistillationColumn = jneqsim.process.equipment.distillation.DistillationColumn
Stream = jneqsim.process.equipment.stream.Stream
SulfurNitrogenBalance = jneqsim.thermo.characterization.RefineryHydrotreatingSulfurNitrogenBalance
crude = SystemSrkEos(298.15, 1.01325)
crude.setMixingRule("classic")
assay = crude.getOilAssayCharacterisation()
assay.clearCuts()
assay.addCut(AssayCut("Light").withMassFraction(0.40).withSpecificGravity(0.75)
.withAverageBoilingPointCelsius(200.0).withSulfurMassFraction(0.002)
.withNitrogenMassFraction(0.0005))
assay.addCut(AssayCut("Heavy").withMassFraction(0.60).withSpecificGravity(0.90)
.withAverageBoilingPointCelsius(400.0).withSulfurMassFraction(0.012)
.withNitrogenMassFraction(0.002))
assay.setTotalAssayMass(1.0)
assay.apply()
feed = Stream("crude assay feed", crude)
feed.setFlowRate(10000.0, "kg/hr")
feed.setTemperature(100.0, "C")
feed.setPressure(3.0, "bara")
feed.run()
feed.getThermoSystem().initProperties()
column = DistillationColumn("screening crude column", 8, True, True)
column.addFeedStream(feed, 4)
column.setTopPressure(1.5)
column.setBottomPressure(2.0)
column.getReboiler().setOutletTemperature(650.0)
column.setCondenserRefluxRatio(0.5)
column.run()
balance = SulfurNitrogenBalance.calculateForAssay(1000.0, assay, 0.0001, 0.00005, 2.0, 4.0)
product_mass_kg = balance.getProductMassKg()
mass_closure_kg = balance.getTotalMassBalanceResidualKg()
For feed data supplied as cumulative volume-yield / boiling-point boundaries, addTBPCutBoundariesCelsius(...) accepts boundaries in degC and per-cut specific gravities. It requires 0 and 100 vol% endpoints and matching array lengths. Prefer explicit assay yields and lab properties over the bundled reference assay when building a new case.
Result extraction
| Result | API | Units / interpretation |
|---|---|---|
| Assay cut yields | getResolvedMassFractions() |
Dimensionless mass fractions in getCuts() order; returned as a defensive copy. |
| Bulk assay properties | getBulkSpecificGravity(), getBulkApiGravity(), getBulkDensityKgPerCubicMetreAt60F(), getBulkSulfurMassFraction(), getBulkNitrogenMassFraction() |
Specific gravity is dimensionless; API is degrees API; density is kg/m3 at 60 F; sulfur/nitrogen are mass fractions. |
| Applied assay amount | getTotalAssayMass() |
kg used to generate component mole inventories; set with setTotalAssayMass(double). |
| Blend properties | RefineryAssayBlend getters |
Mass fractions, specific gravity, API gravity and sulfur/nitrogen mass fraction; sulfur/nitrogen getters are unavailable for bulk-property inputs that omitted those data. |
| Balance outputs | RefineryHydrotreatingSulfurNitrogenBalance getters |
Batch mass kg, removed sulfur/nitrogen kg, produced H2S/NH3 kg, hydrogen consumed kg and mass-balance residual kg. |
| Operating receipt | RefineryHydrotreatingSulfurNitrogenOperatingReceipt getters |
Feed/H2 kg/h; H2 energy MWh/t feed; emissions kg CO2e/h or kg CO2e/t feed; caller-priced scenario currency/h or currency/t. |
| D86 curve | Standard_ASTM_D86.getDistillationCurve() |
Two columns: liquid volume percent and temperature in degC on the active reporting basis. getDistillationCurveKelvin() uses K. |
| Discrete product boiling points | ProductBoilingPointDistribution getters |
Normal boiling points in K, cumulative mole fractions, and mean normal boiling point in K or degC. Not an ASTM curve. |
Standard_ASTM_D86.calculate() must run before reading its result. The qualified conversion getQualifiedD86Temperature(...) accepts only 0, 10, 30, 50, 70, 90, or 95 vol% and defaults to degC; it rejects unsupported points and temperatures outside its qualified reference domain.
Gotchas
OilAssayCharacterisation.apply()mutates the attached thermodynamic system by adding pseudo-components. Validate the cuts first, apply once, and do not reapply over existing generated names. The method rejects duplicates rather than silently doubling the assay.- Assay cuts must use a consistent yield basis. Volume fractions are converted to mass fractions using cut specific gravities; a mixed or incomplete basis fails.
getBulkSpecificGravity()uses ideal additive liquid volumes and does not model temperature correction or blend contraction. - For petroleum cuts, provide a boiling point or explicit molecular mass as required by the cut; tests verify that missing average boiling-point data fails before components are applied.
withMolarMassKgPerMolexpects kg/mol. Temperatures are K unless a method explicitly says Celsius; process pressure conventions are bara. - Always set the EOS mixing rule before running a flash/column. After a flash, call
initProperties()before reading transport properties. Clone the characterized fluid before independent scenario modifications. - Blend optimization is a linear, source-property blend screen. It is not a full thermodynamic mixture calculation, assay blending laboratory model, or refinery planning optimizer. It fails closed when no feasible blend satisfies the supplied bounds.
- The hydrotreating balance and its hydrogen/utility/emissions/economics receipts are algebraic scenario balances. They do not solve reactor kinetics, catalyst activity, equilibrium, reactor temperature profiles, or a complete H2 recycle process. State assumed stoichiometric H2-per-removed-heteroatom and caller-supplied prices/emission factors.
- The catalytic-reforming receipts represent only idealized same-carbon-number naphthene dehydrogenation and paraffin dehydrocyclization. The feed receipt aggregates unique carbon-number rows and retains each cut result. The recovery receipt uses a caller-owned hydrogen fraction and is not a separator, purity, compression, fuel, or hydrogen-network model. Caller-supplied family flows, conversions, and recovery are not feed characterization or yield predictions; do not infer kinetics, catalyst performance, hydrocracking/isomerization, octane, heat duty, or plant output.
- The hydrocracking receipts allocate caller-owned conversion, hydrogen consumption, and product-lump fractions, then offset demand with recovered reformer hydrogen. They do not predict yields, kinetics, catalyst behavior, product properties, heteroatom byproducts, reactor heat duty, separation, recycle, compression, or a refinery hydrogen network.
- The FCC receipts allocate caller-owned conversion and product-lump fractions, then close a simplified coke-carbon, dry-air, CO/CO2, and dry-flue-gas balance. They do not predict yields, kinetics, catalyst or riser behavior, fractionation, product properties, coke hydrogen/sulfur, regenerator heat duty or temperature, water, NOx/SOx, fines, or emissions compliance.
- The delayed-coking receipts allocate caller-owned conversion and product-lump fractions, then calculate feed-basis duty, fuel, and steam from caller-owned intensities. They do not predict yields, kinetics, cracking severity, coke quality, heater coking, drum cycle, fractionation, recycle, product properties, fired-equipment performance, emissions, blowdown, decoking, or safe operability.
DoeBigHillSweetAssay,DoeBigHillVacuumFractionationCase,SarirAtmosphericFractionationCase, andAlDiwiniyaAtmosphericReferencecontain case-specific data and evidence boundaries. They are examples/reference cases, not general-purpose crude-unit models. Sarir's side-stripper contact screen is not a multistage side stripper; generic column side draws/pumparounds are separate features.- NeqSim provides
Standard_ASTM_D86and a literature conversion from D86 to TBP. NoStandard_ASTM_D2887class was found instandards.oilquality; do not labelProductBoilingPointDistributionor a TBP curve as ASTM D2887 or as a lab test. - Characterization and balance APIs generally validate inputs with exceptions rather than returning an equipment
validateSetup()report. Record source assay values, units, missing cuts, and data gaps; do not replace absent assay measurements with the built-in example constants.
Validation / benchmarks
- Check that resolved assay mass fractions sum to 1.0 within the input precision and that applying the assay reconstructs the requested mass inventory. The source tests use tight mass closure around
1e-10for their controlled examples. - Reconstruct bulk API from specific gravity as
API = 141.5 / SG - 131.5. Treat this and reciprocal-volume specific-gravity blending as the documented ideal blend screen, not as a non-ideal density model. - Check total mass, sulfur, and nitrogen residuals from the corresponding balance getters; require finite non-negative hydrogen and products and achieved sulfur/nitrogen targets no greater than their feed fractions.
- For FCC screening, require converted-feed fractions to sum to one and verify feed, converted-product, overall mass, coke-carbon, oxygen, and dry-gas molar residuals. Independently qualify conversion, lump yields, coke analysis, burn, CO/CO2 allocation, and air assumptions.
- For delayed-coking screening, require converted-feed fractions to sum to one and verify converted-product, overall mass, and useful-energy residuals. Independently qualify conversion, yields, specific duty, furnace efficiency, fuel LHV, and steam intensity.
- For D86/TBP comparison, cite Riazi and Daubert, “Analytical correlations interconvert distillation-curve types” (Oil & Gas Journal, 1986). The implementation uses seven discrete recovery points and documented temperature ranges. It is a correlation/NeqSim prediction check, not an ASTM apparatus test or D2887 compliance claim.
- For an equilibrium crude tower, inspect convergence diagnostics, feed/product component balance, product yields, top/bottom pressure, and realistic cut ordering. Fenske–Underwood–Gilliland is an independent shortcut reasonableness check only where light/heavy keys and relative volatility are meaningful; it is not a rigorous crude assay validation.
- Compare named reference scenarios only against the same published/reference inputs and declared specification-vs-validation status. Preserve the data boundary: product rates that were imposed as specifications are not independent yield-validation evidence.
Related skills
neqsim-distillation-designfor rigorous equilibrium-column setup, solver selection, convergence and sizing.neqsim-api-patternsfor EOS creation, oil characterization, units, mixing rules and property initialization.neqsim-process-modelingfor connecting the column into a process flowsheet.neqsim-eos-regressionfor measured-PVT regression and C7+ parameter fitting.neqsim-benchmark-reference-datafor independent reference-data gates and provenance.neqsim-professional-reportingfor assumptions, evidence, uncertainty and engineering-report structure.