neqsim-pid-process-operations

name neqsim-pid-process-operations version 1.8.0 description Bidirectional P&ID/NeqSim workflow. USE WHEN: understanding P&ID symbols, converting P&ID topology into NeqSim simulations, generating governed DEXPI engineering packages from ProcessSystem or ProcessModel, linking tags to historian data, evaluating valve/equipment changes, or preparing water-hammer and blowdown/flare handoffs. last_verified 2026-07-17 requires {"python_packages":["pandas"]} 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: { "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 : { "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: 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: 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 Build the base flowsheet from the P&ID graph and process model. Use live plant data to set boundary pressure, temperature, flow, level, and selected valve positions where available. Run process.run() and compare simulated outputs with historian tags. 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