# Neqsim Pvt Regression Characterization Factor

> Public weighted multi-target regression of a split/characterization factor against measured PVT and separator data (saturation pressure, GOR, stock-tank-oil density, formation volume factor). USE WHEN: a task must calibrate one heavy-end characterization factor so a fluid model reproduces several measured PVT/separator quantities at once, with per-target weights and residual reporting, before rigorous NeqSim EOS regression.

- Skill: `equinor/neqsim-pvt-regression-characterization-factor-2` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add equinor/neqsim-pvt-regression-characterization-factor-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/equinor/neqsim-pvt-regression-characterization-factor-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: equinor (https://skillmd.com/u/equinor)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/equinor/neqsim-pvt-regression-characterization-factor-2

---


# PVT Regression of a Characterization Factor

Use this skill to **regress a single split / characterization factor against
several measured PVT or separator targets at once**, with per-target weights and
explicit residual reporting. It follows standard PVT regression practice (fitting
EOS/characterization parameters to measured PVT experiment values with weights)
and NeqSim's characterization plus PVT-simulation workflow.

The forward model is **injected** by the caller, so this skill has no dependency
on a particular EOS. In practice it wraps a NeqSim characterization + flash /
PVT-simulation evaluation, or the community
`pseudocomponent-split-characterization` and `reference-fluid-synthetic-generation`
skills.

## When to Use

- When one heavy-end factor must reproduce **multiple** measured quantities
  (for example saturation pressure and stock-tank-oil density) simultaneously.
- When targets have **different importance** and need weighting.
- When you must report **per-target residuals** to judge whether the match is
  acceptable.
- When a full EOS regression is not warranted but a calibrated split factor is.

## Inputs

- `forward_model(factor) -> {target_name: predicted_value}`: caller-supplied.
- `targets`: a list of `RegressionTarget(name, measured, weight)`.
- `low`, `high`: bounds of the factor search interval.
- `tol`, `max_iter`: search controls.

## Outputs

- `RegressionResult`: fitted factor, objective, per-target residuals and
  predictions, iterations, and convergence flag.
- `weighted_ssr(predicted, targets)`: the weighted sum of squared relative
  residuals, usable as a standalone objective.

## Engineering Method

Each residual is normalized: `(predicted - measured) / measured`, so quantities
of different magnitude and units contribute comparably. The objective is the
weighted sum of squared relative residuals. The factor is fitted by a robust
golden-section 1-D search over `[low, high]` — no gradients, suitable for the
noisy forward models produced by flash and PVT calculations.

Typical targets and units:

| Target | Symbol | Typical unit |
| --- | --- | --- |
| Saturation pressure | `p_sat` | bara |
| Gas-oil ratio | `GOR` | Sm³/Sm³ |
| Stock-tank-oil density | `rho_STO` | kg/m³ |
| Oil formation volume factor | `Bo` | m³/Sm³ |

## Python Usage Pattern

```python
from pvt_regression import RegressionTarget, regress_characterization_factor

def forward(alpha):
    # Replace with a NeqSim characterization + PVT evaluation for this factor.
    fluid = build_fluid_with_split_factor(alpha)
    return {
        "p_sat": saturation_pressure_bara(fluid),
        "rho_STO": stock_tank_oil_density(fluid),
    }

targets = [
    RegressionTarget("p_sat", measured=248.0, weight=2.0),
    RegressionTarget("rho_STO", measured=832.0, weight=1.0),
]
result = regress_characterization_factor(forward, targets, low=0.6, high=3.0)
print(result.factor, result.residuals)
```

## Related NeqSim Functionality

- `neqsim.thermo.characterization.PlusFractionModel` / `PlusCharacterize` — the
  factor (`alpha`/`eta`) regressed here.
- `SystemInterface` + `ThermodynamicOperations` — saturation pressure
  (`bubblePointPressureFlash`), GOR and density via separator/flash calculations.
- For a full EOS parameter regression (kij, Tc, Pc, omega, volume shift), use the
  rigorous NeqSim PVT-simulation and tuning classes rather than this
  single-factor screening.

Pair this skill with `neqsim-pseudocomponent-split-characterization` (the split)
and `neqsim-reference-fluid-synthetic-generation` (generate the fluids).

## Validation Checklist

- Each measured target has a stated value, unit, source, and weight.
- The forward model returns every target name the regression expects.
- The returned `converged` flag is checked and per-target residuals are within a
  documented acceptable-match threshold.
- The fitted factor lies inside (not on) the search bounds; widen bounds if it
  sits at an endpoint.
- Assumptions and limitations are recorded and qualified PVT review is planned.

## Common Mistakes

- A forward model that omits a target name (raises a missing-prediction error).
- A measured value of zero (relative residual is undefined; raises).
- Passing `low >= high` (raises).
- Interpreting a single-factor fit as a full EOS regression.
- Reporting only the fitted factor: also show raw vs tuned vs lab per target, the
  per-sample *predicted* CME/DLE/viscosity error, and a bound flag when the factor
  is pinned at an endpoint (see Reporting tuning quality).
- Tuning an oil characterisation (universal P/A) to a gas-cap or gas-condensate
  sample: the GOR can be matched while the dew point and stock-tank density stay
  wrong. Mark such a fluid NOT TUNED instead of reporting the fit.
- Reusing a cloned NeqSim fluid across trials: clones share kij and volume-shift
  state, so rewrite both on every composition change or earlier trials leak in.

## Reporting tuning quality

Every use of a tuned fluid in a report needs: a per-fluid table of raw, tuned and
lab GOR, stock-tank density and saturation pressure with the fitted parameters and
bound flags; per-sample prediction error (Psat, GOR, STO, CME above/below Psat,
DLE Rs/Bo, viscosity) with mean and worst case; parity and CME/DLE overlay figures;
untuned or inconsistent samples named (a CME referenced to a pressure that differs
from the reported Psat is a lab inconsistency to flag, not to fit). Worked example:
Grane task 2026-10-06 `60_figures_tables.py`; reporting rule in
`neqsim-professional-reporting` Principle 9a.

Also required (Visund task 2026-10-06, `63_tuning_quality.py`):

- Compute the **untuned "before"** with the optimiser start values through the same
  quality function as the tuned "after" (gas: alpha 2, S 0.5, k 1; oil: S from the C7+ MW
  correlation, k 1) and tabulate before and after per sample.
- Give every experiment row a role: `fit target` or `check (not fitted)`. A check metric may
  get worse when a target improves (oil Psat -3 points after the GOR and density fit); say so.
- Process-level calibration (for example the produced-gas heavy-end leaning of the wellstream
  recombination) is not a PVT parameter: list it in `parameters` with fluid
  `wellstream recombination`, its bounds, and the benchmark role per window (calibrated,
  hold-out, fitted separately). Never absorb a PVT or allocation mismatch in one factor on the
  allocated oil: it closes the calibration window and fails the hold-outs.

## Limitations

- Screening-level and single-factor; it does not tune the full EOS.
- The caller's forward model determines physical accuracy.
- Acceptable-match criteria (residual thresholds) must be set by the engineer.
- Results require qualified PVT review before design or operational use.

## References

- Whitson, C.H., Brulé, M.R. (2000). *Phase Behavior*, SPE Monograph 20.
- Pedersen, K.S. et al. (2015). *Phase Behavior of Petroleum Reservoir Fluids*, 2nd ed.
- NeqSim: https://github.com/equinor/neqsim

