neqsim-process-modeling git:20260919.77c34a0A

Immutable. This exact content never changes and is served at /api/v1/blob/d8a2072fc808f65d.

---
name: neqsim-process-modeling
description: "Process modeling and flowsheet construction patterns for NeqSim. USE WHEN: building executable NeqSim process simulations, ProcessSystem flowsheets, or runnable process models with streams, separators, compressors, heat exchangers, valves, pumps, distillation columns, recycles, adjusters, topology checks, result extraction, and engineering validation - for example a multi-stage gas compression train with intercooling, an HP/LP separation train, or a gas treatment unit."
last_verified: "2026-08-29"
---

# NeqSim Process Modeling Skill

Build executable NeqSim process simulations from engineering descriptions. This skill
is the process-flowsheet layer between thermodynamic fluid setup and downstream
specialists such as mechanical design, safety, plant data, and reporting.

## Use When

- Building a `ProcessSystem` or `ProcessModel` flowsheet from a process description.
- Connecting equipment such as streams, separators, compressors, coolers, heaters,
  heat exchangers, pumps, valves, pipes, mixers, splitters, recycles, adjusters, and
  distillation columns.
- Extracting process results with units, compositions, duties, powers, phase splits,
  mass balances, energy balances, or equipment profiles.
- Preparing a steady-state process base case for mechanical design, relief sizing,
  flow assurance, dynamic simulation, plant-data comparison, or optimization.

## Core Workflow

1. **Define the fluid** using the EOS and component sequence from
   `neqsim-api-patterns`.
2. **Create feed streams** with explicit temperature, pressure, and flow units.
3. **Add equipment in topological order** to a `ProcessSystem`.
4. **Connect by outlet stream objects**, for example separator gas outlet to
   compressor inlet or valve outlet to downstream separator.
5. **Run once after assembly** unless recycle initialization requires a staged solve.
6. **Validate results** using conservation checks, phase sanity checks, equipment
   limits, and applicable standards.
7. **Report outputs with units** and include assumptions for missing design data.

## Modeling Choices

| Situation | Recommended Pattern |
|-----------|---------------------|
| Single train, linear or branched flowsheet | One `ProcessSystem` |
| Multiple areas with cross-area streams | Multiple `ProcessSystem` objects in a `ProcessModel` |
| Production / gathering / commingling / export **manifold** or inlet header | `Manifold` (`process.equipment.manifold.Manifold`) — NOT `Mixer`/`Splitter` |
| PFD/P&ID or unstructured text input | Use `neqsim-process-extraction` first |
| Distillation or fractionation | Load `neqsim-distillation-design` |
| Startup, shutdown, controllers, inventory dynamics | Load `neqsim-dynamic-simulation` |
| Turndown or control valve operability | Load `neqsim-controllability-operability` |
| Platform-scale separation/recompression | Load `neqsim-platform-modeling` |

**Manifolds:** always model a well/production/gathering/commingling/export
manifold (or an inlet/outlet header) with the `Manifold` class, not a plain
`Mixer` or `Splitter`. Add the routed inlet streams with `addStream(...)`. **A
manifold ALWAYS has split outlets — route downstream from a split stream, never
from `getMixedStream()`.** If the manifold feeds a single destination, give it
one split (`setSplitFactors([1.0])`) and route its `getSplitStream(0)`. For a
distributing manifold set `setSplitFactors([f0, f1, ...])` (fractions summing to
1) and read each branch with `getSplitStream(i)`. `getMixedStream()` returns only
the internal commingled stream (all inlets combined, before the split) — use it
for inspection, not for wiring downstream. The `Manifold` also carries
header/branch inner diameters (`setHeaderInnerDiameter`, `setBranchInnerDiameter`)
for hydraulics and mechanical design.

## Data Basis for an Optimization-Ready Model

A model built only to *run* has fixed operating points. A model built to
**optimize** additionally needs a bounded decision space, equipment constraints,
and an objective. Gather this basis up front (and record every assumed value):

- **Fluid & feed** — composition(s) + PVT/assay (C7+); feed rate, T, P, water
  cut/GOR per feed; EOS + mixing rule.
- **Geometry & hydraulics** — **line sizes** (ID, schedule/wall, length, elevation,
  roughness, insulation), **manifold/header sizes**, separator/scrubber dimensions
  (ID, T/T length, orientation, nozzle sizes), heat-exchanger area/UA.
- **Valves & chokes** — **control-valve Cv/Kv, rated travel, characteristic,
  opening**; **choke Cv-vs-opening (bean/trim)** for wells and let-down; ESD sizes.
- **Rotating equipment** — compressor maps (head/eff vs flow at several speeds) +
  design/max speed; pump curves (+ NPSHr); driver rating (GT/motor); anti-surge
  config (surge line, control-line margin, recycle-valve Cv).
- **Design limits → constraints** — separator design gas-load K + residence time;
  compressor rated power, surge/stonewall margins, max discharge T; pump power +
  NPSHa; line erosional-velocity limit; design P/T; valve max Cv; MAWP; PSV set P.
- **Decision space & control** — manipulable setpoints with **physical bounds**
  (stage pressures, temperatures, compressor discharge P or speed, split/routing);
  **compressor control mode** (solve-speed vs predictive — see
  `neqsim-agentic-process-optimization`); pre-wired adjusters (do not also optimize).
- **Objective & economics** — objective (max throughput / min power / max value /
  min emissions); product specs as constraints (RVP, dew point, cricondenbar,
  Wobbe); prices / power & fuel cost / CO2 price for value objectives.

Source geometry and Cv from the line list, valve/choke datasheets, and instrument
index; maps from vendor curve sheets; limits from datasheets + piping class. For
the governed enterprise checklist and readiness gates use
`enterprise-process-model-build-verify` (`target_fidelity="optimization_ready"`).

For MCP `runProcess` compressor protection, keep embedded compressor
`antiSurge` as screening control only. Use root-level `antiSurgeSystems` when
the model must bind `CompressorAntiSurgeApplication` to explicit named hot/cold
recycle valves, cooler, suction mixer, and recycle blocks. Multi-area systems
must include `area`. Follow `neqsim-compressor-antisurge-recycle` for the JSON
contract, screening-map provenance, commissioning evidence, and the mandatory
`NOT_CERTIFIED_FOR_PROTECTION` boundary.

## Per-Area Three-Phase Flash Control (Speed-Up)

Switch the multiphase (three-phase) flash off on areas that are known to be
two-phase only. On a multi-area plant this is usually the cheapest speed-up
available, because the extra phase-stability analysis otherwise runs on every
flash of every unit of every recycle iteration.

```java
plant.setMultiPhaseCheck(true);                    // baseline for all areas
plant.setMultiPhaseCheck("Export train A", false); // dry gas: no third phase
compressionTrain.setMultiPhaseCheck(false);        // a single ProcessSystem
```

- `ProcessSystem.setMultiPhaseCheck(boolean)` returns the number of distinct
  fluids updated; `getMultiPhaseCheck()` returns `TRUE`/`FALSE`/`null` (unset).
- `ProcessModel.setMultiPhaseCheck(String areaName, boolean)` returns `-1` for an
  unknown area name — check it, do not assume the call landed.
- The setting is re-applied at the start of each run, so a `ThreePhaseSeparator`
  temporarily enabling the check cannot leak three-phase mode into the area.
- Default is unset: fluids keep whatever flag they were built with.

**Only disable it where the absence of a third phase is known from the process,
not assumed.** Free water, an aqueous glycol/MEG phase, or a liquid CO2 phase
will be silently missed. Keep the check ON for inlet separation, produced-water,
glycol/MEG, and CO2-rich areas.

## Per-Area Property-Initialization Level (Speed-Up)

Every `Stream.run()` ends with `initProperties()`, which evaluates mass density,
viscosity, thermal conductivity and diffusivity. Selecting `DENSITY_ONLY` skips
the transport-property correlations and is roughly an order of magnitude cheaper
per stream.

```java
plant.setPropertyInitLevel(Stream.PropertyInitLevel.DENSITY_ONLY); // whole plant
plant.setPropertyInitLevel("Subsea", Stream.PropertyInitLevel.FULL); // one area
compressionTrain.setPropertyInitLevel(Stream.PropertyInitLevel.DENSITY_ONLY);
feedStream.setPropertyInitLevel(Stream.PropertyInitLevel.FULL);      // one stream
```

- Same API shape as `setMultiPhaseCheck`: `ProcessSystem.setPropertyInitLevel`
  returns the number of streams updated, `ProcessModel.setPropertyInitLevel(area,
  level)` returns `-1` for an unknown area, the setting propagates into nested
  `ModuleInterface` sub-processes, is applied to units added afterwards, and is
  re-applied at the start of every run.
- Default is unset (`null`): each stream keeps `PropertyInitLevel.FULL`.

> **⚠ `DENSITY_ONLY` makes transport properties read back as ZERO, not throw.**
> `getViscosity()`, `getThermalConductivity()` and the diffusion coefficients
> return `0.0`. That silently corrupts pipeline pressure drop, heat-exchanger UA,
> mechanical design, and every flow-assurance calculation. Use it only for
> mass/energy-balance solves, and set the level back to `FULL` (or call
> `getFluid().initProperties()` on the stream) before reading transport
> properties.

Both switches are re-applied by `run(UUID)`, `run_step(UUID)`,
`runSequential(UUID)`, `runParallel(UUID)`, `runHybrid(UUID)`,
`runDataflow(UUID)` and `runTransient(double, UUID)`.

## Closing Feedback Loops Automatically (`makeRecycles`)

Do **not** hand-write a tear stream (`Stream` clone + `Recycle`) per feedback
stream any more. A loop wired straight back into an upstream mixer, with no
`Recycle` in it, is an *implicit tear*: it converges only through the surrounding
sweep, so it has no tolerance, no acceleration and no convergence report. Across
`ProcessModel` areas it is worse — a stream produced by an area that runs after its
consumer is closed only by the outer Gauss-Seidel pass, which has no relaxation
setting, so the plant residual sits on a floor no tolerance can reach.

```python
created = process.makeRecycles()        # ProcessSystem — SCCs of one flowsheet
created = plant.makeRecycles()          # ProcessModel — cross-area streams, then each area
plant.setAutoRecycles(True)             # or let run()/runUntilConverged() do it
```

- Tear point = inlet with the smallest **recycle ratio** (tear flow / total inlet
  flow of the consuming unit), which sets the contraction rate of the tear. One edge
  torn per round, structure recomputed after — nested cycles get the minimum number
  of tears.
- Generated recycles start on direct substitution with `setAdaptiveAcceleration(true)`
  (never pin `setAccelerationMethod(...)` — that sets `accelerationMethodExplicit` and
  disables the self-upgrade) plus an absolute flow tolerance at 1e-6 of the area's
  largest flow, so a near-zero leg converges on absolute change.
- Self-seeding (runs once when streams have no fluid) and idempotent — call order is
  not your problem, repeat calls insert nothing.
- Only `Mixer` and `Manifold` inlets are tearable (`replaceStream(int, StreamInterface)`).
  Loops closing on other equipment are logged and left alone; route them through a mixer.
- `setAutoRecycles` defaults to **false**: inserting a tear changes how an existing
  flowsheet iterates, so it must be opted into.

## Required Checks

- Temperatures and pressures use explicit units in setters.
- Fluids have a mixing rule before simulation.
- Branching streams use cloned fluids or well-defined equipment outlet streams.
- Phase-separating equipment exposes conventional gas/liquid product accessors;
  domain aliases return those same objects rather than separate streams.
- `getInletStreams()` and `getOutletStreams()` contain every externally connected,
  live stream. Their entries remain object-identical across reruns so downstream
  equipment never retains a stale product reference.
- After solving a phase separator or column, verify the gas outlet contains a gas
  phase, the liquid outlet contains an oil/liquid/aqueous phase, and total plus
  per-component balances close. Getter existence alone is not product validation.
- Every equipment item has a unique name inside the process.
- Recycles and adjusters are added after their connected equipment.
- **Pick the separator class by orientation, or set it explicitly.** Gas-capacity
  results depend on orientation because a horizontal vessel derates the gas area by
  the design liquid level (default 80% → gas area `(1−0.8)=0.2×`, a **5× over-read**
  of gas velocity / `getGasLoadFactor()` if used for a vertical vessel):
  - `Separator` and `ThreePhaseSeparator` default to **horizontal** — use for the
    horizontal 1st/2nd/3rd-stage separators (VA-tag).
  - `GasScrubber`, `GasScrubberSimple`, `NeqGasScrubber` (2-phase) and
    `ThreePhaseGasScrubber` (3-phase) default to **vertical** — prefer these for
    vertical scrubbers (VG-tag); their constructor calls `setOrientation("vertical")`.
  - Either way you can override with `separator.setOrientation("vertical"|"horizontal")`.
  Verified: with the correct orientation, `getGasLoadFactor()` matches a hand
  Souders-Brown `v·sqrt(ρg/(ρl−ρg))`. `setInternalDiameter()` itself propagates
  correctly through `run()` — the trap is orientation, not diameter.
- Every suction/export scrubber in a recompression/export-compression train has its
  liquid knock-out (`scrubber.getLiquidOutStream()`) closed back to the separator
  operating at the matching pressure — never leave it unconnected (it is silently
  dropped, under-counting oil/condensate recovery). See `neqsim-platform-modeling`
  Section 4 for the seed + TP-setter + `Recycle` pattern.
- **Overall mass balance MUST be verified before accepting any solution.** Sum the mass
  flow (`kg/hr`) of all feed streams and all product/export streams; the closure error
  must be `< 0.1 %` (`abs(sum_in - sum_out) / sum_in`). A larger imbalance means a stream
  was dropped (e.g. an unconnected scrubber liquid), a recycle did not converge, or a
  splitter fraction is wrong — fix the flowsheet and re-run; do NOT report results from an
  unbalanced model. For multi-area `ProcessModel`s, also confirm `plant.run()` converged.
- Results include the verified mass balance, expected pressure ordering, and physically
  reasonable phase splits.
- For industrial engineering use, assess every exact `method@version` with
  `EngineeringMethodQualificationRegistry`: require an independent benchmark, approved structured applicability
  envelope, intended use, controlled service inputs, uncertainty basis and explicit extrapolation policy. A converged
  calculation outside the envelope remains investigation evidence, not a qualified engineering result.
- Use `EngineeringNumericalHealthAnalyzer` to capture convergence, mass/energy closure, residual, and sensitivity
  evidence for every process state that governs an engineering decision. Required but absent evidence must remain
  `INCOMPLETE`; never replace unavailable closure data with zero.
- Use `Dexpi20XmlWriter` for native Plant/P&ID exchange and `Dexpi20ProcessModelWriter` for native Process/PFD/BFD
  exchange. A Proteus document with a changed header is not native DEXPI 2.0. Preserve the conformance report and still
  require a named-CAE round-trip before project qualification.
- Keep an explicitly registered terminal product as `new Stream(productName, upstreamOutlet)` when the product must
  remain a named topology node. NeqSim reports the wrapped outlet as that stream's inlet and the DEXPI Process exporter
  maps the node to a sink. Zero-flow and isolated empty streams must not be deleted merely to avoid invalid empty port
  collections.
- An isolated `new Stream(name)` with no fluid runs as an inactive topology placeholder. Do not connect downstream
  thermodynamic equipment to that placeholder until a real fluid state is assigned.
- Use `Cfihos20HandoverExporter` only with an exact project-controlled CFIHOS 2.0 Core or Extended RDL delivery.
  Verify its digest from controlled bytes, map canonical nodes/properties/documents to exact RDL identifiers, record
  mapping approval, and close the generated gap register. Its CSVs are staging data; Principal transformation,
  target-system validation, contractual completeness, and information acceptance remain external decisions.
- Compressor, pump, heat exchanger, separator, and pipeline cases identify applicable
  standards through `neqsim-standards-lookup`.

## Process Safety Is Part of a Capacity or Tie-in Study

A capacity, debottlenecking or tie-in study that reports only throughput is
incomplete, and in an oil-and-gas setting it will not pass review. **More flow
through a plant changes its relief demand, its blowdown inventory and its
overpressure exposure.** Run these checks in the same study, not as a follow-on:

1. **Overpressure protection per vessel.** For every vessel whose duty changes,
   tabulate design pressure, PSV set pressure and the measured operating
   pressure. Flag a set point above design (accumulation beyond the ASME VIII
   110 % single-device allowance) and a set point far below design (it probably
   protects a lower-rated downstream section — confirm which). Allow a rounding
   tolerance of about 1 % before calling a set point above design a
   non-conformance: design pressure and set pressure usually come from different
   documents.
2. **Relief adequacy against the governing case.** Size the relief with
   `neqsim-relief-flare-network` (API 520 Part I critical gas flow) and compare
   with the installed orifice. A PSV sized at a few percent of normal flow is
   normal for a thermal or blocked-outlet case — it means the protection against
   sustained gas blowby rests on the **shutdown system**, not the valve. Say so
   explicitly rather than implying the PSV covers full flow.
3. **Inflow bounding.** The maximum flow into each pressure step is set by the
   upstream chokes and control valves. Without a choke `Cv` the blowby and
   overpressure cases cannot be closed from first principles — record that as a
   gap rather than assuming a number.
4. **Blowdown.** Restriction-orifice sizes give the depressurisation time
   (`neqsim-depressurization-mdmt`); without them, state that time-to-blowdown is
   unknown.
5. **The safety meaning of an over-capacity vessel.** A separator or scrubber
   above its Souders-Brown gas-load limit carries liquid over into downstream
   equipment. That is a **safety** finding, not only a production one: liquid to
   a compressor, liquid to a dehydration bed, liquid to the flare KO drum. If a
   capacity calculation shows an exceedance, follow the carry-over path and say
   what it reaches.

**Ordering rule.** Establish the capacity answer first, then the safety
consequence of it — the safety question depends on which unit is loaded and by
how much. Reporting capacity without step 5 is the most common way a
throughput-increase study is quietly wrong.

**Data-retrieval expectations** (verified on an NCS platform): design pressure
and relief-device orifice/rated capacity are typically **not** tag attributes in
an engineering register — they live in the mechanical and relief data sheets and
often need OCR. Budget for that. Vessel *geometry* on a tag record may be an
L×W×H envelope rather than an internal diameter; **where a data sheet exists it
governs the tag field**, and the difference can move a utilisation result by tens
of percent.

## Related Skills

- `neqsim-api-patterns` — fluid setup, equipment APIs, and result extraction.
- `neqsim-input-validation` — pre-simulation physical bounds and component checks.
- `neqsim-troubleshooting` — flash and process convergence recovery.
- `neqsim-process-extraction` — JSON builder and route extraction from documents.
- `neqsim-notebook-patterns` — executable notebook structure and devtools setup.
- `neqsim-process-safety` — barrier, HAZOP, LOPA and SIL framing for the safety
  step above.
- `neqsim-relief-flare-network` — PSV sizing per API 520/521 and flare loads.
- `neqsim-depressurization-mdmt` — blowdown time and low-temperature screening.