Flow-assurance study report
Turns a route + basis + cases into a reviewable flow-assurance report and drawing package with one
command. Sibling of process-study-report: the same architecture (one canonical dataset, data-bound
narrative tokens, drawings as data, fail-closed validation) with flow-assurance content. Calculation
patterns for hydrate, wax, corrosion and so on stay in neqsim-flow-assurance; this skill documents,
checks and draws a study. Nothing is invented: a value nobody sourced is unavailable - TO BE CONFIRMED.
Quick start
neqsim flow-assurance-report --init study_inputs # scaffold basis, route, cases, standards register
neqsim flow-assurance-report route.yaml --basis basis.yaml --cases cases.yaml --out report --strict
neqsim flow-assurance-report --demo --out demo # synthetic two-template tie-back (about 1 min)
neqsim flow-assurance-report study.json --basis basis.yaml # rebuild from a canonical dataset (no solve)
Without the neqsim command: <python> -m neqsim_cli flow-assurance-report ... or
<python> devtools/flow_assurance_report.py .... Options: --no-word, --no-mesh, --strict
(exit 1 on a validation FAIL), --task DIR (merge a summary block into results.json),
--external-results DIR (attach results from an external simulator), --standards FILE.
Exit codes: 0 ok, 1 strict validation failure, 2 input or usage error (nothing is written).
The shared fa_solver.neqsim_handle() adapter uses neqsim_dev_setup for source-checkout or installed-JAR
execution and reuses an active JVM. Do not import a top-level jneqsim Python module; the adapter returns
the Java neqsim package on the selected classpath, including when called from a SURF study.
Inputs
| File |
Holds |
Rules |
route.yaml |
assets (id, kind, x/y/elevation), segments (length, ID, roughness, ambient, burial, layers), route_status |
measured length; unique IDs; every number sourced; dz and the 3D chord are checked; one junction at most |
basis.yaml |
study and document metadata, fluids, solver, acceptance criteria, mitigation options, sources, assumptions, data gaps, optional review record |
criteria carry quantity, operator, value, unit, source and applies_to |
cases.yaml |
cases (role design/scenario/mitigation), topology variants, events |
mass rates by default; source pressures are CALCULATED, never inputs; MEG as lean stream or aqueous target wt |
standards_register.yaml |
standard, status, assessment status |
public metadata only; text not read means not assessed |
An unfilled template (unavailable - TO BE CONFIRMED where a number is required) is rejected with
exit 2. Templates: devtools/fa_templates/; synthetic examples: devtools/fa_examples/offshore_tieback/ (two sources, junction, PLEM)
and devtools/fa_examples/single_flowline/ (one source, one path).
What is calculated and what is not
| Analysis |
Method |
Status |
| Steady pressure, temperature, holdup, velocity, regime label |
PipeBeggsAndBrills chained per segment, SRK, backward solve for source pressures |
implemented; analytic checks only; no general experimental qualification |
| Hydrate equilibrium margin |
SRK-CPA hydrateFormationTemperature on a pressure grid (ln p interpolation), inhibited and uninhibited |
implemented; only secondary-source benchmarks; no field or laboratory validation |
| Inhibitor balance |
lean-MEG mass balance, aqueous mass fraction (never mole fraction) |
implemented; losses to gas and condensate NOT modelled |
| Cooldown to hydrate temperature |
lumped exponential (fluid plus steel) |
screening; not time to plug; insulation mass excluded |
| Erosional velocity ratio |
project C-factor criterion |
not a DNV-RP-O501 assessment |
| Wax, asphaltene, scale, CO2 corrosion |
threat matrix entry, open unless inputs supplied |
open with reason (never "safe") |
| Startup/restart, pigging, severe and terrain slugging, transients |
not supported; external-event JSON hand-off written |
unsupported - open |
Open or unsupported threats and unmet criteria stay visible in the executive summary, the action
register and the drawings. The only transient path is fa_handoff.two_fluid_profile (Python adapter for
a TwoFluidPipeResponse); the CLI does not ingest it - run the event in an external simulator and give
the result back through --external-results.
Outputs (--out)
report/ FA-...docx, .pdf (Word or LibreOffice; WARN FA-DOC-PDF when neither exists), validation_report.json/.md, report_facts.json
drawings/ svg/ (10 A3 sheets; 9 for a single-path route), png/, <doc>_drawings.pdf, layout_spec.json
dataset/ flow_assurance_study.json (schema flow_assurance_study.v1, hash in every title block)
handoff/ external-event JSON per open transient event
figures/ report figures cache/ per-case solver cache (keyed on inputs and NeqSim version)
Drawing sheets: 01 network schematic, 02 route plan, 03/04 longitudinal profiles per path, 05 riser and
PLEM arrangement, 06 pipe and thermal cross-sections, 07 velocity/erosional ratio/holdup, 08 hydrate
margin and critical sections, 09 operating-limit and threat summary, 10 transient and event sheet.
Every plotted series and annotation carries a data reference; FA-DRAW-DATA re-reads the dataset and
fails on disagreement.
Validation gates (validation_report.md)
Inputs, IDs, geometry, topology, criteria, fluid, solver convergence, finite values, mass balance,
boundary pressure, analytic benchmarks, validation status, mesh sensitivity (>= 10 increments per
segment; a 6-increment mesh changed a riser outlet temperature by 7.5 K in development), hydrate grid,
extrema, threats, events, standards verification, drawing QA/data/alignment/files/front-page, and
document checks (every [[token]] resolves with its unit, facts match the dataset, mandatory sections
present, open items shown, no unreplaced placeholder, figures, PDF). A FAIL makes the package a
NOT_READY diagnostic. WARN is acceptable only when explained in the report.
Readiness is NOT_READY / SCREENING / REVIEWED. REVIEWED needs a human review record in
basis.yaml, non-synthetic data and no open threat or data gap; the software never assigns it.
Agent procedure
Flow-diagram gate: schematic/network sheets and any PFD/BFD figure must pass neqsim pfd-check (skill
neqsim-pfd-layout-review, agent pfd-layout-review) before the report is issued; map/profile/chart sheets get the visual QA only.
- Read the task folder, then the route, basis and cases. Ask in ONE message only for what is missing:
objective, maturity, cases and rates, criteria and their sources, fluid/PVT, insulation and burial data.
--init, fill from sources, record every inspected source and gap. Never fill from memory.
- Run
--strict; open the PNG of every sheet and fix overlaps, clipped text and wrong direction arrows.
- Interpret each WARN. Do not suppress a gate to get a pass; fix the input or state the limit.
- Write narrative only from
report_facts.json and tokens; verify any standard before citing it
(neqsim-standards-lookup); never copy standard text.
- Hand off: open threats and unsupported transients to the community
flow-assurance-study-agent /
olga-simulation-agent (external), fluid issues to @thermo-fluid / @pvt-simulation, review to @review.
Pitfalls
- Mass vs mole: MEG "25 wt %" is a mass fraction in water + MEG; 5 mol MEG per 15 mol water is 53 wt %.
Use
fa_units.aqueous_inhibitor_moles.
- Backward solve: specify the host pressure and rates; source pressure is a result. A source
pressure above the available limit is a failed criterion, not an input to change.
- U-value basis:
SPECIFIED_U in PipeBeggsAndBrills refers to the INNER area (pi x ID x L); the
toolkit converts layered build-ups accordingly. Do not paste an outer-area U-value.
- Hydrate fluid: use light components plus water; C7+ pseudo-components can stall the hydrate solver.
- Rates: standard-volume rates need the standard conditions and a standard density; actual-volume rates need p and T.
- Extrapolation: inhibitor concentrations outside the verified range are not validated.
- Topology variants support
isolate_sources and isolate_segments only; bypass, reroute or added
segments raise an error (extension point: fa_geometry.apply_variant).
- Branching: one junction (common trunk) per study; nested junctions are rejected.
- Narrative is data-driven: report and drawing text must come from the dataset (case roles, criteria, extrema, mitigations),
never from case IDs, option names or limits of the demo. A second geometry (
single_flowline) is the regression test for this.
- Tokens need a format slot:
[[crit:C-HYD-01:BASE:value|.1f]], [[seg:FL-A-01:length_m|.0f|unit=km]].
References
- references/study_contract.md - dataset schema, token kinds, readiness rules
- references/standards_register_notes.md - what was verified and how
- Doc page:
docs/development/FLOW_ASSURANCE_STUDY_REPORT.md (snippets are test-verified)
- Related:
neqsim-flow-assurance, process-study-report, neqsim-professional-reporting,
neqsim-standards-lookup, neqsim-pipeline-survey-processing, neqsim-water-hammer
1---2name: neqsim-flow-assurance-study-report3version: "1.0.0"4description: "Produces a validated flow-assurance study report (Word/PDF) and ten A3 pipeline drawing sheets from a route, basis and cases: hydrate margin, cooldown, hydraulics, MEG balance, threat matrix, mitigations, hand-offs, fail-closed validation. USE WHEN: a flow-assurance report, tie-back/pipeline drawings or hydrate/cooldown screening documentation is requested. Calculation patterns: neqsim-flow-assurance."5last_verified: "2026-10-25"6requires:7 python_packages: [python-docx, matplotlib, pymupdf, pyyaml, jpype1]8metadata:9 source: https://skillmd.com/skills/equinor/neqsim-flow-assurance-study-report10---1112# Flow-assurance study report1314Turns a **route + basis + cases** into a reviewable flow-assurance report and drawing package with one15command. Sibling of `process-study-report`: the same architecture (one canonical dataset, data-bound16narrative tokens, drawings as data, fail-closed validation) with flow-assurance content. Calculation17patterns for hydrate, wax, corrosion and so on stay in `neqsim-flow-assurance`; this skill documents,18checks and draws a study. Nothing is invented: a value nobody sourced is `unavailable - TO BE CONFIRMED`.1920## Quick start2122```powershell23neqsim flow-assurance-report --init study_inputs # scaffold basis, route, cases, standards register24neqsim flow-assurance-report route.yaml --basis basis.yaml --cases cases.yaml --out report --strict25neqsim flow-assurance-report --demo --out demo # synthetic two-template tie-back (about 1 min)26neqsim flow-assurance-report study.json --basis basis.yaml # rebuild from a canonical dataset (no solve)27```2829Without the `neqsim` command: `<python> -m neqsim_cli flow-assurance-report ...` or30`<python> devtools/flow_assurance_report.py ...`. Options: `--no-word`, `--no-mesh`, `--strict`31(exit 1 on a validation FAIL), `--task DIR` (merge a summary block into `results.json`),32`--external-results DIR` (attach results from an external simulator), `--standards FILE`.33Exit codes: 0 ok, 1 strict validation failure, 2 input or usage error (nothing is written).3435The shared `fa_solver.neqsim_handle()` adapter uses `neqsim_dev_setup` for source-checkout or installed-JAR36execution and reuses an active JVM. Do not import a top-level `jneqsim` Python module; the adapter returns37the Java `neqsim` package on the selected classpath, including when called from a SURF study.3839## Inputs4041| File | Holds | Rules |42|------|-------|-------|43| `route.yaml` | assets (id, kind, x/y/elevation), segments (length, ID, roughness, ambient, burial, layers), `route_status` | measured length; unique IDs; every number sourced; dz and the 3D chord are checked; one junction at most |44| `basis.yaml` | study and document metadata, fluids, solver, acceptance criteria, mitigation options, sources, assumptions, data gaps, optional `review` record | criteria carry quantity, operator, value, unit, source and `applies_to` |45| `cases.yaml` | cases (role design/scenario/mitigation), topology variants, events | mass rates by default; source pressures are CALCULATED, never inputs; MEG as lean stream or aqueous target wt |46| `standards_register.yaml` | standard, status, assessment status | public metadata only; text not read means not assessed |4748An unfilled template (`unavailable - TO BE CONFIRMED` where a number is required) is rejected with49exit 2. Templates: `devtools/fa_templates/`; synthetic examples: `devtools/fa_examples/offshore_tieback/` (two sources, junction, PLEM)50and `devtools/fa_examples/single_flowline/` (one source, one path).5152## What is calculated and what is not5354| Analysis | Method | Status |55|----------|--------|--------|56| Steady pressure, temperature, holdup, velocity, regime label | `PipeBeggsAndBrills` chained per segment, SRK, backward solve for source pressures | implemented; analytic checks only; **no general experimental qualification** |57| Hydrate equilibrium margin | SRK-CPA `hydrateFormationTemperature` on a pressure grid (ln p interpolation), inhibited and uninhibited | implemented; only secondary-source benchmarks; no field or laboratory validation |58| Inhibitor balance | lean-MEG mass balance, aqueous mass fraction (never mole fraction) | implemented; losses to gas and condensate NOT modelled |59| Cooldown to hydrate temperature | lumped exponential (fluid plus steel) | screening; not time to plug; insulation mass excluded |60| Erosional velocity ratio | project C-factor criterion | not a DNV-RP-O501 assessment |61| Wax, asphaltene, scale, CO2 corrosion | threat matrix entry, open unless inputs supplied | open with reason (never "safe") |62| Startup/restart, pigging, severe and terrain slugging, transients | **not supported**; external-event JSON hand-off written | unsupported - open |6364Open or unsupported threats and unmet criteria stay visible in the executive summary, the action65register and the drawings. The only transient path is `fa_handoff.two_fluid_profile` (Python adapter for66a `TwoFluidPipeResponse`); the CLI does not ingest it - run the event in an external simulator and give67the result back through `--external-results`.6869## Outputs (`--out`)7071```72report/ FA-...docx, .pdf (Word or LibreOffice; WARN FA-DOC-PDF when neither exists), validation_report.json/.md, report_facts.json73drawings/ svg/ (10 A3 sheets; 9 for a single-path route), png/, <doc>_drawings.pdf, layout_spec.json74dataset/ flow_assurance_study.json (schema flow_assurance_study.v1, hash in every title block)75handoff/ external-event JSON per open transient event76figures/ report figures cache/ per-case solver cache (keyed on inputs and NeqSim version)77```7879Drawing sheets: 01 network schematic, 02 route plan, 03/04 longitudinal profiles per path, 05 riser and80PLEM arrangement, 06 pipe and thermal cross-sections, 07 velocity/erosional ratio/holdup, 08 hydrate81margin and critical sections, 09 operating-limit and threat summary, 10 transient and event sheet.82Every plotted series and annotation carries a data reference; `FA-DRAW-DATA` re-reads the dataset and83fails on disagreement.8485## Validation gates (`validation_report.md`)8687Inputs, IDs, geometry, topology, criteria, fluid, solver convergence, finite values, mass balance,88boundary pressure, analytic benchmarks, validation status, mesh sensitivity (>= 10 increments per89segment; a 6-increment mesh changed a riser outlet temperature by 7.5 K in development), hydrate grid,90extrema, threats, events, standards verification, drawing QA/data/alignment/files/front-page, and91document checks (every `[[token]]` resolves with its unit, facts match the dataset, mandatory sections92present, open items shown, no unreplaced placeholder, figures, PDF). A FAIL makes the package a93`NOT_READY` diagnostic. WARN is acceptable only when explained in the report.9495Readiness is `NOT_READY` / `SCREENING` / `REVIEWED`. `REVIEWED` needs a human review record in96`basis.yaml`, non-synthetic data and no open threat or data gap; **the software never assigns it.**9798## Agent procedure99100**Flow-diagram gate:** schematic/network sheets and any PFD/BFD figure must pass `neqsim pfd-check` (skill101`neqsim-pfd-layout-review`, agent `pfd-layout-review`) before the report is issued; map/profile/chart sheets get the visual QA only.1021031. Read the task folder, then the route, basis and cases. Ask in ONE message only for what is missing:104 objective, maturity, cases and rates, criteria and their sources, fluid/PVT, insulation and burial data.1052. `--init`, fill from sources, record every inspected source and gap. Never fill from memory.1063. Run `--strict`; open the PNG of every sheet and fix overlaps, clipped text and wrong direction arrows.1074. Interpret each WARN. Do not suppress a gate to get a pass; fix the input or state the limit.1085. Write narrative only from `report_facts.json` and tokens; verify any standard before citing it109 (`neqsim-standards-lookup`); never copy standard text.1106. Hand off: open threats and unsupported transients to the community `flow-assurance-study-agent` /111 `olga-simulation-agent` (external), fluid issues to `@thermo-fluid` / `@pvt-simulation`, review to `@review`.112113## Pitfalls114115- **Mass vs mole**: MEG "25 wt %" is a mass fraction in water + MEG; 5 mol MEG per 15 mol water is 53 wt %.116 Use `fa_units.aqueous_inhibitor_moles`.117- **Backward solve**: specify the host pressure and rates; source pressure is a result. A source118 pressure above the available limit is a failed criterion, not an input to change.119- **U-value basis**: `SPECIFIED_U` in `PipeBeggsAndBrills` refers to the INNER area (pi x ID x L); the120 toolkit converts layered build-ups accordingly. Do not paste an outer-area U-value.121- **Hydrate fluid**: use light components plus water; C7+ pseudo-components can stall the hydrate solver.122- **Rates**: standard-volume rates need the standard conditions and a standard density; actual-volume rates need p and T.123- **Extrapolation**: inhibitor concentrations outside the verified range are not validated.124- **Topology variants** support `isolate_sources` and `isolate_segments` only; bypass, reroute or added125 segments raise an error (extension point: `fa_geometry.apply_variant`).126- **Branching**: one junction (common trunk) per study; nested junctions are rejected.127- **Narrative is data-driven**: report and drawing text must come from the dataset (case roles, criteria, extrema, mitigations),128 never from case IDs, option names or limits of the demo. A second geometry (`single_flowline`) is the regression test for this.129- Tokens need a format slot: `[[crit:C-HYD-01:BASE:value|.1f]]`, `[[seg:FL-A-01:length_m|.0f|unit=km]]`.130131## References132133- [references/study_contract.md](references/study_contract.md) - dataset schema, token kinds, readiness rules134- [references/standards_register_notes.md](references/standards_register_notes.md) - what was verified and how135- Doc page: `docs/development/FLOW_ASSURANCE_STUDY_REPORT.md` (snippets are test-verified)136- Related: `neqsim-flow-assurance`, `process-study-report`, `neqsim-professional-reporting`,137 `neqsim-standards-lookup`, `neqsim-pipeline-survey-processing`, `neqsim-water-hammer`