neqsim-process-modeling

# 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. **Agree the model basis**: engineering question, battery limits, feed/assay, units, product specifications, data provenance and required fidelity. Follow [model-build-contract](references/model-build-contract.md) for every new or revised flowsheet; use its handoff checklist when another agent consumes it. 2. **Select the task pattern** from [oil-and-gas-task-patterns](references/oil-and-gas-task-patterns.md). Load only the relevant specialist skills. Discover additional capabilities rather than treating an equipment class name as proof of a validated application. For several platforms exchanging streams (hub plus satellites, shared export chain) load [multi-platform-complex](references/multi-platform-complex.md). 3. **Define fluids and feeds** with the EOS/component sequence in `neqsim-api-patterns`. Verify the EOS and phase options for the composition, pressure/temperature range and property being calculated. 4. **Assemble a reusable builder** with named streams/equipment, live outlet connections, explicit terminal products and one `ProcessSystem` per area. Return the process/plant and stream/equipment registries, not just numbers. 5. **Solve progressively**: establish the feed and once-through base case, close physical recycles, then add adjusters and operating constraints. Use `makeRecycles()` or `setAutoRecycles(true)` for supported mixer/manifold loops. For coupled models, check the boolean from `runUntilConverged(n)` and retain residual/iteration evidence. A returned `run()` call is not convergence proof. 6. **Validate each accepted case**: external total/component balances, energy closure where heat/work matters, phase identity, feasible equipment limits, independent benchmark and repeat/nearby-point behavior. Missing evidence stays incomplete; never insert zero as a closure result. 7. **Deliver reusable outputs** with explicit units, inputs, version, assumptions, data gaps, failed cases and validation evidence. Store notebooks/scripts in the task folder; publish sanitized examples only when requested. Do not silently fill composition, heavy-end characterization, maps, geometry, Cv, design limits or protection settings from generic defaults. A synthetic screening case may use labeled assumptions; an asset-specific verdict must identify missing decision-critical data. A thermodynamic operating-point model can answer duties without establishing installed capacity or safe operation. ## 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/interstage/export scrubber liquid outlet has a physical route to an appropriate pressure section or a declared external drain/product. Include required letdown/pumping and heat/work; a TP setter is not a physical pressure lift. Preserve all returns in recovery and boundary balances. Consult `neqsim-platform-modeling` for initialization patterns, with the routing and validation requirements in the model-build contract. - **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 affected pressure section.** Record design pressure/MAWP, PSV set pressure, operating pressure, protected equipment and source/reference conditions. Investigate discrepancies using the applicable project/code basis; do not excuse them with an invented rounding allowance or confuse set pressure with allowable accumulation. 2. **Relief adequacy against credible governing cases.** Use `neqsim-relief-flare-network` with documented scenarios, inflow and device data. Compare required capacity with installed capacity including applicable backpressure. A small relief load does not by itself establish adequate blowby protection or credit a shutdown function. Missing protection evidence remains a gap. 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. - `neqsim-future-operation-study` — per-year strategy, modification register and design-basis deviation register on top of a finished multi-year model. ## Diagnose unresolved recycles before accepting a plant result After `ProcessSystem.runUntilConverged(n)`, inspect `getRunStatus().isConverged()` and `getOpenRecycles()`. `RunStatus.isSuccess()` means execution did not fail; it does not prove numerical convergence. The status also names open loops, reports their count, the full-process pass count and a termination reason. Never accept repeated mass-balance values as a convergence criterion while loops