Professional process overview (A3 PFD + 16:9 slide)
One command turns the case-aware data set of a solved NeqSim model into a one-sheet A3 landscape
process flow diagram that communicates the whole process (feeds, sections, separation, compression,
pumping, heating/cooling, treatment, recycles, products) and a 16:9 presentation adaptation of the same
drawing. Everything is deterministic vector output with editable text and embedded fonts; nothing in the
simulation model is modified.
Toolkit (flat devtools/ modules, shared with the process-study report): ppo_graph (structured graph
and reductions), ppo_layout (hierarchical layout, routing, annotations, neqsim.pfd_layout.v1 spec),
ppo_render (styles, symbol library, sheet furniture, SVG/PDF/PNG exporters), ppo_validate
(validation record), process_overview (orchestrator + CLI), ppo_examples (synthetic test plant).
Layout engine, symbol geometry, label placement and detail sheets are reused from psr_diagrams;
the layout gate is pfd_layout_check (skill neqsim-pfd-layout-review).
Quick start
# from the data extracted by the process-study report (preferred: same numbers as the report)
neqsim process-overview <task>/deliverables/process_report/data/process_data.json --case A `
--out <task>/deliverables/process_overview --title-block <task>/inputs/overview_title_block.yaml
# directly from a model source (solved through process_report: model.py with build(case), process.json, plant.neqsim)
neqsim process-overview model.py --cases cases.yaml --case A --out out/overview
# options
# --level overview|engineering|presentation A3 information level (default overview)
# --detail-sheets collapsed|all|none A3 PFD sheets for sections drawn as blocks (default collapsed)
# --collapse "<section name>" force a section to block representation (repeatable)
# --config cfg.json --style style.json graph / style overrides (see below)
# --no-mono --no-presentation --no-embed-font --dpi 150 --quiet
# --no-supporting-slides keep main slides; A3 detail sheets unchanged
# --bands phase bands on the A3 sheet: gas top, oil middle, water bottom (off by default)
Without neqsim on PATH: <python> -m neqsim_cli process-overview ... (plugin install) or
<python> devtools/process_overview.py ... (checkout). Python: process_overview.build_overview(data, out_dir, ..., bands=...).
Outputs (--out folder)
| File |
Content |
overview_A3_colour.svg/.pdf/.png, overview_A3_mono.* |
A3 landscape 420 x 297 mm, frame with zones, legend, KEY STREAMS table, ISO 7200-style title block |
overview_16x9.*, overview_16x9_mono.*, overview_16x9_detail_NN.* |
13.33 x 7.5 in slide, same tags/numbers; one supporting slide per section drawn as a block |
detail_sheets/ |
psr_diagrams.build_pfd drawing set for the sections referenced on the overview (sheet PFD-nn) |
process_graph.json (+ process_graph_presentation.json, process_graph_drawn.json when sections were merged) |
structured source data: equipment, ports, streams, sections, trains, values of the case, mapping of every reduction |
layout_A3.json, layout_16x9.json, pfd_layout_spec_A3.json, pfd_layout_spec_16x9.json |
positions, routes, bubbles, bundles, fit attempts; the neqsim.pfd_layout.v1 specs for neqsim pfd-check |
validation.json, validation.md |
checks V01-V16 (see below), pfd_layout_check findings, limitations |
manifest.json |
files, page sizes, collapsed sections, refs, warnings, the exact regeneration command |
Procedure
- Source and case. Prefer the
process_data.json written by neqsim process-report (then drawing and
report share one extraction). State the case (--case); every displayed value is results[case] of that
file - never mix cases, never show design ratings as operating values.
- Title block. Write a YAML/JSON with
company, project, title, document_number, revision,
issue_status, date, drawn_by, model_source, notes, readiness_note. Leave checked_by /
approved_by unset ("not assigned") unless a person did it - never imply review or approval.
- Run the command; read
manifest.json (validation_status, collapsed_sections, fits, warnings).
- Inspect every drawing at full page (
view the PNG) and close-ups (crop dense regions): reading
direction, section titles, feed/product labels, stream bubbles vs. KEY STREAMS table, legend, title block,
mono variant separately (service is encoded by dash pattern there), the slide at normal viewing size.
- Run the layout gate
neqsim pfd-check <out>/pfd_layout_spec_A3.json <out>/pfd_layout_spec_16x9.json and note the
result in the task's pfd_layout_review/. CROSSING warnings are expected on dense overviews; errors must
be fixed by regeneration (config/style), never by hand-editing the SVG.
- Improve, regenerate, re-inspect. Typical levers (never shrink text below the readability target):
--collapse "<section>" for sections whose equipment belongs on a detail sheet;
--config {"section_groups": [{"name": "Compression", "sections": ["stage 3 train A", "stage 3 train B"]}]}
for a deliberate section hierarchy (A3) and presentation_groups for the slide story;
{"sections": {...}}, {"section_labels": {...}}, {"section_order": [...]} to rename or order sections;
{"annotate": ["S012", ...]} to choose the key streams; {"group_trains": "never"} to show both trains;
- style:
{"pt": {"tag": 10}, "section": {"gap_x": 14}, "annotation": {"style": "box"}}.
- Deliver the folder with
validation.md and a short limitation list (from validation.json) in the report.
What the drawing shows and how it is built
- Sections come from the model areas (
ProcessModel systems). They are placed left to right in
mass-flow order (weighted feedback-arc-set ordering), stacked vertically when parallel, and wrapped into
rows when the sheet is narrower than the process; connections between rows run in corridors with
shared tracks, returns and recycles are routed above/below or along the left margin.
- Inside a section the units are drawn with the Sugiyama engine of
psr_diagrams (layering, crossing
reduction, port ordering, orthogonal channels). Separators put gas out top, water out bottom.
- Reductions (recorded in
process_graph.json/mapping): numerical Recycle elements removed (stream
drawn to the real consumer, dashed); in-line valves absorbed into their stream (overview /
presentation level); >= 3 boundary feeds into one unit grouped (GF-<unit>, count and range shown);
identical parallel trains drawn once (tag xN); streams between two blocks bundled (xN mark).
- Fit strategy (A3 then slide): symbol scale -> block representation of the section that helps most
(detail on
sheet PFD-nn) -> single-unit sections as blocks -> stream bubbles limited to boundary streams
-> compact text step at the readability target (A3 7 pt, slide 9 pt) -> contiguous section groups.
Every step is logged in layout_*.json/attempts and the validation record.
- Values: boundary streams carry flow, T, P under their label; key cross-section streams carry a
stream-number bubble and appear in the KEY STREAMS table (t/h, C, bara; totals for shaft power and duties).
Standard conditions are stated in note 1.
- Small mass flows: use three significant figures, preserve signed nonzero flows and distinguish exact
zero from trace bounds below 0.001 kg/h. The table retains t/h, including scientific notation when needed;
the source JSON keeps full precision. See
docs/development/PROCESS_OVERVIEW.md for the formatting policy.
- Colour (project convention, Okabe-Ito palette, defined in the legend): gas vermilion, oil/condensate
bluish green, produced water blue, multiphase black, utility grey dashed, recycle dashed. The mono variant
encodes the service by dash pattern; the heavy line is the main path in both.
- Phase bands (
--bands, config "bands": true or {"gas": [...], "oil": [...], "water": [...]} of section ids, names or
model areas; off by default, A3 sheet only): Equinor TR2329 SR-15794 (three horizontal bands, gas flow on top, liquid below,
process flow left to right) and ISO 10628:1997 5.3.3 (left to right and top to bottom). Lanes top to bottom GAS / OIL / WATER
(empty lanes are not drawn), light lane backgrounds with a label in a 10 mm gutter, sections flow left to right inside a lane, a
row starts to the right of the column that feeds it, a boundary product of another phase (produced water) ends in a terminal
label in its own lane, counter-flow recycles are dashed. Each section is classified: (1) explicit mapping; (2) a separator with
two or more different gas/oil/water outlets, fed by a multiphase stream, in a section without compressor -> oil band; (3) otherwise
the majority of the gas/oil/water streams produced in or fed into the section (multiphase, unknown and utility streams do not vote,
a compressor adds one gas vote); (4) name keywords (water; gas, compress, fuel, flare; oil, condensate, export); (5) oil band. When
a lane row does not fit, the widest section of that lane is collapsed first, then compact text, then adjacent sections of the
same band are merged (never across bands). The manifest records the resulting bands mapping; the spec carries bands and
node["band"] so neqsim pfd-check reports BAND_NODE / BAND_EDGE. Python: ppo_graph.assign_bands, ppo_graph.bands_config,
ppo_layout.layout_overview(bands=...). Limits: lane labels are horizontal, the 16:9 version is not banded, name mappings do not
reach sections the fit merged automatically, and a 15-unit compression section still needs --no-supporting-slides for the slide
version. When the compressors and their utilisation must be visible on the sheet itself (debottlenecking), draw the one-sheet
PFD with PfdDiagram.phase_bands instead (skill neqsim-pfd-layout-review, section "Phase-band layout").
Standards basis (document what is used, claim nothing unverified)
| Topic |
Convention applied |
Note |
| Sheet |
ISO 5457: A3 420 x 297 mm, frame with 20 mm filing margin left / 10 mm elsewhere, zone grid, centring marks |
edition not verified against standard text |
| Title block |
ISO 7200 data fields: legal owner, identification number, title, revision, date, sheet, document type, status, creator/checker/approver, represented case |
fields that have not happened read "not assigned" |
| Content |
ISO 10628-1 PFD level: equipment, main flows, recycles, utility interfaces where modelled |
instrumentation only when it explains operation |
| Layout |
TR2329 v2.02 SR-15794 and Addendum 2.2.3.2: gas band on top, equipment / oil in the middle, liquid and water below, flow left to right; ISO 10628:1997 5.3.3 left to right and top to bottom |
--bands; edition of ISO 10628 read: 1997 (the library copy), the 2014 parts are not verified |
| Stream data |
TR2329 SR-15755 / 15756: stream number on every line, heat and material table at the bottom or on a separate sheet |
key streams table here, full table in the process report |
| Symbols |
ISO 10628-2 / ISO 14617 shapes shared with the process-study report |
documented in ppo_render.SYMBOL_LIBRARY |
Record the editions actually consulted in the task's standards register; the drawing note states
"editions not verified, conformance not claimed".
Validation (automatic, validation.md)
V01 unique traceable ids - V02 valid endpoints, no dangling legs - V03 every source area and boundary
stream represented - V04 explicit mapping for grouped/bundled/collapsed items - V05 displayed values
re-derived from the source case - V06 inside the frame - V07 label size >= target - V08 pfd_layout_check
(overlaps, line-through-box, crossings) - V09 PDF page size, embedded fonts, exports - V10 fits without
shrinking text - V11 stream data placed - V12-V14 the same for the 16:9 version - V15 every supporting
slide (fit, page bounds, process fonts, layout/arrows, source values, endpoints and annotations) - V16 main
slide fit. Failed supporting slides block export and write a validation record. Split their sections or use
supporting_slides=False / --no-supporting-slides, retaining A3 detail PFDs. Review each supporting slide's
overview_16x9_detail_NN_layout.json and _validation.json. Status FAIL blocks delivery.
Limitations
- Routing density: facilities with many inter-section streams end up at block level on A3 (the detail is on
the referenced sheets); crossings are counted, not eliminated.
- Utilities, drivers and non-modelled systems are not drawn; say so in the notes (
title_block.notes).
- Section quality follows the model's area structure - fix odd areas with
section_groups / section_labels.
- No instrumentation; use the P&ID workflows for that.
Related: process-study-report (data extraction, detail sheets, stream tables), neqsim-pfd-layout-review
(gate), neqsim-report-design-and-visual-qa, neqsim-professional-reporting.
1---2name: professional-process-overview3version: "1.0.0"4description: "Generates a professional one-sheet A3 process flow diagram (colour + monochrome, ISO 5457 / 7200 / 10628-2 conventions, embedded fonts, PDF + editable SVG) and a coordinated 16:9 presentation version from a solved NeqSim model or process_data.json, with detail sheets, a structured process graph and automatic validation. USE WHEN: a report, review or presentation needs the complete process on one overview sheet, a section-level process picture with traceable grouping, or a slide version of a PFD."5last_verified: "2026-11-01"6requires:7 python_packages: [pymupdf, matplotlib, fonttools, pyyaml]8metadata:9 source: https://skillmd.com/skills/equinor/professional-process-overview10---1112# Professional process overview (A3 PFD + 16:9 slide)1314One command turns the case-aware data set of a solved NeqSim model into a **one-sheet A3 landscape15process flow diagram** that communicates the whole process (feeds, sections, separation, compression,16pumping, heating/cooling, treatment, recycles, products) and a **16:9 presentation adaptation** of the same17drawing. Everything is deterministic vector output with editable text and embedded fonts; nothing in the18simulation model is modified.1920Toolkit (flat `devtools/` modules, shared with the process-study report): `ppo_graph` (structured graph21and reductions), `ppo_layout` (hierarchical layout, routing, annotations, `neqsim.pfd_layout.v1` spec),22`ppo_render` (styles, symbol library, sheet furniture, SVG/PDF/PNG exporters), `ppo_validate`23(validation record), `process_overview` (orchestrator + CLI), `ppo_examples` (synthetic test plant).24Layout engine, symbol geometry, label placement and detail sheets are reused from `psr_diagrams`;25the layout gate is `pfd_layout_check` (skill `neqsim-pfd-layout-review`).2627## Quick start2829```powershell30# from the data extracted by the process-study report (preferred: same numbers as the report)31neqsim process-overview <task>/deliverables/process_report/data/process_data.json --case A `32 --out <task>/deliverables/process_overview --title-block <task>/inputs/overview_title_block.yaml3334# directly from a model source (solved through process_report: model.py with build(case), process.json, plant.neqsim)35neqsim process-overview model.py --cases cases.yaml --case A --out out/overview3637# options38# --level overview|engineering|presentation A3 information level (default overview)39# --detail-sheets collapsed|all|none A3 PFD sheets for sections drawn as blocks (default collapsed)40# --collapse "<section name>" force a section to block representation (repeatable)41# --config cfg.json --style style.json graph / style overrides (see below)42# --no-mono --no-presentation --no-embed-font --dpi 150 --quiet43# --no-supporting-slides keep main slides; A3 detail sheets unchanged44# --bands phase bands on the A3 sheet: gas top, oil middle, water bottom (off by default)45```4647Without `neqsim` on PATH: `<python> -m neqsim_cli process-overview ...` (plugin install) or48`<python> devtools/process_overview.py ...` (checkout). Python: `process_overview.build_overview(data, out_dir, ..., bands=...)`.4950## Outputs (`--out` folder)5152| File | Content |53|---|---|54| `overview_A3_colour.svg/.pdf/.png`, `overview_A3_mono.*` | A3 landscape 420 x 297 mm, frame with zones, legend, KEY STREAMS table, ISO 7200-style title block |55| `overview_16x9.*`, `overview_16x9_mono.*`, `overview_16x9_detail_NN.*` | 13.33 x 7.5 in slide, same tags/numbers; one supporting slide per section drawn as a block |56| `detail_sheets/` | `psr_diagrams.build_pfd` drawing set for the sections referenced on the overview (`sheet PFD-nn`) |57| `process_graph.json` (+ `process_graph_presentation.json`, `process_graph_drawn.json` when sections were merged) | structured source data: equipment, ports, streams, sections, trains, values of the case, mapping of every reduction |58| `layout_A3.json`, `layout_16x9.json`, `pfd_layout_spec_A3.json`, `pfd_layout_spec_16x9.json` | positions, routes, bubbles, bundles, fit attempts; the `neqsim.pfd_layout.v1` specs for `neqsim pfd-check` |59| `validation.json`, `validation.md` | checks V01-V16 (see below), pfd_layout_check findings, limitations |60| `manifest.json` | files, page sizes, collapsed sections, refs, warnings, the exact regeneration command |6162## Procedure63641. **Source and case.** Prefer the `process_data.json` written by `neqsim process-report` (then drawing and65 report share one extraction). State the case (`--case`); every displayed value is `results[case]` of that66 file - never mix cases, never show design ratings as operating values.672. **Title block.** Write a YAML/JSON with `company`, `project`, `title`, `document_number`, `revision`,68 `issue_status`, `date`, `drawn_by`, `model_source`, `notes`, `readiness_note`. Leave `checked_by` /69 `approved_by` unset ("not assigned") unless a person did it - never imply review or approval.703. **Run** the command; read `manifest.json` (`validation_status`, `collapsed_sections`, `fits`, `warnings`).714. **Inspect every drawing** at full page (`view` the PNG) and close-ups (crop dense regions): reading72 direction, section titles, feed/product labels, stream bubbles vs. KEY STREAMS table, legend, title block,73 mono variant separately (service is encoded by dash pattern there), the slide at normal viewing size.745. **Run the layout gate** `neqsim pfd-check <out>/pfd_layout_spec_A3.json <out>/pfd_layout_spec_16x9.json` and note the75 result in the task's `pfd_layout_review/`. `CROSSING` warnings are expected on dense overviews; errors must76 be fixed by regeneration (config/style), never by hand-editing the SVG.776. **Improve, regenerate, re-inspect.** Typical levers (never shrink text below the readability target):78 - `--collapse "<section>"` for sections whose equipment belongs on a detail sheet;79 - `--config` `{"section_groups": [{"name": "Compression", "sections": ["stage 3 train A", "stage 3 train B"]}]}`80 for a deliberate section hierarchy (A3) and `presentation_groups` for the slide story;81 - `{"sections": {...}}`, `{"section_labels": {...}}`, `{"section_order": [...]}` to rename or order sections;82 - `{"annotate": ["S012", ...]}` to choose the key streams; `{"group_trains": "never"}` to show both trains;83 - style: `{"pt": {"tag": 10}, "section": {"gap_x": 14}, "annotation": {"style": "box"}}`.847. **Deliver** the folder with `validation.md` and a short limitation list (from `validation.json`) in the report.8586## What the drawing shows and how it is built8788- **Sections** come from the model areas (`ProcessModel` systems). They are placed left to right in89 mass-flow order (weighted feedback-arc-set ordering), stacked vertically when parallel, and wrapped into90 rows when the sheet is narrower than the process; connections between rows run in corridors with91 shared tracks, returns and recycles are routed above/below or along the left margin.92- **Inside a section** the units are drawn with the Sugiyama engine of `psr_diagrams` (layering, crossing93 reduction, port ordering, orthogonal channels). Separators put gas out top, water out bottom.94- **Reductions (recorded in `process_graph.json/mapping`)**: numerical `Recycle` elements removed (stream95 drawn to the real consumer, dashed); in-line valves absorbed into their stream (overview /96 presentation level); >= 3 boundary feeds into one unit grouped (`GF-<unit>`, count and range shown);97 identical parallel trains drawn once (`tag xN`); streams between two blocks bundled (`xN` mark).98- **Fit strategy** (A3 then slide): symbol scale -> block representation of the section that helps most99 (detail on `sheet PFD-nn`) -> single-unit sections as blocks -> stream bubbles limited to boundary streams100 -> compact text step at the readability target (A3 7 pt, slide 9 pt) -> contiguous section groups.101 Every step is logged in `layout_*.json/attempts` and the validation record.102- **Values**: boundary streams carry flow, T, P under their label; key cross-section streams carry a103 stream-number bubble and appear in the KEY STREAMS table (t/h, C, bara; totals for shaft power and duties).104 Standard conditions are stated in note 1.105- **Small mass flows**: use three significant figures, preserve signed nonzero flows and distinguish exact106 zero from trace bounds below 0.001 kg/h. The table retains t/h, including scientific notation when needed;107 the source JSON keeps full precision. See `docs/development/PROCESS_OVERVIEW.md` for the formatting policy.108- **Colour** (project convention, Okabe-Ito palette, defined in the legend): gas vermilion, oil/condensate109 bluish green, produced water blue, multiphase black, utility grey dashed, recycle dashed. The mono variant110 encodes the service by dash pattern; the heavy line is the main path in both.111- **Phase bands (`--bands`, config `"bands": true` or `{"gas": [...], "oil": [...], "water": [...]}` of section ids, names or112 model areas; off by default, A3 sheet only)**: Equinor TR2329 SR-15794 (three horizontal bands, gas flow on top, liquid below,113 process flow left to right) and ISO 10628:1997 5.3.3 (left to right and top to bottom). Lanes top to bottom GAS / OIL / WATER114 (empty lanes are not drawn), light lane backgrounds with a label in a 10 mm gutter, sections flow left to right inside a lane, a115 row starts to the right of the column that feeds it, a boundary product of another phase (produced water) ends in a terminal116 label in its own lane, counter-flow recycles are dashed. Each section is classified: (1) explicit mapping; (2) a separator with117 two or more different gas/oil/water outlets, fed by a multiphase stream, in a section without compressor -> oil band; (3) otherwise118 the majority of the gas/oil/water streams produced in or fed into the section (multiphase, unknown and utility streams do not vote,119 a compressor adds one gas vote); (4) name keywords (water; gas, compress, fuel, flare; oil, condensate, export); (5) oil band. When120 a lane row does not fit, the widest section of that lane is collapsed first, then compact text, then adjacent sections of the121 same band are merged (never across bands). The manifest records the resulting `bands` mapping; the spec carries `bands` and122 `node["band"]` so `neqsim pfd-check` reports `BAND_NODE` / `BAND_EDGE`. Python: `ppo_graph.assign_bands`, `ppo_graph.bands_config`,123 `ppo_layout.layout_overview(bands=...)`. Limits: lane labels are horizontal, the 16:9 version is not banded, name mappings do not124 reach sections the fit merged automatically, and a 15-unit compression section still needs `--no-supporting-slides` for the slide125 version. When the compressors and their utilisation must be visible on the sheet itself (debottlenecking), draw the one-sheet126 PFD with `PfdDiagram.phase_bands` instead (skill `neqsim-pfd-layout-review`, section "Phase-band layout").127128## Standards basis (document what is used, claim nothing unverified)129130| Topic | Convention applied | Note |131|---|---|---|132| Sheet | ISO 5457: A3 420 x 297 mm, frame with 20 mm filing margin left / 10 mm elsewhere, zone grid, centring marks | edition not verified against standard text |133| Title block | ISO 7200 data fields: legal owner, identification number, title, revision, date, sheet, document type, status, creator/checker/approver, represented case | fields that have not happened read "not assigned" |134| Content | ISO 10628-1 PFD level: equipment, main flows, recycles, utility interfaces where modelled | instrumentation only when it explains operation |135| Layout | TR2329 v2.02 SR-15794 and Addendum 2.2.3.2: gas band on top, equipment / oil in the middle, liquid and water below, flow left to right; ISO 10628:1997 5.3.3 left to right and top to bottom | `--bands`; edition of ISO 10628 read: 1997 (the library copy), the 2014 parts are not verified |136| Stream data | TR2329 SR-15755 / 15756: stream number on every line, heat and material table at the bottom or on a separate sheet | key streams table here, full table in the process report |137| Symbols | ISO 10628-2 / ISO 14617 shapes shared with the process-study report | documented in `ppo_render.SYMBOL_LIBRARY` |138139Record the editions actually consulted in the task's standards register; the drawing note states140"editions not verified, conformance not claimed".141142## Validation (automatic, `validation.md`)143144V01 unique traceable ids - V02 valid endpoints, no dangling legs - V03 every source area and boundary145stream represented - V04 explicit mapping for grouped/bundled/collapsed items - V05 displayed values146re-derived from the source case - V06 inside the frame - V07 label size >= target - V08 `pfd_layout_check`147(overlaps, line-through-box, crossings) - V09 PDF page size, embedded fonts, exports - V10 fits without148shrinking text - V11 stream data placed - V12-V14 the same for the 16:9 version - V15 every supporting149slide (fit, page bounds, process fonts, layout/arrows, source values, endpoints and annotations) - V16 main150slide fit. Failed supporting slides block export and write a validation record. Split their sections or use151`supporting_slides=False` / `--no-supporting-slides`, retaining A3 detail PFDs. Review each supporting slide's152`overview_16x9_detail_NN_layout.json` and `_validation.json`. Status FAIL blocks delivery.153154## Limitations155156- Routing density: facilities with many inter-section streams end up at block level on A3 (the detail is on157 the referenced sheets); crossings are counted, not eliminated.158- Utilities, drivers and non-modelled systems are not drawn; say so in the notes (`title_block.notes`).159- Section quality follows the model's area structure - fix odd areas with `section_groups` / `section_labels`.160- No instrumentation; use the P&ID workflows for that.161162Related: `process-study-report` (data extraction, detail sheets, stream tables), `neqsim-pfd-layout-review`163(gate), `neqsim-report-design-and-visual-qa`, `neqsim-professional-reporting`.