characterization

title: “Characterization Package” description: “Petroleum TBP, plus-fraction, assay, lumping, asphaltene, and pseudo-component characterization in NeqSim.” —

The neqsim.thermo.characterization package converts petroleum assay, TBP, and plus-fraction information into pseudo-components suitable for NeqSim equations of state and process calculations.

Main workflows

Workflow	Primary API	Use
Pre-binned TBP fractions	`SystemInterface.addTBPfraction(...)`	Add a petroleum cut from moles, molar mass, and specific gravity
Plus fraction	`SystemInterface.addPlusFraction(...)` + `Characterise`	Represent and split a C7+/C20+ heavy end
Refinery assay	`OilAssayCharacterisation`	Convert assay data, export, split, re-lump, re-ingest and recharacterize an auditable TBP cut table, with invertible recovery/cut-point queries and conservative target-grid resampling
Assay blend screening	`RefineryAssayBlend`	Combine whole-assay SG/API and optional sulfur/nitrogen on an explicit mass basis
TBP property model selection	`Characterise.setTBPModel(...)`	Select Pedersen, Lee-Kesler, Riazi-Daubert, Twu, Cavett, Standing, and related models
Lumping	`Characterise.configureLumping()`	Reduce a detailed heavy-end slate while preserving configured grouping rules
Common-slate characterization	`PseudoComponentCombiner`	Align multiple characterized fluids to a shared pseudo-component definition
Wax/asphaltene characterization	wax/asphaltene classes	Specialized heavy-phase workflows

Critical unit contract

addTBPfraction and addPlusFraction use kg/mol for molar mass. Petroleum examples therefore use values such as 0.096 kg/mol for a roughly C7 cut, not 96.0.

The density argument is the petroleum specific gravity/relative-density numeric value. Current system APIs also accept density values above 1.5 as kg/m3 and normalize them internally, but unit-explicit refinery-assay helpers are preferred when importing assay tables.

import neqsim.thermo.system.SystemInterface;
import neqsim.thermo.system.SystemSrkEos;

SystemInterface fluid = new SystemSrkEos(373.15, 100.0);
fluid.addComponent("methane", 0.70);
fluid.addComponent("ethane", 0.10);
fluid.addComponent("propane", 0.08);
fluid.addComponent("n-butane", 0.05);

// name, moles, molar mass [kg/mol], specific gravity [-]
fluid.addTBPfraction("C7", 0.04, 0.096, 0.727);
fluid.addPlusFraction("C20+", 0.03, 0.400, 0.90);

Refinery assay characterization

For crude/petroleum assays, use OilAssayCharacterisation rather than manually converting every volume cut to moles. The assay API provides:

one explicit composition basis per assay: mass or liquid volume;
volume-to-mass conversion using cut density;
literature-qualified ASTM D86 reference-point conversion at 0, 10, 30, 50, 70, 90, and 95 vol% with an explicit caller-supplied 100 vol% TBP terminal boundary;
auditable TBP cut-table export with mass/volume-basis round-trip closure and fail-closed contiguous boundaries;
bounded, invertible TBP liquid-volume and ideal-additive-volume mass recovery/cut-point queries with unit-explicit interval-yield receipts;
immutable TBP boiling-range mass-yield, temperature-moment, distribution-spread, SG60/60, API-gravity, density, and Watson-factor receipts with additive raw-moment closure;
conservative adjacent whole-cut re-lumping with exact liquid-volume and implied-mass closure;
kg/mol and g/mol explicit molar-mass helpers;
specific-gravity, kg/m3, and API-gravity density inputs;
exact API-gravity/SG60/60 round-tripping and explicit bulk density at 60 degF;
immutable whole-assay blend screening with ideal additive liquid volumes and mass-linear sulfur/nitrogen;
auditable optimizer property bounds, margins, and binding-constraint receipts;
auditable blend-batch mass, additive-volume, specific-gravity, and optimizer-cost receipts;
immutable label-addressable source ledgers for qualified blend batches;
complete optimized blend plans with source-level cost closure and retained quality receipts;
stoichiometric hydrotreating sulfur/hydrogen screening receipts with explicit H2/S assumptions;
single- and multi-cut catalytic-reforming naphthene/paraffin-to-aromatic receipts with explicit hydrogen-recovery allocation;
caller-defined hydrocracking conversion/product-lump receipts with reformer-hydrogen supply allocation;
caller-defined FCC conversion/product-lump receipts with coke-carbon, dry-air, CO/CO2, and dry-flue-gas closure;
caller-defined delayed-coking conversion/product-lump receipts with feed-basis duty, fuel, steam, and closure;
stoichiometric hydrotreating nitrogen/hydrogen/ammonia receipts with explicit H2/N assumptions;\n- coupled hydrotreating sulfur/nitrogen receipts solved on one liquid-product mass basis;\n- unit-explicit coupled sulfur/nitrogen throughput receipts in kg/h;\n- coupled sulfur/nitrogen makeup- and outlet-gas receipts with H2, H2S, NH3, and non-H2 closure;
coupled sulfur/nitrogen recycle/purge receipts with explicit H2, H2S, NH3, and non-H2 recovery;
unit-explicit coupled recycle-throughput receipts in kg/h and kmol/h;
coupled sulfur/nitrogen hydrogen energy and caller-priced utility receipts;
coupled sulfur/nitrogen external liquid-product and export-gas distribution receipts;
caller-owned coupled sulfur/nitrogen reaction-heat and net thermal-duty receipts;
caller-owned coupled sulfur/nitrogen fired-heater fuel, cost, and emissions receipts;\n- caller-owned CHSON fuel/air/complete-combustion flue-gas closure receipts;
caller-owned wet-flue-gas sensible stack-loss receipts reconciled to qualified furnace loss;
caller-owned wet-flue-gas heat-recovery receipts with explicit recovered/remaining loss closure;
caller-owned recovered-heat utilization with avoided/net fired-heater fuel, cost, and emissions receipts;
integrated net hydrogen/fired-heater energy, emissions, and caller-priced operating receipts;
liquid-product-basis energy, emissions, and caller-priced operating-intensity receipts;
caller-priced coupled sulfur/nitrogen screening-economics receipts;
single-variable break-even economics and price-sensitivity receipts;
same-physical-case economics scenario-delta attribution receipts;\n- fixed-screening-price economics case-delta receipts;\n- symmetric total economics-delta attribution receipts;
scenario-based coupled sulfur/nitrogen hydrogen-supply emissions and carbon-cost receipts;
integrated coupled sulfur/nitrogen material, energy, emissions, and scenario-cost receipts;
hydrotreating makeup-gas and outlet-gas receipts with explicit H2 purity, excess, and non-H2 molar mass;
hydrotreating recycle/purge receipts with explicit component recovery and purge assumptions;
unit-explicit hydrotreating throughput receipts in kg/h and kmol/h;
explicit hydrotreating hydrogen energy and caller-priced utility receipts;
scenario-based hydrotreating hydrogen-supply emissions and carbon-cost receipts;
integrated hydrotreating material, energy, emissions, and scenario-cost receipts;
forward and inverse UOP/Watson characterization between representative boiling point and specific gravity;
mass-basis mapping of known assay light ends to authoritative NeqSim standard components;
number-average molar mass from mass-basis PIANO family/carbon-number data;
per-cut total-sulfur and total-nitrogen inputs with mass-basis whole-assay reconstruction;
pre-binned cumulative TBP cut-boundary ingestion;
preserved finite and one-sided lower/upper boiling boundaries;
closure, duplicate-name, monotonicity, and repeated-application guards.

See Refinery Assay and TBP Cut Characterization for the complete contract and the refinery campaign gap matrix. Independent public-data bookkeeping evidence is tracked in DOE Big Hill Sweet refinery assay validation, whole-assay density/API evidence in DOE/OEDI COA bulk density qualification, per-cut characterization evidence in DOE Big Hill Watson-factor qualification, terminal representative-temperature evidence in DOE Big Hill terminal-Watson qualification, composition-resolved light-end evidence in DOE Big Hill light-end qualification, PIANO aggregate molar-mass evidence in DOE Big Hill C5-175 degF qualification, assay-quality evidence in DOE Big Hill sulfur qualification and DOE Big Hill nitrogen qualification, terminal-boundary evidence in DOE Big Hill terminal-cut qualification, the atmospheric process-integration gate in DOE Big Hill atmospheric fractionation qualification, and the connected material/energy boundary in DOE Big Hill atmospheric-to-vacuum workflow.

The qualified inputs are assembled into one reusable reference composition by DOE Big Hill Sweet complete modeled assay slate.

A second public operating case is retained by Al-Diwiniya atmospheric operating reference. Its 2-60 liquid-vol% partial TBP curve, plant configuration, product rates, and draw temperatures remain explicitly separate from the complete DOE modeled slate. The source fixed its HYSYS product rates, so those values are operating specifications rather than independent yield-validation evidence.

Sarir atmospheric validation reference adds a CC BY 4.0, complete-range TBP case with 34-tray operating data, numeric product ASTM D86 endpoints, and plant product rates that remain independent validation targets.

Persistent PR covolume tuning

ComponentPR.setOmegaB(value) sets a positive, finite, dimensionless per-component coefficient in $b_i = \Omega_{B,i} R T_{c,i}/P_{c,i}$. With SI $R$, $T_c$ in K and $P_c$ in Pa, this gives $b_i$ in m³/mol. NeqSim uses bara internally; multiply the existing internal getb() value by $10^{-5}$ to obtain m³/mol. The ordinary PR default remains exactly 0.077803333. Set the coefficient on the component in every allocated phase (getMaxNumberOfPhases()), then call fluid.init(0) before flashing or reading updated properties. This is the same phase-ownership requirement as other component-property tuning. The public methods are callable from Java and JPype’s ComponentPR wrapper. The older setb(...) call changes only transient storage and is still replaced by component initialization; use setOmegaB(...) for persistent tuning.

hasOmegaBOverride() reports whether tuning is active and getOmegaBOverride() returns the supplied value, or NaN when unset. getOmegaB() returns the active coefficient, including the default. clearOmegaBOverride() removes tuning; initialize again to rebuild the cached covolume. The override survives repeated initialization, flashes, fluid cloning, and Java serialization. Older serialized PR components without this field keep the default because zero represents an unset override.

The storage belongs to PR components rather than all EOS components. BNS retains its supplied constructor coefficient when no override is active, and resetting returns to that coefficient. PR-based CPA components reject setOmegaB with UnsupportedOperationException: their covolumes belong to the association parameterization. SRK is outside this API’s scope. No flash calls or fitting iterations are added to the normal initialization path.

E300 exports explicit PR coefficients in OMEGAB; reload them with the opt-in EclipseFluidReadWrite.readWithPrOmegaB(...) reader. Ordinary E300 readers retain their historical coefficient behavior. JSON fluid files preserve explicit PR overrides in optional omegaB component fields. Diagnostic fluid.toJson() output is not a reloadable fluid definition. Retain coefficient provenance, fit conditions and uncertainty separately: supplying a number does not validate an assay or reproduce a paper whose other tuning inputs are missing. The text formats do not reproduce the specialized BNS or CPA model from these coefficients; the supported tuning round trip here is ordinary PR/PR1978.

Regressions: ComponentPrOmegaBTest checks the analytical coefficient, initialization, flash, invalid input, reset, clone/serialization and BNS/CPA boundaries; PrOmegaBFluidRoundTripTest checks the text-persistence contract.

TBP fraction models

TBP models estimate the properties needed to represent petroleum pseudo-components in an EOS. Available implementations include standard Pedersen SRK/PR variants, Lee-Kesler, Riazi-Daubert, Twu, Cavett, and Standing. Pedersen estimation rejects molecular weights at or above 1120 g/mol (1.120 kg/mol at the system API); the explicit PedersenSRKHeavyOil and PedersenPRHeavyOil property models are unavailable at every molecular weight. The RiaziDaubert fallback inherits the same upper boundary. These paths throw UnsupportedOperationException rather than constructing an unphysical component. The seven-argument addTBPfraction overload accepts independently validated critical properties for heavier cuts; see TBP Fraction Models for units and limitations.

SystemInterface fluid = new SystemSrkEos(350.0, 50.0);
fluid.getCharacterization().setTBPModel("PedersenSRK");
fluid.addTBPfraction("C7", 0.05, 0.096, 0.727);
fluid.addTBPfraction("C10", 0.04, 0.134, 0.782);
fluid.addTBPfraction("C12+", 0.15, 0.250, 0.85);

For equations, model selection boundaries, and references, see:

Lumping configuration

After plus-fraction splitting, lumping can reduce the number of pseudo-components for faster process calculations.

// Preserve lighter TBP fractions and lump the heavier range.
fluid.getCharacterization().configureLumping()
    .model("PVTlumpingModel")
    .plusFractionGroups(5)
    .build();

// Target a total number of pseudo-components.
fluid.getCharacterization().configureLumping()
    .model("standard")
    .totalPseudoComponents(6)
    .build();

// Match user-defined grouping boundaries.
fluid.getCharacterization().configureLumping()
    .customBoundaries(6, 7, 10, 15, 20)
    .build();

// Keep the detailed SCN representation.
fluid.getCharacterization().configureLumping()
    .noLumping()
    .build();

Model	Behaviour	Typical use
`PVTlumpingModel`	Preserves configured lighter TBP fractions and lumps the plus fraction	PVT/process workflows that retain light-cut detail
`standard`	Lumps the characterized heavy range to a requested total	Smaller simulation slates
custom boundaries	Uses explicit carbon-number/group boundaries	Matching an external/reference characterization
no lumping	Retains the generated detailed representation	Detailed characterization studies

Common pseudo-component slates

When several reservoir or process fluids need to be mixed consistently, use PseudoComponentCombiner rather than assuming independently generated pseudo-components have identical meaning.

See Fluid Characterization Combining for common-slate and reference-slate workflows.

Asphaltene and wax workflows

NeqSim also contains specialized heavy-phase characterization used by wax and asphaltene calculations. These are separate from the refinery-assay bookkeeping API because they introduce additional phase-model assumptions and validation requirements.

See:

Validation guidance

Characterization validation should distinguish three layers:

Bookkeeping: units, cut yields, composition/mass closure, component identity, splitting/lumping conservation.
Property correlations: boiling point, molecular weight, density, critical properties, acentric factor, and applicability ranges.
Process behaviour: flash, phase envelope, distillation/fractionation, and product-yield agreement for representative fluids.

A bookkeeping regression does not by itself validate a petroleum-property correlation, and a property match does not by itself establish refinery column performance. The refinery campaign in issue #3305 uses these layers as separate quality gates.