SURF model generation
Library: devtools/surf_spec.py (specification), surf_model.py (plan, executor, builder emission, mapping manifest), surf_run.py
(execution and extraction). It creates and wires existing NeqSim owners and adds no solver. Read neqsim-surf-design-study first.
Contract
surf_spec.check_spec(spec) returns (findings, model); surf_model.build_plan(spec, model, concept, case, domain) returns an ordered
operation list; surf_model.execute_plan(plan) returns a Domain (topology, coupler, unit, wells, sps); emit_python(plan, ...)
writes a stand-alone builder whose literal plan equals the generated plan.
| Spec item |
NeqSim owner |
| nodes (wells, manifolds, PLEM/PLET, host, source) |
FieldNetworkTopology.addLiveWellNode/addJunction/addFixedPressureSink/addPressureSource |
| edges (jumper, flowline, trunkline, riser, pump) |
addPipe(..., PipeModelType) + setMultiphaseSegments, setElevationProfile; addPump |
| thermal design |
SubseaProductionSystem.setLineDesign + applyLineThermalDesigns (U-value on the bore area) |
| producers |
WellFlow productivity index bound with FieldWellNetworkCoupler.bindProductionWell |
| injectors |
WellFlow.addLiquidInjectionZone (kg/(s bar)) bound with bindInjectionWell |
| process composition |
FieldWellNetworkProcessUnit + Separator in a ProcessSystem, added to a ProcessModel |
| structural screening |
LineDesign.dnvStF101Input through assessDnvStF101LineDesigns (all inputs explicit, none defaulted) |
| chemical tubes |
one Darcy-Weisbach LoopedPipeNetwork per tube |
Services are separate hydraulic domains (different fluids); identity is shared through the mapping manifest
(model/mapping_manifest.json: spec ID -> hydraulic node/edge, equipment binding, line design, drawings, quantities).
Things that bite
- Every edge needs unique
from_port/to_port per node; duplicates are a validation error.
- Set a flowing temperature on every node that starts a thermal path: a junction downstream of a pump is 15 degC by default.
- Live wells need an initial node pressure that gives a positive first rate (injectors: the pump discharge pressure; zero initial flow makes the thermal coupling NaN).
FieldWellNetworkProcessUnit.getOutletStream exists only after the first run; build the host separator after it.
LoopedPipeNetwork.setTolerance is in Pa (use about 100 Pa), not bar.
LineDesign.installationMethod accepts only S-lay, J-lay and Reel-lay (cost basis); the free-text method is documentation.
- A rigid
LineDesign must match the hydraulic ID within 2 mm (checked by SubseaProductionSystem); a DNV-ST-F101 input needs the exact OD and wall.
- A
BEGGS_BRILL_FALLBACK_DARCY status means no distributed profile: the case is unusable, not a Darcy result.
- JSON replay (
topology.toJson()) is a definition, not a restart state; runtime wells, fluids and bindings are rebound by the builder.
Topology variants
A concept is a set of active edges (edges[].concepts) plus edge_overrides; IDs stay stable and each concept is generated and solved separately.
FieldWellNetworkProcessUnit.registerRouteConfigurationSelector supports availability-based line-ups on one superset graph for operations
studies; the study toolkit builds filtered concepts so cost, MTO and drawings stay concept-exact. Unsupported variants are rejected, not ignored.
Adopting a user-built model
Use the spec only for identity and checks: register existing nodes/edges with FieldNetworkTopology.registerExistingNode/registerExistingEdge
and bind equipment with bindEquipment; never regenerate or overwrite detailed equipment. Verify these method names against the Java source before use.
1---2name: neqsim-surf-model-generation3version: "1.0.0"4description: "Generates the executable NeqSim SURF model from a surf_study.v1 spec: FieldNetworkTopology over LoopedPipeNetwork, live WellFlow wells, FieldWellNetworkProcessUnit with a host separator, SubseaProductionSystem line designs, umbilical networks, ID mapping manifest and an editable Python builder. USE WHEN: a subsea network must be built from structured inputs, concepts compared, or a user-built model adopted without overwriting equipment."5last_verified: "2026-10-25"6requires:7 python_packages: [jpype1, pyyaml]8metadata:9 source: https://skillmd.com/skills/equinor/neqsim-surf-model-generation10---1112# SURF model generation1314Library: `devtools/surf_spec.py` (specification), `surf_model.py` (plan, executor, builder emission, mapping manifest), `surf_run.py`15(execution and extraction). It creates and wires **existing** NeqSim owners and adds no solver. Read `neqsim-surf-design-study` first.1617## Contract1819`surf_spec.check_spec(spec)` returns `(findings, model)`; `surf_model.build_plan(spec, model, concept, case, domain)` returns an ordered20operation list; `surf_model.execute_plan(plan)` returns a `Domain` (`topology`, `coupler`, `unit`, `wells`, `sps`); `emit_python(plan, ...)`21writes a stand-alone builder whose literal plan equals the generated plan.2223| Spec item | NeqSim owner |24|-----------|--------------|25| nodes (wells, manifolds, PLEM/PLET, host, source) | `FieldNetworkTopology.addLiveWellNode/addJunction/addFixedPressureSink/addPressureSource` |26| edges (jumper, flowline, trunkline, riser, pump) | `addPipe(..., PipeModelType)` + `setMultiphaseSegments`, `setElevationProfile`; `addPump` |27| thermal design | `SubseaProductionSystem.setLineDesign` + `applyLineThermalDesigns` (U-value on the bore area) |28| producers | `WellFlow` productivity index bound with `FieldWellNetworkCoupler.bindProductionWell` |29| injectors | `WellFlow.addLiquidInjectionZone` (kg/(s bar)) bound with `bindInjectionWell` |30| process composition | `FieldWellNetworkProcessUnit` + `Separator` in a `ProcessSystem`, added to a `ProcessModel` |31| structural screening | `LineDesign.dnvStF101Input` through `assessDnvStF101LineDesigns` (all inputs explicit, none defaulted) |32| chemical tubes | one Darcy-Weisbach `LoopedPipeNetwork` per tube |3334Services are separate hydraulic domains (different fluids); identity is shared through the mapping manifest35(`model/mapping_manifest.json`: spec ID -> hydraulic node/edge, equipment binding, line design, drawings, quantities).3637## Things that bite3839- Every edge needs unique `from_port`/`to_port` per node; duplicates are a validation error.40- Set a flowing temperature on **every** node that starts a thermal path: a junction downstream of a pump is 15 degC by default.41- Live wells need an initial node pressure that gives a positive first rate (injectors: the pump discharge pressure; zero initial flow makes the thermal coupling NaN).42- `FieldWellNetworkProcessUnit.getOutletStream` exists only after the first `run`; build the host separator after it.43- `LoopedPipeNetwork.setTolerance` is in Pa (use about 100 Pa), not bar.44- `LineDesign.installationMethod` accepts only S-lay, J-lay and Reel-lay (cost basis); the free-text method is documentation.45- A rigid `LineDesign` must match the hydraulic ID within 2 mm (checked by `SubseaProductionSystem`); a DNV-ST-F101 input needs the exact OD and wall.46- A `BEGGS_BRILL_FALLBACK_DARCY` status means no distributed profile: the case is unusable, not a Darcy result.47- JSON replay (`topology.toJson()`) is a definition, not a restart state; runtime wells, fluids and bindings are rebound by the builder.4849## Topology variants5051A concept is a set of active edges (`edges[].concepts`) plus `edge_overrides`; IDs stay stable and each concept is generated and solved separately.52`FieldWellNetworkProcessUnit.registerRouteConfigurationSelector` supports availability-based line-ups on one superset graph for operations53studies; the study toolkit builds filtered concepts so cost, MTO and drawings stay concept-exact. Unsupported variants are rejected, not ignored.5455## Adopting a user-built model5657Use the spec only for identity and checks: register existing nodes/edges with `FieldNetworkTopology.registerExistingNode/registerExistingEdge`58and bind equipment with `bindEquipment`; never regenerate or overwrite detailed equipment. Verify these method names against the Java source before use.