neqsim-process-modeling

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.
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.

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.

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).

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 + pattern.

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.