DEXPI P&ID Import, Export and Visualization

NeqSim provides a complete DEXPI integration that supports:

Architecture overview

Class Purpose
DexpiXmlReader Parses DEXPI XML into lightweight DexpiProcessUnit / DexpiStream objects
DexpiXmlWriter Exports ProcessSystem to DEXPI XML with full P&ID layout
DexpiLayoutEngine Computes auto-layout positions; renders graphical elements (shapes, lines, instruments, borders)
DexpiShapeCatalog Generates ShapeCatalogue with 22 ISO 10628:2012 equipment shapes
DexpiLayoutConfig Configurable layout parameters (spacing, fonts, colors, feature toggles)
DexpiMetadata Shared constants for GenericAttribute names used by both reader and writer
DexpiSimulationBuilder High-level builder: DEXPI XML to runnable ProcessSystem
DexpiTopologyResolver Nozzle/connection graph, topological sort, cycle detection
DexpiEquipmentFactory Converts DEXPI placeholders to real NeqSim equipment with sizing
DexpiMappingLoader Thread-safe cached loader for equipment mapping .properties files
DexpiStreamUtils Shared outlet-stream resolution for separators, splitters, two-port equipment
DexpiRoundTripProfile Validates minimal metadata for reliable round-trip fidelity
DexpiStream Lightweight piping segment with DEXPI class, line number, and fluid code
DexpiProcessUnit Imported equipment with original DEXPI class and mapped EquipmentEnum
DexpiInstrumentInfo Instrument metadata (tag, type, function letter)

Importing DEXPI XML

The DexpiXmlReader converts DEXPI XML P&ID exports into ProcessSystem models. It recognises major equipment (pumps, heat exchangers, tanks, control valves, reactors, compressors, inline analysers) and imports piping segments as runnable DexpiStream units tagged with the source line number.

Path xmlFile = Paths.get("/path/to/dexpi.xml");
SystemSrkEos exampleFluid = new SystemSrkEos(298.15, 50.0);
exampleFluid.addComponent("methane", 0.9);
exampleFluid.addComponent("ethane", 0.1);
exampleFluid.setMixingRule(2);
exampleFluid.init(0);

Stream template = new Stream("feed", exampleFluid);
template.setFlowRate(1.0, "MSm3/day");
template.setPressure(50.0, "bara");
template.setTemperature(30.0, "C");

ProcessSystem process = DexpiXmlReader.read(xmlFile.toFile(), template);

DexpiProcessUnit feedPump = (DexpiProcessUnit) process.getUnit("P4711");
if (feedPump.getMappedEquipment() == EquipmentEnum.Pump) {
  // handle pump metadata
}

Each imported equipment item is represented as a lightweight DexpiProcessUnit that records the original DEXPI class, mapped EquipmentEnum category, and contextual information (line numbers, fluid codes). Piping segments become DexpiStream objects that clone pressure, temperature, and flow settings from the template stream.

Metadata conventions

Both the reader and writer share DexpiMetadata constants that describe the recommended generic attributes for DEXPI exchanges. Equipment exports include tag names, line numbers, and fluid codes. Piping segments carry segment numbers and operating pressure/temperature/flow triples with explicit unit annotations. Query DexpiMetadata.recommendedStreamAttributes() and DexpiMetadata.recommendedEquipmentAttributes() for the minimal metadata sets guaranteed by NeqSim.

Exporting to DEXPI XML

The DexpiXmlWriter serializes any ProcessSystem into a DEXPI XML document with professional P&ID visualization. The writer produces valid DEXPI XML with proper namespace declarations.

Basic export

// Build and run a process
ProcessSystem process = new ProcessSystem();
process.add(feed);
process.add(separator);
process.add(compressor);
process.run();

// Export with auto-layout
DexpiXmlWriter.write(process, new File("output.xml"));

Layout and visualization features

The export path applies NeqSim’s built-in auto-layout and visualization defaults: equipment tag labels, nozzles, routed connection lines, service labels, flow arrows, stream tables, battery-limit connectors, symbol legends, and equipment bar labels when simulation data is available. DexpiLayoutConfig collects the tunable layout fields used by the DEXPI layout workstream; check the writer API before using custom layout configuration from application code, because the stable public export calls are the write(...), writeForPyDexpi(...), and writeSheets(...) overloads shown below.

Exporting a multi-area ProcessModel

A whole ProcessModel (several process areas) can be exported in a single call. All areas are flattened into one drawing; equipment is added by object identity so a stream shared between two areas is registered once, and genuine name collisions are skipped with a logged warning.

ProcessModel plant = new ProcessModel();
plant.add("Inlet", inletArea);
plant.add("Compression", compressionArea);

// One call writes a single combined P&ID for the whole plant
DexpiXmlWriter.write(plant, new File("plant.xml"));

// Or split into one DEXPI sheet per area
List<File> sheets = DexpiXmlWriter.writeSheets(plant, new File("sheets"));

pyDEXPI-friendly export (namespace omitted)

pyDEXPI and other Proteus readers that perform unqualified tag look-ups cannot resolve elements when the default xmlns="http://sandbox.dexpi.org/xml" namespace is present. Use writeForPyDexpi (or the DexpiDiagramBridge.exportForPyDexpi convenience method) to write content-identical XML with the default namespace omitted while preserving the OriginatingSystem* PlantInformation metadata that Proteus loaders expect, so the file loads directly without a namespace-stripping pre-pass.

// Java — writer
DexpiXmlWriter.writeForPyDexpi(process, new File("plant.pydexpi.xml"));

// Java — diagram bridge convenience
DexpiDiagramBridge.exportForPyDexpi(process, Paths.get("plant.pydexpi.xml"));

The examples/notebooks/professional_process_flow_diagrams.ipynb notebook wraps this in a reusable render_dexpi_pid(process, name) helper that exports the DEXPI file and renders genuine ISA-5.1 symbols via pydexpi.loaders.svg_loader.DrawDiagram, degrading gracefully when pyDEXPI is absent.

The same notebook also shows the most compact recipe — a P&ID figure in four working lines (export → load → draw → display):

from pydexpi.loaders.svg_loader import DrawDiagram
from IPython.display import SVG, display

DexpiDiagramBridge.exportForPyDexpi(process, JPaths.get("compact.dexpi.xml"))
model = ProteusSerializer().load(out_dir, "compact.dexpi.xml")
DrawDiagram(model.diagram, padding=5.0, pretty=True).save_svg("compact", str(out_dir))
display(SVG(filename=str(out_dir / "compact.svg")))

For a standalone, importable end-to-end pipeline (NeqSim build → DEXPI export → pyDEXPI render), see examples/neqsim/render_neqsim_dexpi_with_pydexpi.py. Its build_process, export_dexpi, and render functions can be imported directly into a notebook or run as a script via python render_neqsim_dexpi_with_pydexpi.py. The example uses writeForPyDexpi, so it no longer needs a separate namespace-stripping compatibility pass.

Round-trip (import, simulate, re-export)

Stream templateStream = new Stream("feed", fluid);
templateStream.setFlowRate(1.0, "MSm3/day");
templateStream.setPressure(50.0, "bara");
templateStream.setTemperature(30.0, "C");

DexpiXmlWriter.roundTrip(
    new File("input_pid.xml"),
    new File("output_with_results.xml"),
    templateStream);

XML namespace compliance

The writer produces namespace-aware DEXPI XML:

For consumers that require unqualified tag look-ups (such as pyDEXPI), use writeForPyDexpi / DexpiDiagramBridge.exportForPyDexpi, which emit the same content with the default xmlns omitted (see pyDEXPI-friendly export above).

Line data and NORSOK line numbers

Each piping connection carries operating line data and a NORSOK Z-003 line-identification label:

Battery-limit feeds and products that are not wired to another unit on the sheet are marked with off-page connector symbols carrying FEED / PRODUCT cross references, and instrument tags are checked against ISA-5.1 with a TagConformanceWarning attribute added for non-conforming tags.

Equipment mapping (native NeqSim to DEXPI)

The writer reverse-maps Java classes to DEXPI ComponentClass strings:

NeqSim class DEXPI ComponentClass RDL URI suffix
ThreePhaseSeparator ThreePhaseSeparator RDS327962
Separator Separator RDS327962
Compressor CentrifugalCompressor RDS414622
Pump CentrifugalPump RDS415550
Cooler AirCoolingSystem RDS327938
HeatExchanger ShellAndTubeHeatExchanger RDS327918
Heater FiredHeater RDS327914
ThrottlingValve GlobeValve (tag prefix may map to gate/ball/check/butterfly) RDS415212
Expander Expander RDS414776
Mixer Mixer RDS4149564
Splitter Splitter RDS4112354
DistillationColumn DistillationColumn RDS327902

Valve types are further distinguished by tag name prefix: XV- (gate valve), BV- (ball valve), NRV- / CV- (check valve), BFV- (butterfly valve), or globe valve (default).

Nozzles and connections

Every exported equipment element receives <Nozzle> children with phase-aware positioning:

Equipment type Outlet nozzles
Separator 2 (gas top, liquid bottom)
ThreePhaseSeparator 3 (gas top, oil middle, water bottom)
All other equipment 1

<Connection> elements link outlet nozzles to inlet nozzles using stream identity matching. Pass-through Stream wrappers are recognised by tracing the delegated fluid identity.

Simulation results export

After process.run(), the writer exports converged simulation results (operating pressure, temperature, and flow rate) as GenericAttribute entries on each equipment element.

Mechanical design data export

When equipment has a MechanicalDesign associated, the writer exports:

These appear as rows in the equipment data bar and as GenericAttribute entries in the XML.

Valve-specific data

For ThrottlingValve equipment, the writer exports the valve flow coefficient (Cv) as a GenericAttribute when a non-zero value is available.

Piping network export

DexpiStream segments are grouped by line number (or fluid code) into <PipingNetworkSystem> / <PipingNetworkSegment> elements. Each segment carries piping class and line size metadata when available. Networks are labelled with a NeqSimGroupingKey generic attribute for downstream visualization tools.

P&ID Layout and Visualization

The DexpiLayoutEngine computes auto-layout positions and renders a full set of graphical elements that produce professional-quality P&ID drawings.

ISO 10628:2012 shape catalogue

The DexpiShapeCatalog generates a <ShapeCatalogue> with 22 standardized shapes drawn using DEXPI graphical primitives (Circle, PolyLine, TrimmedCurve). Each shape records its ISO 10628 registration number via a ComponentName attribute.

Shape ISO Reference Description
Vertical separator ISO 10628:2012-2091-A Vessel body with dished heads
Three-phase separator ISO 10628:2012-2091-A Vessel with weir partition
Centrifugal compressor ISO 10628:2012-2331-A Trapezoid with circle driver
Centrifugal pump ISO 10628:2012-2301-A Circle with discharge triangle
Air-cooled heat exchanger ISO 10628:2012-2141-A Rectangular with fan symbol
Fired heater ISO 10628:2012-2191-A Rectangular enclosure with flame
Shell-and-tube heat exchanger ISO 10628:2012-2131-A Rectangular with tube passes
Globe valve ISO 10628:2012-X8058-A Double-triangle (bowtie)
Gate valve ISO 10628:2012-X8062-A Bowtie with vertical bar
Ball valve ISO 10628:2012-X8038-A Bowtie with filled circle
Check valve ISO 10628:2012-X8072-A Triangle with vertical stop
Butterfly valve ISO 10628:2012-X8042-A Bowtie with vertical line
Expander/turbine ISO 10628:2012-2331-A Reversed trapezoid
Mixer — Converging tee
Splitter — Diverging tee
Nozzle — Small stub
Generic equipment — Dashed rectangle (fallback)
Distillation column ISO 10628:2012-2092-A Tall vessel with 5 internal tray lines
Relief valve ISO 10628:2012-X8088-A Triangle with spring/bonnet line and arrowhead
Solenoid valve — Diamond outline with coil symbol
Utility supply — Circle with incoming arrow

Auto-layout features

The layout engine automatically arranges equipment left-to-right following process flow topology. Per ISO 10628 drafting practice, a separator’s gas/overhead branch routes to the upper part of the sheet and the liquid/bottoms branch to the lower part, with the inlet train and any recombined streams kept on the centre line. This keeps the gas train (compressors, coolers, scrubbers) visually above the liquid train (pumps, oil/water treatment) and stops bottoms lines from crossing gas equipment. The engine produces the following visual elements:

Drawing frame and border:

Equipment visualization:

Process lines:

Instrumentation (per ISA 5.1):

Safety elements:

Piping detail:

Annotations:

Additional drawing elements:

Layout configuration

DexpiLayoutConfig provides a builder-pattern API for customizing every aspect of the layout:

Spacing and positioning:

Parameter Default Description
xSpacing 100.0 Horizontal spacing between equipment (mm)
yBranchOffset 60.0 Vertical offset for liquid branches (mm)
xStart 80.0 X-coordinate of first equipment (mm)
yBase 150.0 Y-coordinate of main process line (mm)
defaultScale 1.0 Overall drawing scale factor
instrumentOffsetY 45.0 Vertical offset for instruments above process line (mm)
instrumentXSpacing 15.0 Horizontal spacing between instruments (mm)
borderMargin 14.0 Drawing border margin (mm)
batteryLimitPadding 30.0 Battery limit boundary padding (mm)

Typography and line styles:

Parameter Default Description
fontName "Calibri" Font family for all text
tagFontHeight 4.5 Font height for tag labels (mm)
processLineWeight 0.5 Stroke weight for process lines
signalLineWeight 0.2 Stroke weight for signal/instrument lines
lineColorR/G/B 0.5/0.5/0 RGB color for process lines

Feature toggles:

Toggle Default Controls
showStreamTable true Stream data table at bottom of drawing
showSymbolLegend true Symbol identification legend
showRevisionHistory true Revision history table
showBatteryLimit true Battery limit boundary
showFlowArrows true Flow direction arrows
showStreamLabels true Stream name labels on lines
showEquipmentBars true Equipment data bars
showInsulationMarks true Insulation tick marks on pipes
showFailPositionMarkers true FC/FO/FL markers on control valves
showSilMarkers true SIL-level double-border circles
showOrientationMarkers true Equipment orientation indicators

Building runnable simulations from DEXPI

The DexpiSimulationBuilder provides a high-level API that goes beyond basic import: it resolves the P&ID topology (nozzle/connection graph), instantiates real NeqSim equipment (separators, compressors, valves, heat exchangers, etc.) with sizing attributes from DEXPI GenericAttributes, and wires them into a runnable ProcessSystem.

SystemInterface fluid = new SystemSrkEos(298.15, 50.0);
fluid.addComponent("methane", 0.9);
fluid.addComponent("ethane", 0.1);
fluid.setMixingRule("classic");

ProcessSystem process = new DexpiSimulationBuilder(new File("plant.xml"))
    .setFluidTemplate(fluid)
    .setFeedPressure(50.0, "bara")
    .setFeedTemperature(30.0, "C")
    .setFeedFlowRate(1.0, "MSm3/day")
    .setAutoInstrument(true)
    .build();

process.run();

The builder performs these steps internally:

  1. Topology resolution — DexpiTopologyResolver parses <Equipment>, <Nozzle> and <Connection> elements into a directed graph, collapses inline piping components (valves, reducers) into equipment-level edges, and produces a topological ordering via Kahn’s algorithm. The resolver also detects cycles and logs warnings when cyclic dependencies are found; ResolvedTopology.hasCycle() can be queried programmatically.
  2. Equipment mapping — DexpiMappingLoader reads dexpi_equipment_mapping.properties and dexpi_piping_component_mapping.properties from the classpath to translate DEXPI ComponentClass strings (e.g. CentrifugalCompressor) into EquipmentEnum values.
  3. Equipment instantiation — DexpiEquipmentFactory creates real NeqSim equipment from the mapped enum, applying sizing attributes such as InsideDiameter, TangentToTangentLength, DesignPressure, ValveCv and Orientation. Distillation columns are instantiated with NumberOfTrays and FeedTray attributes when present. Column subtypes are detected from the DEXPI class name: absorbers (class containing “absorb”) are created without condenser or reboiler, and strippers (class containing “strip”) without a condenser.
  4. Stream wiring — The builder walks the topology in upstream-to-downstream order, connecting outlet streams of upstream equipment to inlets of downstream equipment.
  5. Auto-instrumentation — When enabled, DynamicProcessHelper.instrumentAndControl() adds transmitters and PID controllers to separators, compressors and heat exchangers. DEXPI instrument tags are matched to auto-generated transmitters by category prefix (e.g. PT- for pressure transmitters) and the auto-generated names are renamed to the actual DEXPI tag names. Controller tags are derived by replacing the function letter (e.g. PT-100 to PC-100).
  6. Namespace-aware parsing — The builder supports an optional setNamespaceAware(true) flag for DEXPI documents that use XML namespaces. When enabled, the underlying DOM parser and equipment factory use namespace-aware element resolution.

Sizing attributes

The following DEXPI GenericAttributes are automatically extracted and applied to equipment:

Attribute Applied to Effect
InsideDiameter Separators Sets setInternalDiameter()
TangentToTangentLength Separators Sets setSeparatorLength()
Orientation Separators Sets vertical orientation flag
DesignPressure Compressors, Valves Sets outlet pressure
DesignTemperature Heat exchangers Sets outlet temperature
ValveCv Valves Sets flow coefficient via setCv()
NumberOfTrays Distillation columns Sets number of trays
FeedTray Distillation columns Sets feed tray location

Round-trip profile and validation

The DexpiRoundTripProfile utility validates that a process contains the minimal metadata required for reliable imports and exports: runnable DexpiStream segments (with line/fluid references and operating conditions), tagged equipment, and at least one piece of equipment alongside the piping network. Regression tests enforce this profile on the reference training case and the re-imported export artefacts to guarantee round-trip fidelity.

Security considerations

Both the reader and writer configure their XML factories with hardened defaults:

These guardrails prevent XXE injection attacks and should be preserved if the parsing/serialisation logic is extended.

Generating PFD diagrams from DEXPI

The DexpiDiagramBridge class provides seamless integration between DEXPI imports and NeqSim’s PFD diagram generation system:

// One-step: import DEXPI and create diagram exporter
ProcessDiagramExporter exporter = DexpiDiagramBridge.importAndCreateExporter(
    Paths.get("plant.xml"));
exporter.exportDOT(Paths.get("diagram.dot"));
exporter.exportSVG(Paths.get("diagram.svg"));  // Requires Graphviz

// Full round-trip: import, simulate, diagram, export
ProcessSystem system = DexpiDiagramBridge.roundTrip(
    Paths.get("input.xml"),     // Input DEXPI
    Paths.get("diagram.dot"),   // Output DOT diagram
    Paths.get("output.xml"));   // Re-exported DEXPI with simulation results

The bridge automatically configures the diagram exporter to display DEXPI metadata (tag names, line numbers, fluid codes) alongside equipment labels.

Tested examples

Import test

DexpiXmlReaderTest imports the official C01V04-VER.EX01.xml training case from the DEXPI Training Test Cases repository. It verifies that expected equipment (heat exchangers, pumps, tanks, valves, piping segments) are discovered, streams remain active after process.run(), and exported metadata (pressure, temperature, flow, units) survives a round-trip reload.

Export / visualization tests

DexpiExportForViewerTest exercises five export scenarios:

  1. Gas processing — separator, compressor, cooler, valve with flow lines and equipment bars
  2. Two-stage compression — multi-stage compressor train with intercooling
  3. Official DEXPI example — reproduces the official DEXPI reference P&ID structure
  4. Instruments test — transmitters, PID controllers, signal lines, SIL markers, fail-position markers
  5. Professional P&ID — full-featured drawing with border, title block, stream table, symbol legend, revision history, battery limit

All five tests validate that the exported XML is well-formed and contains the expected DEXPI elements (Equipment, PipingComponent, PipingNetworkSystem, Drawing, ShapeCatalogue, etc.).