Dynamic Equipment Implementation
Use this skill when a NeqSim equipment class needs real dynamic simulation support instead of the default steady-state fallback or unsupported transient behavior.
This complements neqsim-dynamic-simulation, which explains how to run dynamic studies. This skill explains how to implement and test the Java code that makes equipment participate correctly in ProcessSystem.runTransient(dt, id).
Local Architecture
SimulationInterface.runTransient(double dt, UUID id) defaults to steady-state run(id) when getCalculateSteadyState() is true, otherwise throws UnsupportedOperationException.
ProcessSystem.runTransient(dt, id) steps each ProcessEquipmentInterface through a skip-aware wrapper and calls unit.runTransient(dt, id).
- Equipment that has real dynamic behavior must override
runTransient(double dt, UUID id).
- Existing reference implementations include
Separator, ThreePhaseSeparator, Tank, Compressor, ThrottlingValve, SafetyValve, BlowdownValve, PipeBeggsAndBrills, WaterHammerPipe, SimpleReservoir, and WellFlow.
- All dynamic equipment code must remain Java 8 compatible, use Log4j2 for logging, and pass Spotless formatting.
Implementation Decision Tree
Is the equipment purely algebraic?
- Examples: simple pressure drop, splitter ratio, ideal heater with no metal/fluid holdup.
- Implement only if needed to propagate controller or actuator dynamics; otherwise the steady-state fallback may be sufficient.
Does the equipment hold mass or energy inventory?
- Examples: separator, tank, column tray/section, adsorber bed, exchanger volume, pipe segment, reactor, accumulator.
- Add explicit volume/holdup state and integrate component moles and internal energy over
dt.
Does the equipment have actuator or mechanical state?
- Examples: compressor shaft speed, valve opening, pump ramp, fan speed, bed switching, recycle valve position.
- Add bounded state variables, ramp-rate limits, and controller hooks.
Does the equipment need thermal inertia?
- Examples: heat exchangers, heaters/coolers, fired heaters, reactors, pipes.
- Add fluid volume and optional wall/metal heat capacity. Preserve energy balance and avoid instant outlet jumps unless the equipment is intentionally algebraic.
Required Code Pattern
For any new transient implementation:
- Add serializable state fields with defaults that preserve existing steady-state behavior.
- Add public setters/getters for dynamic configuration such as volume, residence time, metal mass, ramp rate, or initial inventory.
- Override
runTransient(double dt, UUID id).
- Keep the steady-state branch first:
- If
getCalculateSteadyState() is true, call run(id), increaseTime(dt), set/finish the calculation identifier consistently with the class pattern, and return.
- Initialize transient state lazily on the first dynamic step from the last steady-state solution.
- Run controllers or actuator logic before solving the equipment response when the class exposes controller behavior.
- Integrate component and energy balances over the timestep:
- Accumulation = inlet rates minus outlet rates plus generation or consumption.
- Energy accumulation = inlet enthalpy rates minus outlet enthalpy rates plus heat/work terms.
- Clamp tiny negative mole inventories to zero; do not allow negative total volume, negative pressure, or invalid phase amounts.
- Re-flash the updated inventory with the appropriate flash operation (
TPflash, TVflash, PHflash, or VUflash) and call initProperties() or the class-equivalent physical-property initialization before reading transport properties.
- Update every outlet stream from the new state and preserve mass/energy consistency.
- Call
increaseTime(dt) and set the calculation identifier before returning.
Equipment Configuration Guidance
Dynamic behavior needs physical capacity. Prefer existing mechanical-design data when it already exists, but expose a simple runtime configuration path for simulations:
- Vessel-like equipment: volume, diameter, length, liquid level, gas headspace, max/min operating pressure.
- Heat-transfer equipment: process-side volume, optional utility-side volume, UA, metal mass, metal heat capacity, ambient heat loss.
- Rotating equipment: inertia, rated speed, ramp rates, driver power limit, recycle or minimum-flow logic.
- Valves and dampers: opening fraction, stroke time, fail action, Cv/characteristic, controller attachment.
- Pipes: length, diameter, roughness, elevation profile, segment inventory, heat-transfer environment.
- Reactors and beds: bed volume, void fraction, catalyst/solid heat capacity, reaction source terms, residence time.
Do not hide required dynamic capacity behind mechanical design only. Task notebooks and MCP workflows need direct, documented setters for dynamic parameters.
Testing Requirements
Create focused JUnit 5 tests under the matching package in src/test/java/neqsim/....
Minimum test coverage for each dynamic implementation:
- Steady-state compatibility:
runTransient(dt, id) with calculateSteadyState=true matches or preserves the existing run(id) behavior.
- Dynamic branch executes: with
calculateSteadyState=false, runTransient(dt, id) does not throw and advances equipment time.
- Inventory response: a flow, heat, pressure, valve-opening, speed, or level disturbance changes a physically relevant state in the expected direction.
- Mass balance: integrated inlet minus outlet accumulation matches inventory change within a reasonable tolerance.
- Energy or temperature response: when relevant, heat/work input changes internal energy, outlet temperature, or pressure consistently.
- Controller interaction: if the equipment has controllers, verify one timestep calls/runs controller logic and applies bounded output.
- Bounds and robustness: zero/low flow, empty inventory, small
dt, and repeated timesteps remain finite and non-negative.
- Serialization/copy safety: if new fields are non-serializable, mark them
transient; otherwise verify normal equipment copy behavior still works.
Use physical assertions, not private implementation details. Prefer monotonic or bounded assertions over fragile exact transient values unless a regression baseline is intentional.
Validation Commands
After editing Java files in the NeqSim repo, run:
mvnw.cmd spotless:apply
mvnw.cmd test "-Dtest=YourDynamicTest"
mvnw.cmd spotless:check
When public APIs or JavaDoc were added or changed, also run:
mvnw.cmd javadoc:javadoc
When only agent/skill files were edited, run:
uv run --project devtools --locked devtools/verify_skills_agents.py
uv run --project devtools --locked devtools/generate_agent_skill_map.py
uv run --project devtools --locked devtools/verify_skills_agents.py
Common Pitfalls
For TwoFluidPipe and related finite-volume code, include all three phase inventories in
rejection/positivity checks, even though the class name says two-fluid. Preserve phase identity
at exact water-cut endpoints and separate phase momenta through primitive/conservative recovery.
Distinguish explicit caller velocities from internal recovery: test legacy bulk updates after
recovery, recovered slip, and zero-to-positive phase appearance without overwriting donor momentum.
Pressure-correction face fluxes must share each donor phase's inventory budget. A positivity repair
that moves mass between phases can hide a phase-balance defect behind an exact total-mass balance.
Source-splitting helpers must not run primitive recovery on an invalid trial before its rejection
check; exercise the same negative-phase test with stiff source terms enabled.
Rollback must restore configured closures and their accepted diagnostics, pressure and phase
densities as well as the state vector; a generic clone may discard transient closure fields.
Pressure and density must use the same applied correction after bounds. Independent cell clipping
can reverse Newton face directions and make an upwind active set cycle; test bounded convergence.
A substep budget
must never enlarge a CFL-limited step or silently truncate a requested interval; compare accepted
time with both equipment and solver clocks. Tracker overlay inventory is separate from Eulerian
inventory, so dissolution must not return mass that initialization never withdrew. Read
docs/wiki/two_fluid_reporting_and_validation.md for the distinction between numerical regression
coverage and currently disabled experimental qualification gates.
Conservative slug/film coupling uses subcell reconstruction with the Eulerian seven-variable
state as the sole inventory. Assert that every reconstructed variable averages back to its cell
value, including energy after momentum redistribution. Enthalpy reference shifts must not change
the reconstruction. Recover positive trace-phase velocities from their exact momentum/mass
ratios so primitive recovery thresholds cannot alter the numerical flux. Use one shared face
flux per phase, with independent oil/water donors when slip is enabled, and cancel the pressure
part using the same phase face holdups and pressures. Test gas-free and one-cell limits explicitly.
Subcell face holdup can greatly exceed its cell average: include the phase-inventory draining
time in the CFL limit, not only reconstructed velocities. Test a thin body crossing a cell face.
Closed boundaries must constrain the external flux after reconstruction; zeroing cell velocities
alone does not prevent a reconstructed slug from leaking through a valve. Prescribed feeds
belong on external face states, not in the evolving cell density/momentum/holdup inventory.
For total energy, transport phase enthalpy plus kinetic energy, include gravitational work,
and do not add stationary-wall friction dissipation as an external energy source.
Independent experimental comparisons must retain source-cell provenance, source-definition
ambiguities, missing predictions and predeclared tolerances. A prescribed-flow marker experiment
tests a closure; label an actual time-marching pipe comparison separately. Coordinate source
freezes across agents before builds because desktop background compilers can modify target/classes.
Test initially volume-exact alternating pressure and velocity modes before claiming convective-CFL
stability of a collocated pressure correction. Include pressure-correction face transfers in
component/thermal transport after acceptance; global energy conservation alone does not establish
local EOS/pressure-work consistency. Record slug crossings during accepted motion and distinguish
union-occupancy changes from internal endpoints or instantaneous merge/birth geometry.
Reject nonfinite or negative raw phase predictors even when adaptive retry is disabled;
fixed stepping must fail at the last accepted state instead of using a positivity repair
to hide lost phase inventory. Separate clock-resolution/invalid-step failures from actual
attempt-budget exhaustion. A configured minimum timestep must never enlarge a CFL bound.
Pressure-solve convergence must include prescribed boundary pressure as well as volume
closure, and reset/failed steps must clear stale correction results and transfer ledgers.
Exercise five-/six-variable legacy inputs after a populated seven-variable state, including
zero and trace liquid. Do not suppress positive trace holdup in an interior flux while
external faces still transport it. For variable areas, match the momentum flux's face area
in the geometric pressure source. At either boundary, preserve each positive phase holdup
directly; subtracting a nearly unit gas fraction can round a trace liquid to zero. Evaluate
all tracked-interface kinematics against the
same accepted geometry before moving any marker; count reverse inlet exits separately
from downstream outlet arrivals without depositing overlay mass into Eulerian cells.
- Forgetting to set
calculateSteadyState=false in tests, so the test never exercises the new dynamic branch.
- Adding a dynamic branch that calls
run(id) internally every timestep and erases the inventory state.
- Reading viscosity, density, or thermal conductivity after a flash without physical-property initialization.
- Updating outlet streams but not the internal inventory, or updating inventory but leaving outlet streams stale.
- Re-flashing every outlet stream after an inventory flash. For phase-separating equipment, rebuild outlets from the
freshly flashed inventory phases, preserve configured valve-capacity flow rates, and initialize properties without
another equilibrium flash. This keeps outlets current and avoids multiplying expensive CPA flashes per timestep.
- Introducing Java 9+ syntax such as
var, List.of, Map.of, text blocks, or String.repeat.
- Adding
System.out.println in tests or examples; use assertions or Log4j2 logger output.
- Adding non-serializable fields to equipment without
transient.
Handoff Checklist
Before considering a dynamic equipment implementation complete, confirm:
- The equipment has a documented physical capacity model or a documented reason why it remains algebraic.
runTransient(dt, id) has both steady-state fallback and real dynamic branch behavior.
- New setters/getters have JavaDoc and Java 8-compatible signatures.
- Tests exercise the real dynamic branch and at least one process-level
ProcessSystem.runTransient(dt, id) path when practical.
- Spotless and the focused test pass.
1---2name: neqsim-dynamic-equipment-implementation3description: "Implement and test NeqSim process-equipment runTransient support. USE WHEN: adding dynamic simulation behavior to any ProcessEquipmentInterface class, including inventory volume, pressure/level/temperature state, controller response, and JUnit regression tests for transient timesteps."4last_verified: "2026-06-25"5metadata:6 source: https://skillmd.com/skills/equinor/neqsim-dynamic-equipment-implementation7---89# Dynamic Equipment Implementation1011Use this skill when a NeqSim equipment class needs real dynamic simulation support instead of the default steady-state fallback or unsupported transient behavior.1213This complements `neqsim-dynamic-simulation`, which explains how to run dynamic studies. This skill explains how to implement and test the Java code that makes equipment participate correctly in `ProcessSystem.runTransient(dt, id)`.1415## Local Architecture1617- `SimulationInterface.runTransient(double dt, UUID id)` defaults to steady-state `run(id)` when `getCalculateSteadyState()` is true, otherwise throws `UnsupportedOperationException`.18- `ProcessSystem.runTransient(dt, id)` steps each `ProcessEquipmentInterface` through a skip-aware wrapper and calls `unit.runTransient(dt, id)`.19- Equipment that has real dynamic behavior must override `runTransient(double dt, UUID id)`.20- Existing reference implementations include `Separator`, `ThreePhaseSeparator`, `Tank`, `Compressor`, `ThrottlingValve`, `SafetyValve`, `BlowdownValve`, `PipeBeggsAndBrills`, `WaterHammerPipe`, `SimpleReservoir`, and `WellFlow`.21- All dynamic equipment code must remain Java 8 compatible, use Log4j2 for logging, and pass Spotless formatting.2223## Implementation Decision Tree24251. **Is the equipment purely algebraic?**26 - Examples: simple pressure drop, splitter ratio, ideal heater with no metal/fluid holdup.27 - Implement only if needed to propagate controller or actuator dynamics; otherwise the steady-state fallback may be sufficient.28292. **Does the equipment hold mass or energy inventory?**30 - Examples: separator, tank, column tray/section, adsorber bed, exchanger volume, pipe segment, reactor, accumulator.31 - Add explicit volume/holdup state and integrate component moles and internal energy over `dt`.32333. **Does the equipment have actuator or mechanical state?**34 - Examples: compressor shaft speed, valve opening, pump ramp, fan speed, bed switching, recycle valve position.35 - Add bounded state variables, ramp-rate limits, and controller hooks.36374. **Does the equipment need thermal inertia?**38 - Examples: heat exchangers, heaters/coolers, fired heaters, reactors, pipes.39 - Add fluid volume and optional wall/metal heat capacity. Preserve energy balance and avoid instant outlet jumps unless the equipment is intentionally algebraic.4041## Required Code Pattern4243For any new transient implementation:44451. Add serializable state fields with defaults that preserve existing steady-state behavior.462. Add public setters/getters for dynamic configuration such as volume, residence time, metal mass, ramp rate, or initial inventory.473. Override `runTransient(double dt, UUID id)`.484. Keep the steady-state branch first:49 - If `getCalculateSteadyState()` is true, call `run(id)`, `increaseTime(dt)`, set/finish the calculation identifier consistently with the class pattern, and return.505. Initialize transient state lazily on the first dynamic step from the last steady-state solution.516. Run controllers or actuator logic before solving the equipment response when the class exposes controller behavior.527. Integrate component and energy balances over the timestep:53 - Accumulation = inlet rates minus outlet rates plus generation or consumption.54 - Energy accumulation = inlet enthalpy rates minus outlet enthalpy rates plus heat/work terms.55 - Clamp tiny negative mole inventories to zero; do not allow negative total volume, negative pressure, or invalid phase amounts.568. Re-flash the updated inventory with the appropriate flash operation (`TPflash`, `TVflash`, `PHflash`, or `VUflash`) and call `initProperties()` or the class-equivalent physical-property initialization before reading transport properties.579. Update every outlet stream from the new state and preserve mass/energy consistency.5810. Call `increaseTime(dt)` and set the calculation identifier before returning.5960## Equipment Configuration Guidance6162Dynamic behavior needs physical capacity. Prefer existing mechanical-design data when it already exists, but expose a simple runtime configuration path for simulations:6364- Vessel-like equipment: volume, diameter, length, liquid level, gas headspace, max/min operating pressure.65- Heat-transfer equipment: process-side volume, optional utility-side volume, UA, metal mass, metal heat capacity, ambient heat loss.66- Rotating equipment: inertia, rated speed, ramp rates, driver power limit, recycle or minimum-flow logic.67- Valves and dampers: opening fraction, stroke time, fail action, Cv/characteristic, controller attachment.68- Pipes: length, diameter, roughness, elevation profile, segment inventory, heat-transfer environment.69- Reactors and beds: bed volume, void fraction, catalyst/solid heat capacity, reaction source terms, residence time.7071Do not hide required dynamic capacity behind mechanical design only. Task notebooks and MCP workflows need direct, documented setters for dynamic parameters.7273## Testing Requirements7475Create focused JUnit 5 tests under the matching package in `src/test/java/neqsim/...`.7677Minimum test coverage for each dynamic implementation:78791. **Steady-state compatibility:** `runTransient(dt, id)` with `calculateSteadyState=true` matches or preserves the existing `run(id)` behavior.802. **Dynamic branch executes:** with `calculateSteadyState=false`, `runTransient(dt, id)` does not throw and advances equipment time.813. **Inventory response:** a flow, heat, pressure, valve-opening, speed, or level disturbance changes a physically relevant state in the expected direction.824. **Mass balance:** integrated inlet minus outlet accumulation matches inventory change within a reasonable tolerance.835. **Energy or temperature response:** when relevant, heat/work input changes internal energy, outlet temperature, or pressure consistently.846. **Controller interaction:** if the equipment has controllers, verify one timestep calls/runs controller logic and applies bounded output.857. **Bounds and robustness:** zero/low flow, empty inventory, small `dt`, and repeated timesteps remain finite and non-negative.868. **Serialization/copy safety:** if new fields are non-serializable, mark them `transient`; otherwise verify normal equipment copy behavior still works.8788Use physical assertions, not private implementation details. Prefer monotonic or bounded assertions over fragile exact transient values unless a regression baseline is intentional.8990## Validation Commands9192After editing Java files in the NeqSim repo, run:9394```powershell95mvnw.cmd spotless:apply96mvnw.cmd test "-Dtest=YourDynamicTest"97mvnw.cmd spotless:check98```99100When public APIs or JavaDoc were added or changed, also run:101102```powershell103mvnw.cmd javadoc:javadoc104```105106When only agent/skill files were edited, run:107108```powershell109uv run --project devtools --locked devtools/verify_skills_agents.py110uv run --project devtools --locked devtools/generate_agent_skill_map.py111uv run --project devtools --locked devtools/verify_skills_agents.py112```113114## Common Pitfalls115116For `TwoFluidPipe` and related finite-volume code, include all three phase inventories in117rejection/positivity checks, even though the class name says two-fluid. Preserve phase identity118at exact water-cut endpoints and separate phase momenta through primitive/conservative recovery.119Distinguish explicit caller velocities from internal recovery: test legacy bulk updates after120recovery, recovered slip, and zero-to-positive phase appearance without overwriting donor momentum.121Pressure-correction face fluxes must share each donor phase's inventory budget. A positivity repair122that moves mass between phases can hide a phase-balance defect behind an exact total-mass balance.123Source-splitting helpers must not run primitive recovery on an invalid trial before its rejection124check; exercise the same negative-phase test with stiff source terms enabled.125Rollback must restore configured closures and their accepted diagnostics, pressure and phase126densities as well as the state vector; a generic clone may discard transient closure fields.127Pressure and density must use the same applied correction after bounds. Independent cell clipping128can reverse Newton face directions and make an upwind active set cycle; test bounded convergence.129A substep budget130must never enlarge a CFL-limited step or silently truncate a requested interval; compare accepted131time with both equipment and solver clocks. Tracker overlay inventory is separate from Eulerian132inventory, so dissolution must not return mass that initialization never withdrew. Read133`docs/wiki/two_fluid_reporting_and_validation.md` for the distinction between numerical regression134coverage and currently disabled experimental qualification gates.135136Conservative slug/film coupling uses subcell reconstruction with the Eulerian seven-variable137state as the sole inventory. Assert that every reconstructed variable averages back to its cell138value, including energy after momentum redistribution. Enthalpy reference shifts must not change139the reconstruction. Recover positive trace-phase velocities from their exact momentum/mass140ratios so primitive recovery thresholds cannot alter the numerical flux. Use one shared face141flux per phase, with independent oil/water donors when slip is enabled, and cancel the pressure142part using the same phase face holdups and pressures. Test gas-free and one-cell limits explicitly.143Subcell face holdup can greatly exceed its cell average: include the phase-inventory draining144time in the CFL limit, not only reconstructed velocities. Test a thin body crossing a cell face.145Closed boundaries must constrain the external flux after reconstruction; zeroing cell velocities146alone does not prevent a reconstructed slug from leaking through a valve. Prescribed feeds147belong on external face states, not in the evolving cell density/momentum/holdup inventory.148For total energy, transport phase enthalpy plus kinetic energy, include gravitational work,149and do not add stationary-wall friction dissipation as an external energy source.150Independent experimental comparisons must retain source-cell provenance, source-definition151ambiguities, missing predictions and predeclared tolerances. A prescribed-flow marker experiment152tests a closure; label an actual time-marching pipe comparison separately. Coordinate source153freezes across agents before builds because desktop background compilers can modify target/classes.154Test initially volume-exact alternating pressure and velocity modes before claiming convective-CFL155stability of a collocated pressure correction. Include pressure-correction face transfers in156component/thermal transport after acceptance; global energy conservation alone does not establish157local EOS/pressure-work consistency. Record slug crossings during accepted motion and distinguish158union-occupancy changes from internal endpoints or instantaneous merge/birth geometry.159160Reject nonfinite or negative raw phase predictors even when adaptive retry is disabled;161fixed stepping must fail at the last accepted state instead of using a positivity repair162to hide lost phase inventory. Separate clock-resolution/invalid-step failures from actual163attempt-budget exhaustion. A configured minimum timestep must never enlarge a CFL bound.164Pressure-solve convergence must include prescribed boundary pressure as well as volume165closure, and reset/failed steps must clear stale correction results and transfer ledgers.166Exercise five-/six-variable legacy inputs after a populated seven-variable state, including167zero and trace liquid. Do not suppress positive trace holdup in an interior flux while168external faces still transport it. For variable areas, match the momentum flux's face area169in the geometric pressure source. At either boundary, preserve each positive phase holdup170directly; subtracting a nearly unit gas fraction can round a trace liquid to zero. Evaluate171all tracked-interface kinematics against the172same accepted geometry before moving any marker; count reverse inlet exits separately173from downstream outlet arrivals without depositing overlay mass into Eulerian cells.174175- Forgetting to set `calculateSteadyState=false` in tests, so the test never exercises the new dynamic branch.176- Adding a dynamic branch that calls `run(id)` internally every timestep and erases the inventory state.177- Reading viscosity, density, or thermal conductivity after a flash without physical-property initialization.178- Updating outlet streams but not the internal inventory, or updating inventory but leaving outlet streams stale.179- Re-flashing every outlet stream after an inventory flash. For phase-separating equipment, rebuild outlets from the180 freshly flashed inventory phases, preserve configured valve-capacity flow rates, and initialize properties without181 another equilibrium flash. This keeps outlets current and avoids multiplying expensive CPA flashes per timestep.182- Introducing Java 9+ syntax such as `var`, `List.of`, `Map.of`, text blocks, or `String.repeat`.183- Adding `System.out.println` in tests or examples; use assertions or Log4j2 logger output.184- Adding non-serializable fields to equipment without `transient`.185186## Handoff Checklist187188Before considering a dynamic equipment implementation complete, confirm:189190- The equipment has a documented physical capacity model or a documented reason why it remains algebraic.191- `runTransient(dt, id)` has both steady-state fallback and real dynamic branch behavior.192- New setters/getters have JavaDoc and Java 8-compatible signatures.193- Tests exercise the real dynamic branch and at least one process-level `ProcessSystem.runTransient(dt, id)` path when practical.194- Spotless and the focused test pass.