neqsim-pid-process-operations

# P&ID to Process Operations This skill bridges P&ID interpretation, NeqSim process simulation, and plant historian data. It is for operational questions such as "what happens if this valve closes?", "which train is active?", "what inventory is trapped between these valves?", and "how will pressure, level, flow, flare load, or emissions change?" Keep this public skill plant-agnostic. Do not include real facility names, operator-specific document numbers, internal historian source names, real tag maps, credentials, or private operating procedures. Put those details in a private prompt file or local private skill. ## When to Use - Reading P&ID symbols, line numbers, valves, instruments, drains, vents, interlocks, and equipment connections. - Converting P&ID topology into a NeqSim `ProcessSystem`, `ProcessModel`, or `PipingRouteBuilder` route. - Mapping P&ID instrument tags to plant historian tags read by `tagreader`. - Determining active train/equipment state from valves, flows, pressures, levels, temperatures, and run-status tags. - Evaluating steady-state process effects of valve position changes, blocked outlets, bypasses, recycles, drains, or alternate routing. - Evaluating dynamic effects of valve actions using `runTransient`, controllers, measurement devices, or dedicated blowdown/depressurization models. - Preparing `WaterHammerStudy` or MCP `runWaterHammer` inputs for fast liquid-line valve closure, pump trip, or check-valve slam. - Generating governed DEXPI engineering packages from a simulated `ProcessSystem` or multi-area `ProcessModel`, including available mechanical, piping, PSV, blowdown/flare and materials calculations. ## Required Skill Stack Use this skill with: - `neqsim-technical-document-reading` for P&ID image/document extraction, - `neqsim-process-extraction` for topology to JSON/route conversion, - `neqsim-plant-data` for tagreader reads, tag maps, and data quality, - `neqsim-controllability-operability` for steady-state operating envelopes and control valve checks, - `neqsim-dynamic-simulation` for transient valve-action studies, - `neqsim-water-hammer` for hydraulic surge screening from fast liquid-line events, - `neqsim-depressurization-mdmt` for blowdown and minimum-temperature cases, - `neqsim-professional-reporting` for evidence traceability and report outputs. ## P&ID Symbol Interpretation Model Read a P&ID as a process graph plus operational annotations: | P&ID object | Graph meaning | NeqSim representation | Historian evidence | |-------------|---------------|-----------------------|--------------------| | Vessel, separator, scrubber | inventory and phase split node | `Separator`, `ThreePhaseSeparator`, `Tank` | pressure, level, temperature | | Compressor, pump, expander | pressure/energy-changing node | `Compressor`, `Pump`, `Expander` | speed, power, suction/discharge P/T, run status | | Heat exchanger, cooler, heater | heat-duty node | `HeatExchanger`, `Cooler`, `Heater` | inlet/outlet T, utility flow | | Control valve | pressure-drop and manipulated-variable edge | `ThrottlingValve` | valve position, controller output, upstream/downstream P | | Manual isolation valve | topology boundary or scenario switch | open/closed edge state or route K value | valve position if instrumented; otherwise drawing/procedure basis | | Shutdown valve / on-off valve | dynamic event and isolation boundary | valve scenario event, often binary open/closed | limit switch, trip status, position | | Check valve | one-way edge constraint | route K value and direction flag | reverse-flow indication if available | | PSV/BDV/vent valve | relief or blowdown path | safety valve, blowdown route, flare source term | flare header P, valve status, event log | | Drain/vent/purge connection | alternate evacuation route | scenario route or boundary stream | valve status, purge/flare destination | | Instrument bubble | measurement or controller signal | transmitter/controller device or tag map entry | historian tag and data quality | | Signal line / interlock | control logic or trip dependency | controller, logic note, dynamic event | controller mode, setpoint, trip status | When symbol meaning is uncertain, record alternatives and confidence. Never infer a valve's current open/closed state from a P&ID alone; use live data, operator input, or the approved procedure basis. ## P&ID Extraction Schema Extend the standard `PID_EXTRACTION` object with operational semantics: ```json { "pid_operational_model": { "equipment_nodes": [ {"id": "V-101", "type": "separator", "neqsim_type": "Separator"} ], "process_edges": [ { "id": "L-101", "from": "V-101.gasOut", "to": "PV-101.inlet", "line_number": "L-101", "nominal_size_in": 8.0, "normal_service": "gas outlet" } ], "valves": [ { "tag": "PV-101", "symbol_type": "control_valve", "normal_position": "modulating", "failsafe": "unknown", "neqsim_role": "ThrottlingValve", "scenario_actions": ["set outlet pressure", "change Cv", "close"] } ], "instruments": [ { "pid_tag": "PT-101", "function": "pressure transmitter", "measured_object": "V-101", "logical_tag_name": "separator_pressure" } ], "control_links": [ {"controller": "PIC-101", "measurement": "PT-101", "manipulated_valve": "PV-101"} ], "operational_boundaries": [ {"name": "separator outlet isolation", "boundary_valves": ["XV-101", "XV-102"]} ] } } ``` ## Connecting P&ID Tags to Plant Data Create a logical tag map first, then bind logical names to private historian tags in a private skill or task-local `tag_mapping.json`: ```json { "separator_pressure": "PRIVATE_HISTORIAN_TAG", "separator_level": "PRIVATE_HISTORIAN_TAG", "separator_temperature": "PRIVATE_HISTORIAN_TAG", "gas_outlet_valve_position": "PRIVATE_HISTORIAN_TAG", "gas_outlet_flow": "PRIVATE_HISTORIAN_TAG", "compressor_run_status": "PRIVATE_HISTORIAN_TAG" } ``` In Java workflows, use the plant-agnostic helpers in `neqsim.process.operations` so private historian names can stay outside public models while NeqSim still uses its existing measurement devices and automation API: ```java OperationalTagMap tagMap = new OperationalTagMap() .addBinding(OperationalTagBinding.builder("separator_pressure") .historianTag("PRIVATE_HISTORIAN_TAG") .unit("bara") .role(InstrumentTagRole.INPUT) .build()) .addBinding(OperationalTagBinding.builder("outlet_valve_position") .historianTag("PRIVATE_HISTORIAN_TAG") .automationAddress("Outlet Valve.percentValveOpening") .unit("%") .role(InstrumentTagRole.INPUT) .build()); ValidationResult validation = tagMap.validate(process); Map<String, Double> applied = tagMap.applyFieldData(process, fieldData); Map<String, Double> modelValues = tagMap.readValues(process); ``` This is a bridge only. Keep using `MeasurementDeviceInterface` tags, tag roles, `ProcessSystem.setFieldData`, `ProcessSystem.applyFieldInputs`, and `ProcessAutomation` for the actual model interaction. For active-state inference, use at least two independent indicators: flow, pressure, temperature, level movement, valve position, controller output, run status, speed, power, or trip status. Save raw historian data as CSV inside the task folder before running calculations. ## Converting to NeqSim ### Generating a governed DEXPI engineering package When the direction is NeqSim-to-P&ID, use the engineering project layer rather than calling `DexpiXmlWriter` alone. It adds a versioned design basis, standards traceability, deterministic control/safeguarding proposals, approval state, validation findings, and referenced compressor-map datasets: ```java EngineeringProject project = NorsokOffshoreEngineeringBuilder .from("Gas compression engineering model", process) .registerProposedInstruments(true) .build(); EngineeringValidationReport validation = project.validate(); DexpiEngineeringExporter.ExportResult files = DexpiEngineeringExporter.export(project, Paths.get("engineering-package")); ``` The generated `plant.dexpi.xml` is a native DEXPI 2.0 semantic process model and is validated against the bundled official DEXPI XML schema during export. `plant-proteus.xml` is the backward-compatible graphical P&ID containing requirement-linked instrumentation functions, logic functions, information flows, control/protective valves, and equipment associations. It references `engineering-manifest.json`, the proposed `cause-and-effect.json`, simulation-backed `engineering-calculations.json`, and any `datasets/<tag>-compressor-map.json` sidecars. Use `plant-pydexpi.xml` for pyDEXPI import and inspect `interoperability-report.json`; native schema validity, semantic-profile validity, pyDEXPI import and commercial-CAE round-trip are distinct gates. Do not flatten large vendor maps into P&ID attributes. Do not call the Proteus graphical file DEXPI 2.0. Antisurge recycle topology is connected discharge-to-suction; PSV/BDV proposals use dedicated equipment nozzles and a separate relief/blowdown network. Treat every `UnresolvedBoundary=YES` as a required line, flare-header, vent, drain or utility tie-in before engineering completion. Represent controlled tie-ins with `EngineeringBoundary` so process inlet/outlet, flare, vent, closed-drain, utility and recycle connections become directional off-page connectors in native DEXPI rather than free-text assumptions. For a full process-to-engineering run, follow the eight controlled stages in `docs/integration/process-to-engineering-simulator.md`. Require convergence of both physical design variables and process values. Use typed equipment, network-piping, valve/instrument, safety, materials and mechanical calculation modules for independent evidence. Compile the final project with `EngineeringDeliverableCompiler`; do not assemble datasheets or registers from ad-hoc notebook dictionaries when coordinated compiler artifacts are available. Use `examples/notebooks/process_to_engineering_simulator.ipynb` for the closed loop and coordinated-package pattern, and `examples/notebooks/engineering_roadmap_steps_1_to_8.ipynb` for executable typed calculation examples across equipment, piping, valve/instrument, safety, materials and preliminary mechanics. When qualifying rather than screening a typed calculation, build an `EngineeringCalculationContext` with `productionQualification=true`, controlled standard references and evidence references. In this mode, do not accept equipment screening defaults, reference-diameter piping scaling, an unresolved valve failure position, or an unreferenced two-phase relief method. Use `ReliefSizingCalculation` for governed gas/liquid/steam orifice selection and only for two-phase flow when a specialist mass-flux result and controlled method reference have been supplied. Treat `unresolved-engineering-actions.json` as a mandatory review input. A calculated DEXPI package is never equivalent to HAZOP/LOPA acceptance, vendor certification, code mechanical design, final metallurgy approval or construction authorization. Represent those external decisions with `EngineeringExternalEvidenceRegister`, starting from `productionMinimum(projectRevisionScope)` and adding equipment-, SIF- and package-specific requirements. `EngineeringExternalEvidenceRecord` must carry the controlled document revision, SHA-256 hash, issuer, governed scope, decision authority, decision date and workflow/signature reference. Independent validation additionally needs an independence statement; construction authority evidence needs the applicable jurisdiction. Inspect `engineering-external-evidence-register.json` and keep draft, rejected, incomplete, conflicting or superseded evidence open. The register verifies receipts; it never creates approval. Also inspect `engineering-production-readiness.json`. Do not describe a package as production-ready merely because the design loop converged or package validation passed. `QUALIFIED_FEED_SUPPORT` additionally requires independent benchmarks for every executed method version, project method qualifications, an explicit no-hidden-default auto-configuration result, named-tool DEXPI round-trip evidence, approved safety-lifecycle evidence, three accepted pilots, and release-quality evidence. Even that level always retains `fitnessForConstruction=false` and does not grant final engineering approval. For the first complete inlet-separator/compressor/cooler/export facility slice, run `ProductionVerticalSlicePreflight.assess` first and use `ProductionVerticalSliceSimulator.runStrictAndCompile` for controlled execution. Inspect `engineering-vertical-slice-qualification.json`. Require the declared topology, ten case types, converged physical design, active compressor surge and stonewall curves, zero map extrapolation, executable dynamic safe-state tests, coupled PSV/blowdown/flare capacity, controlled standards and evidence. Add the map check through the revision-controlled policy with `addCompressorOperatingEnvelope`. Passing all vertical-slice gates means only a controlled pilot; never translate it to FEED approval or fitness for construction. For JPype workflows, use `VerticalSliceCaseMatrixFactory` to create explicit, evidence-linked scalar boundary conditions for every required case type. Do not treat those steady boundary changes as substitutes for transient initiating events, HAZOP credibility decisions, or shutdown logic. Retain `engineering-vertical-slice-execution-manifest.json` with the package. Its SHA-256 fingerprint binds the project and policy revisions, case inputs, dynamic scenarios, coupled safety studies, standards and evidence. A fingerprint change requires recalculation and revision-impact review; it never grants engineering approval. Also inspect `engineering-qualification-plan.json`. Use its exact method keys and open actions to drive `EngineeringBenchmarkDataset`, `DexpiToolQualificationRunner`, `EngineeringPilotQualificationRunner`, and `EngineeringReleaseQualificationRunner`. These runners convert actual measurements and named external results into evidence; they do not perform an independent review or create an acceptance record. Keep missing external evidence open. Use `examples/notebooks/engineering_production_qualification_workflow.ipynb` as the API pattern for the executable qualification workflows. Its data are synthetic and must never be promoted to project evidence. The calculation handoff automatically runs available equipment mechanical-design and materials-screening models. It can run API 520/521 PSV sizing from attached credible relief scenarios, and readiness-gated dynamic blowdown, flare load, radiation, capacity, and header checks from a `DynamicBlowdownFlareStudyDataSource`. A blocked-outlet PSV screen may be generated from simulated full inflow only when declared design and relief-set pressures exist. Treat missing-input statuses as data gaps; never fill them with generic values merely to obtain a size. For an engineering-readiness package, attach the governed project inputs that correspond to the source documents: - `LineDesignInput` for line-list dimensions, schedule, wall, material, piping class, corrosion allowance, design conditions and evidence reference; - `ReliefScenarioBasis` for hazard-review-required API 521 causes, with matching scenarios in `OverpressureProtectionStudy`; - `SafetyFunctionDesign` for LOPA/SRS-backed target SIL, sensor/logic/final-element failure data, MooN voting, proof-test interval, diagnostic coverage and beta factor; - `ShutdownSequence` for cause/effect actions, safe positions, timing budget, linked requirement IDs, HAZOP/SRS references and reset/restart definition; - `ReliefDeviceDesignInput` for the selected device, inlet/outlet geometry, allowable losses, two-phase method, fire zone, concurrency group and evidence; - `EngineeringEvidenceRecord` for revision-controlled HAZOP, LOPA, SRS, line-list, vendor and calculation records linked to equipment and requirements; - `EmergencyShutdownTestResult` from `EmergencyShutdownTestRunner`, linked to the applicable sequence with `addShutdownVerificationResult(...)`. Inspect `engineeringReadiness` in `engineering-calculations.json`. It reports coverage percentage, missing-input count, severity, responsible discipline and approval state. Never interpret 100% calculation/evidence coverage as engineering approval or fitness for construction. Failed or blocked calculation objects must not be counted as completed merely because they are present in the handoff. Also inspect `engineeringCoverageMatrix`, `installedReliefDeviceVerification`, `reliefDisposalNetworkLoads`, `engineeringEvidenceStatus`, and the dynamic result inside `shutdownSequenceVerification`. Review `dexpi-validation.json`, every CSV/JSON under `registers/`, and `package-manifest.json`. If the project provides its controlled DEXPI XSD, call `DexpiEngineeringValidator.validate(dexpiFile, xsdFile)`; do not silently download or choose a schema edition. For multi-area models, call `NorsokOffshoreEngineeringBuilder.fromProcessModel(...)` and export each returned `EngineeringProject` to its own area directory. Use `examples/notebooks/dexpi_engineering_full_processsystem.ipynb` and `examples/notebooks/dexpi_engineering_processmodel.ipynb` as the executable reference patterns. Never bypass the governed exporter with `DexpiXmlWriter` when the requested output includes safety, instrumentation, sizing or standards traceability. Safety governance is mandatory: rule-generated trips use `SIL_UNASSIGNED` and `REVIEW_REQUIRED`; generated controller tuning, trip set points, and voting architectures remain `NOT_ASSIGNED` unless a controlled `SafetyFunctionDesign` supplies them. Never derive SIL from equipment type, a generic tag template, or normal operating conditions. Set a SIL target only from an identified HAZOP/LOPA/QRA record and approve it through the project SRS workflow per IEC 61511. See `neqsim-process-safety` for the risk-analysis handoff. ### Steady-State Model 1. Build the base flowsheet from the P&ID graph and process model. 2. Use live plant data to set boundary pressure, temperature, flow, level, and selected valve positions where available. 3. Run `process.run()` and compare simulated outputs with historian tags. 4. Save a base-case result before applying any change. For large plants, use `ProcessModel` with one `ProcessSystem` per area. For line-only questions, use `PipingRouteBuilder` rather than a full process model. ### Valve or Route Change Scenarios Define every action as a model delta: | Action | Steady-state delta | Dynamic delta | |--------|--------------------|---------------| | Close isolation valve | remove/disable route or set downstream flow to zero with a bounded case | binary valve event at time `t_event` | | Partly close control valve | increase pressure drop or reduce Cv/opening | ramp valve opening or controller output | | Open bypass | add parallel route/mixer/splitter branch | ramp bypass valve open | | Block outlet | set outlet flow path closed and let upstream pressure/level find constraint | close outlet valve and track P/L/T | | Open drain/vent | add drain or flare boundary stream | open drain/vent valve and track inventory loss | | Change controller mode | fix manipulated variable or setpoint | switch AUTO/MAN logic in event schedule | Always state whether the action is physically possible from the P&ID and whether additional hidden paths, non-return valves, or interlocks may change the result. For generic Java studies, represent simple action sequences with `OperationalScenario` and run them with `OperationalScenarioRunner`. The runner delegates valve opening changes to existing `SetValveOpeningAction`, variable