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

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

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.

1. 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.
2. --init, fill from sources, record every inspected source and gap. Never fill from memory.
3. Run --strict; open the PNG of every sheet and fix overlaps, clipped text and wrong direction arrows.
4. Interpret each WARN. Do not suppress a gate to get a pass; fix the input or state the limit.
5. Write narrative only from report_facts.json and tokens; verify any standard before citing it (neqsim-standards-lookup); never copy standard text.
6. 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