PVT forward-proxy surface process
Use the executable pvt_proxy workflow (neqsim pvt-proxy, or python -m pvt_proxy
from devtools/). It reuses NeqSim process equipment (Stream, Heater, Separator,
Mixer, Compressor) and closes reference loops with ProcessSystem.makeRecycles.
The orchestrator is @pvt-forward-proxy; the
guide is docs/pvtsimulation/pvt_forward_proxy.md.
Purpose boundary: the proxy defines the surface separation for PVT-table generation.
It is not a molar-production allocation method and does not replace the Eclipse to
FluidMagic to OLGA to NeqSim production workflow. Say so in every deliverable.
Entry points
neqsim pvt-proxy example recompression --out proxy.yaml # or: synthetic
neqsim pvt-proxy run proxy.yaml --out <task>/step2_analysis/pvt_proxy --strict
neqsim pvt-proxy evaluate <out>/proxy_definition.yaml proxy.yaml --fluids new_fluids.json --out eval.csv
neqsim pvt-proxy export <out>/proxy_definition.yaml --target e300 --target pvtsim --out exports
--strict exits 2 when the fit status is review_required. --resume restarts from
checkpoint.json only when the configuration hash matches. Reference results are cached
in reference_cache.json by reference, feed, standard conditions, template and composition.
Skill 1 - build_neqsim_process (reference and proxy)
reference.type: recompression: decreasing-pressure stages, plus gas-handling steps
(gas_sources, scrubber_pressure_bara (alias discharge_pressure_bara),
cooler_temperature_C, liquid_return_stage). A compressor is inserted only when the
scrubber pressure is above every source pressure; otherwise the step is a suction cooler and
scrubber. Optional gas_return: {to_stage, rate_Sm3_h} returns a fixed gas rate (gas lift).
Keep recycle_tolerance at 1e-6. The default 1e-2 tear tolerance of makeRecycles() leaves
0.1-0.3 % mass imbalance and biases the stock-tank oil. A reference above
max_mass_balance_error (1e-4) is failed.
- Several scrubber liquids returning to the same separator need one tear each.
AutoRecycleBuilder before 2026-11-08 tore only the first (2-23 % mass imbalance); use a NeqSim
build with the fix.
- Gas lift, fuel gas and anti-surge recycles do not change the products when every vessel is at
fixed P and T: the recirculated equilibrium gas forms a linear internal loop. Take the separator
temperature from the solved plant, because that is where gas-lift heating acts.
reference.type: python with callable: "module:function" (module next to the config)
for an existing NeqSim model. It receives (fluid, feed, standard_conditions, JClass)
and returns oil_Sm3_h and gas_Sm3_h on the same product definitions.
reference.type: forward is a known forward train, for recovery tests only.
- Proxy: forward
stages plus an optional scrubber (gas_sources,
liquid_destination = a later stage or stock_tank). A backward destination is a
recycle and is rejected. Each P/T is a fixed number or {value, lower, upper}.
- Product definitions are identical for reference and proxy: oil = stock-tank liquid
(EOS density) at standard conditions; gas = all gas leaving, including stock-tank gas,
as ideal-gas Sm3; same feed molar rate. Water is excluded from the ensemble.
Skill 2 - generate_fluid_ensemble
- One
fluids.template for all fluids: components (library names, TBP pseudo
components with mw_kg_mol and density_g_cm3), e300, or factory: "module:function"
returning a characterized NeqSim fluid. Use the factory to reuse a tuned project EOS (custom Tc,
Pc, acentric factor, volume shift and kij) unchanged; the module must sit next to the config.
This keeps the component mapping stable across all simulations.
base_fluids are named compositions (dict by component name, or a list in template order;
sum to 1 within 1e-3). Methods: explicit,
mixing (endmembers, n or gas_fractions), variation (base, n,
relative_range, seed), depletion (CVD: base, reservoir_temperature_C,
decreasing pressures_bara, optional liquid_recombination).
- Cover the field-life range from the heaviest oil to the lightest gas with at least 30
fluids. Steps rejected during generation are kept in
fluids.json with a reason.
fluids.weights sets operational importance per fluid id. Report the weights used.
Skill 3 - calibrate_forward_proxy
- One common parameter vector for all fluids. Never fit per fluid.
- Default objective: weighted normalized least squares on oil and gas rates, with oil
weight 2, gas weight 1, GOR weight 0 (diagnostic), soft-L1 loss, oil floor
eps_oil_fraction 0.05 of the median oil, and fluids above GOR 15 000 weighted 0.25.
Do not optimize GOR alone: super-dry gas would dominate and bias oil at moderate GOR.
- Default optimizer
de+lsq. Keep fd_step at about 1e-3 (unit box): flash noise is
about 1e-6 in the normalized residuals, and a 1e-4 step stalls the least-squares
refinement short of the optimum.
- Invalid pressure sequences are rejected without simulation. Failed proxy runs are
penalized (
failed_penalty) and reported, never dropped.
Skill 4 - validate_proxy
Read validation_report.md, validation_per_fluid.csv and validation_summary.json:
- Report oil, gas and GOR errors separately (MAPE, bias, P50/P90, max), by fluid class
and for the worst fluids. Report failed cases with their reasons.
- Dominance: a flagged fluid or dry-gas group means the weighting must be revisited.
- Identifiability: rates usually determine only some stage conditions. Variables
marked "poorly" (resolution with the others re-fitted above a quarter of the range)
must be reported with their resolution. Fix them from the design basis, or set a small
objective.prior_weight (for example 1e-5). Do not present them as measured values.
- Variables "at bound": the optimum lies on the bound. Widen the bound only when the
value is physically realistic. A cold scrubber bound usually means the forward proxy
is compensating for condensate that the reference recycles back into the oil.
pass / review_required follows acceptance (oil/gas MAPE, oil P90, failed count,
dominance). Use evaluate for new fluids: outside the stored calibration range it
warns about extrapolation.
Skill 5 - export_pvt_configuration
proxy_definition.yaml/.json is the single source. It holds the stages, scrubber,
routing, flow sequence with liquid/vapour destinations, standard conditions, units, the
exact objective and weights, optimizer settings, fit metrics, calibration range, status,
fit timestamp, software version and git commit. Exporters: neqsim (fixed proxy block),
e300 (SEPCOND-style table; check the item order against the simulator manual),
pvtsim/fluidmagic (separator-test JSON and stage CSV), blackoil/olga (stage CSV
and conditions note). Add a target by registering a function in pvt_proxy.export.EXPORTERS.
Verified behaviour (example configurations)
synthetic_three_stage.yaml: with HP pressure and LP temperature free from wrong
starts, the fit recovers 60.000 bara and 35.000 degC. Freeing MP or LP pressure as well
produces a flat valley, and the identifiability table flags it.
recompression_reference.yaml: 41 fluids (black oil to super-dry gas, CVD), two
recompression loops. The fit gives oil MAPE 0.05 % and gas 0.02 % in about 90 s,
with the scrubber temperature at its lower bound.
- A producing installation (plant model with three scrubbers returning condensate to one separator, gas lift;
46 fluids, GOR 125-6 960): separator-only proxies give 1.4-1.6 % oil MAPE (up to 6 %). One
separator plus scrubber gives 0.06 % with all four conditions identifiable, so compare a scrubber
topology first when the plant returns condensate. Hold-out fluids beyond the training GOR lost up
to 5 % oil, so include the leanest late-life fluids. Warmer suction coolers (+8 C) biased oil by
+1.8 %, so refit per cooling regime.
- Run candidates one after another (or in separate out folders) in OneDrive task folders; the sync
client can lock freshly copied files and make a run exit early.
Related
neqsim-forward-separator-train (community skill) runs one fluid through a fixed
forward train, or fits stage P/T to reservoir-simulator rates.
- neqsim-process-modeling for building a detailed
reference process to plug in via
reference.type: python.
- neqsim-optimization-and-doe for broader
optimizer selection.
1---2name: neqsim-pvt-forward-proxy3version: "0.1.0"4description: "Fits ONE forward (no-recycle) separator/scrubber P/T set so a proxy surface process reproduces the standard oil and gas rates of a detailed NeqSim process with recycle over a 30-100 fluid ensemble, for PVT tables in Eclipse 300, PVTsim, FluidMagic, OLGA and black-oil tools. USE WHEN: recycle/reflux must become a forward separator train, separator-test or SEPCOND conditions need calibrating, or neqsim pvt-proxy is requested."5last_verified: "2026-11-08"6requires:7 python_packages: [pyyaml, jpype1, numpy, scipy, matplotlib]8metadata:9 source: https://skillmd.com/skills/equinor/neqsim-pvt-forward-proxy10---1112# PVT forward-proxy surface process1314Use the executable `pvt_proxy` workflow (`neqsim pvt-proxy`, or `python -m pvt_proxy`15from `devtools/`). It reuses NeqSim process equipment (`Stream`, `Heater`, `Separator`,16`Mixer`, `Compressor`) and closes reference loops with `ProcessSystem.makeRecycles`.17The orchestrator is [@pvt-forward-proxy](../../agents/pvt-forward-proxy.agent.md); the18guide is [docs/pvtsimulation/pvt_forward_proxy.md](../../../docs/pvtsimulation/pvt_forward_proxy.md).1920Purpose boundary: the proxy defines the surface separation for **PVT-table generation**.21It is not a molar-production allocation method and does not replace the Eclipse to22FluidMagic to OLGA to NeqSim production workflow. Say so in every deliverable.2324## Entry points2526```bash27neqsim pvt-proxy example recompression --out proxy.yaml # or: synthetic28neqsim pvt-proxy run proxy.yaml --out <task>/step2_analysis/pvt_proxy --strict29neqsim pvt-proxy evaluate <out>/proxy_definition.yaml proxy.yaml --fluids new_fluids.json --out eval.csv30neqsim pvt-proxy export <out>/proxy_definition.yaml --target e300 --target pvtsim --out exports31```3233`--strict` exits 2 when the fit status is `review_required`. `--resume` restarts from34`checkpoint.json` only when the configuration hash matches. Reference results are cached35in `reference_cache.json` by reference, feed, standard conditions, template and composition.3637## Skill 1 - build_neqsim_process (reference and proxy)3839- `reference.type: recompression`: decreasing-pressure `stages`, plus gas-handling steps40 (`gas_sources`, `scrubber_pressure_bara` (alias `discharge_pressure_bara`),41 `cooler_temperature_C`, `liquid_return_stage`). A compressor is inserted only when the42 scrubber pressure is above every source pressure; otherwise the step is a suction cooler and43 scrubber. Optional `gas_return: {to_stage, rate_Sm3_h}` returns a fixed gas rate (gas lift).44 Keep `recycle_tolerance` at 1e-6. The default 1e-2 tear tolerance of `makeRecycles()` leaves45 0.1-0.3 % mass imbalance and biases the stock-tank oil. A reference above46 `max_mass_balance_error` (1e-4) is failed.47- Several scrubber liquids returning to the same separator need one tear each.48 `AutoRecycleBuilder` before 2026-11-08 tore only the first (2-23 % mass imbalance); use a NeqSim49 build with the fix.50- Gas lift, fuel gas and anti-surge recycles do not change the products when every vessel is at51 fixed P and T: the recirculated equilibrium gas forms a linear internal loop. Take the separator52 temperature from the solved plant, because that is where gas-lift heating acts.53- `reference.type: python` with `callable: "module:function"` (module next to the config)54 for an existing NeqSim model. It receives `(fluid, feed, standard_conditions, JClass)`55 and returns `oil_Sm3_h` and `gas_Sm3_h` on the same product definitions.56- `reference.type: forward` is a known forward train, for recovery tests only.57- Proxy: forward `stages` plus an optional `scrubber` (`gas_sources`,58 `liquid_destination` = a later stage or `stock_tank`). A backward destination is a59 recycle and is rejected. Each P/T is a fixed number or `{value, lower, upper}`.60- Product definitions are identical for reference and proxy: oil = stock-tank liquid61 (EOS density) at standard conditions; gas = all gas leaving, including stock-tank gas,62 as ideal-gas Sm3; same feed molar rate. Water is excluded from the ensemble.6364## Skill 2 - generate_fluid_ensemble6566- One `fluids.template` for all fluids: `components` (library names, TBP pseudo67 components with `mw_kg_mol` and `density_g_cm3`), `e300`, or `factory: "module:function"`68 returning a characterized NeqSim fluid. Use the factory to reuse a tuned project EOS (custom Tc,69 Pc, acentric factor, volume shift and kij) unchanged; the module must sit next to the config.70 This keeps the component mapping stable across all simulations.71- `base_fluids` are named compositions (dict by component name, or a list in template order;72 sum to 1 within 1e-3). Methods: `explicit`,73 `mixing` (`endmembers`, `n` or `gas_fractions`), `variation` (`base`, `n`,74 `relative_range`, `seed`), `depletion` (CVD: `base`, `reservoir_temperature_C`,75 decreasing `pressures_bara`, optional `liquid_recombination`).76- Cover the field-life range from the heaviest oil to the lightest gas with at least 3077 fluids. Steps rejected during generation are kept in `fluids.json` with a reason.78- `fluids.weights` sets operational importance per fluid id. Report the weights used.7980## Skill 3 - calibrate_forward_proxy8182- One common parameter vector for all fluids. Never fit per fluid.83- Default objective: weighted normalized least squares on oil and gas rates, with oil84 weight 2, gas weight 1, GOR weight 0 (diagnostic), soft-L1 loss, oil floor85 `eps_oil_fraction` 0.05 of the median oil, and fluids above GOR 15 000 weighted 0.25.86 Do not optimize GOR alone: super-dry gas would dominate and bias oil at moderate GOR.87- Default optimizer `de+lsq`. Keep `fd_step` at about 1e-3 (unit box): flash noise is88 about 1e-6 in the normalized residuals, and a 1e-4 step stalls the least-squares89 refinement short of the optimum.90- Invalid pressure sequences are rejected without simulation. Failed proxy runs are91 penalized (`failed_penalty`) and reported, never dropped.9293## Skill 4 - validate_proxy9495Read `validation_report.md`, `validation_per_fluid.csv` and `validation_summary.json`:9697- Report oil, gas and GOR errors separately (MAPE, bias, P50/P90, max), by fluid class98 and for the worst fluids. Report failed cases with their reasons.99- **Dominance:** a flagged fluid or dry-gas group means the weighting must be revisited.100- **Identifiability:** rates usually determine only some stage conditions. Variables101 marked "poorly" (resolution with the others re-fitted above a quarter of the range)102 must be reported with their resolution. Fix them from the design basis, or set a small103 `objective.prior_weight` (for example 1e-5). Do not present them as measured values.104- Variables "at bound": the optimum lies on the bound. Widen the bound only when the105 value is physically realistic. A cold scrubber bound usually means the forward proxy106 is compensating for condensate that the reference recycles back into the oil.107- `pass` / `review_required` follows `acceptance` (oil/gas MAPE, oil P90, failed count,108 dominance). Use `evaluate` for new fluids: outside the stored calibration range it109 warns about extrapolation.110111## Skill 5 - export_pvt_configuration112113`proxy_definition.yaml/.json` is the single source. It holds the stages, scrubber,114routing, flow sequence with liquid/vapour destinations, standard conditions, units, the115exact objective and weights, optimizer settings, fit metrics, calibration range, status,116fit timestamp, software version and git commit. Exporters: `neqsim` (fixed proxy block),117`e300` (SEPCOND-style table; check the item order against the simulator manual),118`pvtsim`/`fluidmagic` (separator-test JSON and stage CSV), `blackoil`/`olga` (stage CSV119and conditions note). Add a target by registering a function in `pvt_proxy.export.EXPORTERS`.120121## Verified behaviour (example configurations)122123- `synthetic_three_stage.yaml`: with HP pressure and LP temperature free from wrong124 starts, the fit recovers 60.000 bara and 35.000 degC. Freeing MP or LP pressure as well125 produces a flat valley, and the identifiability table flags it.126- `recompression_reference.yaml`: 41 fluids (black oil to super-dry gas, CVD), two127 recompression loops. The fit gives oil MAPE 0.05 % and gas 0.02 % in about 90 s,128 with the scrubber temperature at its lower bound.129- A producing installation (plant model with three scrubbers returning condensate to one separator, gas lift;130 46 fluids, GOR 125-6 960): separator-only proxies give 1.4-1.6 % oil MAPE (up to 6 %). One131 separator plus scrubber gives 0.06 % with all four conditions identifiable, so compare a scrubber132 topology first when the plant returns condensate. Hold-out fluids beyond the training GOR lost up133 to 5 % oil, so include the leanest late-life fluids. Warmer suction coolers (+8 C) biased oil by134 +1.8 %, so refit per cooling regime.135- Run candidates one after another (or in separate out folders) in OneDrive task folders; the sync136 client can lock freshly copied files and make a run exit early.137138## Related139140- `neqsim-forward-separator-train` (community skill) runs one fluid through a fixed141 forward train, or fits stage P/T to reservoir-simulator rates.142- [neqsim-process-modeling](../neqsim-process-modeling/SKILL.md) for building a detailed143 reference process to plug in via `reference.type: python`.144- [neqsim-optimization-and-doe](../neqsim-optimization-and-doe/SKILL.md) for broader145 optimizer selection.