This guide defines an auditable path from laboratory observations to a NeqSim fluid model. It does not supply a universal fluid, tuning range, or acceptance limit. Sample identity, laboratory conditions, uncertainty, parameter bounds, and acceptance criteria are project-specific and must remain traceable to their owners.

For a runnable starting point, use the Java 8/Log4j2 PvtSeparatorQuickStart and its enabled documentation regression. The enabled PVT regression tests exercise the current regression surface. This page intentionally contains no second code example.

For executable sample/analysis QC, characterization, supported bounded CCE calibration, final parameter capture, fresh-process E300 replay and professional reporting, see the PVT fluid-study report workflow. Its narrower calibrated/exportable contract is explicit; simulation support does not imply that every fitting protocol is qualified.

Evidence boundary

The workflow is bounded by current repository sources:

Responsibility Maintained evidence
Experiment registration, weights, parameters, and optimization PVTRegression
Available tuning parameters and library defaults RegressionParameter
Optimized fluid, objectives, parameter values, and uncertainty accessors RegressionResult
PVT report assembly and exports PVTReportGenerator
Laboratory-test model setup PVT laboratory-test guide
Characterization equations and parameter meanings Fluid characterization mathematics

These sources establish API behavior, not the quality of a particular sample, laboratory campaign, equation-of-state choice, tuned parameter set, or field-development decision.

1. Freeze the data basis

Before constructing a model, record:

Keep raw observations immutable. Perform unit conversion, filtering, and derived-property calculation in a traceable preparation layer. Do not silently replace missing observations with illustrative values.

2. Construct and qualify the base fluid

Build the untuned fluid from the approved composition and characterization basis. Document the thermodynamic model, mixing rule, component mapping, plus-fraction splitting, and every externally supplied property. The Whitson reader, JSON fluid format, and Eclipse E300 import guide describe dedicated input routes.

Qualify the base fluid before regression. At minimum, check material normalization, component identity, critical-property plausibility, phase behavior near the laboratory path, and whether each laboratory experiment can run independently. Preserve the untuned result as the comparison baseline. The PVTRegression constructor clones the supplied system for its base and tuned states; subsequent project records should still identify the exact input revision.

3. Reproduce experiments independently

Configure only experiments represented by traceable observations. Run the corresponding NeqSim laboratory-test models before assembling a multi-experiment objective. This separates model-setup failures from regression behavior and exposes unit or phase-selection mistakes early.

Compare predictions and observations using the laboratory’s definitions. A relative volume, liquid dropout, solution gas-oil ratio, formation volume factor, density, and viscosity are different observables; do not combine them merely because they share a pressure point. Record both absolute and normalized residuals and explain the weighting basis.

4. Register data with explicit units

The current PVTRegression methods accept the following quantities:

Method Required quantities
addCCEData pressure in bar, relative volume as $V/V_{sat}$, optional Y-factor, temperature in K
addCVDData pressure in bar, liquid dropout in volume %, gas compressibility factor, temperature in K
addDLEData pressure in bar, solution GOR in Sm³/Sm³, oil FVF in m³/Sm³, oil density in kg/m³, temperature in K
addSeparatorData GOR in Sm³/Sm³, oil FVF, API gravity, separator pressure in bar, separator temperature in K, reservoir temperature in K
addViscosityData pressure in bara, dynamic viscosity in Pa s, temperature in K, and phase name gas, oil, liquid, aqueous, or water

These five data-ingestion methods define the current regression target surface.

Each addCVDData or addDLEData call registers one complete isothermal depletion experiment, with its original nonincreasing pressure schedule in bara. Do not split one laboratory experiment into singleton registrations: gas removal changes the remaining fluid, and DLE uses the final residual stock-tank oil as the common reference at 288.15 K and 1.01325 bara. Separate registrations retain separate histories, temperatures and reference volumes, including in the final objective summary. Observation arrays must match the schedule length.

The regression runs the full protocol on a fresh model clone for each distinct parameter vector. Frozen serialized model graphs keep interaction parameters independent of the source fluid and other experiments; ordinary fluid clones alone share some mixing-rule state. Observation functions share successful full-protocol results within that experiment; the cache holds at most eight trial vectors and never shares results across independently registered model/protocol identities. This preserves CVD liquid-dropout percentage points and the DLE Rs/Bo reference basis while avoiding a new depletion simulation for each property at each pressure.

For direct PVTRegressionFunction callers, register the protocol with registerDepletionExperiment(type, pressures, temperature). A six-entry observation contains pressure, temperature, experiment-type ordinal, property index, returned experiment index, and original protocol row index. Indexes must be integers and the row’s pressure, temperature and type must match registration. Legacy four-entry CVD/DLE observations retain independent singleton semantics; five-entry depletion observations are rejected. The existing experiment solvers and their physical qualification limits remain applicable; matching the direct full protocol establishes numerical identity, not agreement with measured PVT data.

ExperimentType.SATURATION_PRESSURE and ExperimentType.SWELLING are reserved identifiers; PVTRegression has no ingestion method or complete experimental protocol for either. Calling PVTRegressionFunction.calcValue(...) with those types throws UnsupportedOperationException before fluid cloning, parameter application or thermodynamic work. Enum presence and experiment weights do not enable an unsupported target. Saturation-pressure and swelling simulation APIs are separate from regression support.

A direct Levenberg–Marquardt sample containing an unsupported target also throws when its objective is evaluated. It must not be interpreted as a zero prediction or a zero residual against a zero-valued observation. Starting another solve clears the optimizer’s prior convergence result and statistics; an evaluation exception leaves it unsolved with no final chi-square result.

CVD/DLE registration validates its pressure schedule, temperature and observation-array lengths. The CCE and viscosity array-taking methods still require callers to validate equal-length, non-empty, finite input arrays before indexing. Validate observation values for every experiment, and retain original depletion order or an explicit sort record; do not infer a depletion path from an unordered table.

Pressure conventions differ across the surface: most regression experiment Javadocs say bar, viscosity uses bara, and report metadata uses bara. Treat the laboratory pressure basis as an input contract and convert deliberately.

5. Select bounded regression parameters

Choose only parameters with a defensible physical relationship to the observed residuals. Record for every parameter:

RegressionParameter.getDefaultBounds() returns library defaults, and addRegressionParameter(parameter) uses them. Defaults are not project approval. Prefer explicit, project-specific bounds when the data basis requires them. Avoid adding many weakly identifiable parameters solely to reduce the calibration objective.

6. Configure and run regression

Set experiment weights only after documenting the residual normalization and the relative importance of each data type. setExperimentWeight, setMaxIterations, setTolerance, and setVerbose configure the current framework. runRegression() rejects an empty parameter set and a run with no experimental data.

DLE Rs, Bo and oil density, and separator GOR and Bo, use the sample standard deviation $\sigma = \max(0.01|y|, 0.001)/w$, where $y$ is the observed value in the documented input units and $w$ is the experiment weight. The absolute floor keeps zero and near-zero observations finite. Above that floor, equal relative errors contribute equally across these properties. Previously, all five observables used the same absolute standard deviation, so large numerical values such as density dominated Bo. CCE, CVD and viscosity sample scaling is unchanged. This one-percent scale is a default fitting convention, not a statement of laboratory uncertainty.

Weights divide the standard deviation, so doubling a positive experiment weight quadruples its contribution to the least-squares sum. This preserves the existing weight convention. The per-experiment objective summaries remain separate diagnostics; they are not the weighted chi-square reported by the optimizer. The enabled PVTRegressionWeightingTest checks the registered sample scales, near-zero floor and weight convention.

Keep the base-fluid revision, data-preparation revision, parameter configuration, optimizer settings, software revision, and execution log together. Logging in maintained Java examples must remain Java 8 compatible and use Log4j2; console printing is not an accepted publication pattern.

7. Review calibration diagnostics

RegressionResult exposes the tuned fluid, objective values by experiment type, total objective, parameter configurations and optimized values, uncertainty information, confidence intervals, and the final chi-square value. Treat these as diagnostics of the configured optimization problem.

Calibration is not independent validation. A low objective value does not establish uniqueness, predictive accuracy outside the fitted observations, representative sampling, or fitness for a facility or reservoir decision. Examine residual structure, parameter-bound hits, parameter correlation, experiment balance, and sensitivity to initial guesses.

8. Validate before acceptance

Reserve hold-out observations or a separate experiment that was not used to tune the model. Apply the tuned fluid without changing parameters, then compare predictions using predeclared project-specific criteria. Where no independent data exist, state that limitation and use cross-validation or sensitivity cases as weaker evidence rather than calling the model validated.

Challenge the model across the intended pressure, temperature, composition, and depletion envelope. Investigate discontinuities, phase-identity changes, extrapolation, and sensitivity to laboratory uncertainty. Any engineering use must carry the validation range and unresolved limitations forward.

9. Report and hand off

For measured reservoir history, freeze independently accepted original/tuned models with CalibratedPvtModel, compare whole held-out laboratory experiments and supply an explicitly attributed MaterialBalancePvtHistory on the same separator basis. For measured component production/injection, CompositionalReservoirHistory instead replays the accepted EOS directly through SimpleReservoir, fitting only bounded initial pore volume with separate calibration and held-out pressure residuals. See the material-balance guide for units, interval assumptions, validation evidence and remaining limitations. See the material-balance handoff. The container requires externally evaluated, path-consistent PVT records; it does not automatically convert a constant-composition table into depletion PVT.

PVTReportGenerator accepts a fluid in its constructor. Its current metadata methods include setProjectInfo, setLabInfo, and setReservoirConditions; the latter takes reservoir pressure in bara and temperature in °C. Simulation results can be attached with addCCE, addDLE, addCVD, addSeparatorTest, and the other source-listed adders. generateMarkdownReport() produces the Markdown report, while dedicated CSV methods export supported result tables.

A handoff package should contain:

Use the dedicated black-oil PVT export guide or Eclipse E300 import guide for supported file workflows. The regression package does not provide an EclipseEOSExporter API.

Review checklist