neqsim-professional-reporting

# NeqSim Professional Reporting Skill What separates "an answer" from a **professional deliverable**: traceability, unit hygiene, citation discipline, structured `results.json`, and a report narrative that matches the way senior engineers communicate. ## When to Use - Finalizing any task report under `task_solve/` - Building Jupyter notebook deliverables (study-grade, not exploratory) - Producing FEED-quality memos, technical notes, or design basis documents - Any output that will be read by a reviewer, client, or auditor ## Principle 0 — Analytical depth (what makes a report worth reading) Principles 1–10 are **hygiene**: they stop a report being wrong or unreadable. They do not make it *useful*. A hygienic report that restates the originating memo, lists contributors without ranking them, and ends in "further study is recommended" passes every checklist below and tells the reader nothing they did not already know. The depth of a report is set in the **study**, not in the write-up. Plan for these moves while the analysis is still running — most of them cannot be added afterwards. ### The nine depth moves Aim for **≥ 6 of 9** on a Standard report and **all 9** on a Comprehensive or root-cause/problem-solving report. Record the score in `results.json` (`depth_score`) and name the moves that were not achievable and why. | # | Move | What it looks like | Anti-pattern it replaces | |---|------|--------------------|--------------------------| | 1 | **Rank the contributors on one common basis** | A single table of every candidate cause with an improvement factor or utilisation number, computed the same way, so they are directly comparable | An unranked bullet list of "contributing factors" | | 2 | **Adjudicate the source document's own conclusions** | A verdict table over each recommendation of the originating memo/PEPR/notification: *Supported / Supported with a correction / Challenged*, each with the number that decides it | Silently agreeing with the source, or silently ignoring it | | 3 | **Rule things out, quantitatively** | "Thermal cycling does not explain this, by three orders of magnitude" — a competing explanation eliminated with a number and a stated margin | Leaving every hypothesis nominally alive | | 4 | **Find what the source document missed** | A contributor, coupling, or second-order consequence absent from the originating document, established from evidence — and stated as such | Answering only the question as posed | | 5 | **Test the conclusion's robustness and say where it flips** | A sensitivity table over the one or two genuinely uncertain modelling parameters, plus the explicit crossover point: "the top two swap around a slope of ~0.7, but the headline does not depend on it" | A single-point answer with an unquantified caveat | | 6 | **State the direction of every conservatism** | Each screening value, default, and correlation labelled as an upper or lower bound on the reported quantity, so the reader knows which way the number can move | Undirected "this is approximate" | | 7 | **Name the cheapest discriminating test** | The single measurement or inspection that would confirm or refute the diagnosis, why it discriminates, and what each outcome would mean | A generic "further investigation is recommended" | | 8 | **Report what does not fit** | The observation that disagrees with the model, reported as a disagreement rather than smoothed over or omitted | Presenting only corroborating evidence | | 9 | **Convert qualitative asks into specifications** | "Effective oxygen exclusion" → a purity table with the consequence of each grade; "improve filtration" → a micron rating with the mechanism that sets it | Repeating the source's qualitative wording back | #### Write the moves into `results.json` — the report renders them The depth work has to reach the reader. `generate_report.py` emits an **Analytical Depth** section (Word and HTML) from these keys, turning a list of dicts into a numbered table and anything else into bullets: | `results.json` key | Move | |--------------------|------| | `contributor_ranking` | 1 — contributors on one basis | | `source_recommendation_assessment` | 2 — verdict per source recommendation | | `ruled_out` | 3 — quantitative rule-outs | | `robustness` | 5 — sensitivity and the crossover | | `conservatism` | 6 — direction of each conservatism | | `discriminating_test` | 7 — the cheapest discriminating test | | `evidence_against` | 8 — evidence that does not fit | ```json "contributor_ranking": [ {"contributor": "Shell-side fouling", "share_pct": 62, "basis": "duty deficit vs design"}, {"contributor": "Seawater inlet temperature", "share_pct": 21, "basis": "duty deficit vs design"} ], "ruled_out": [ {"hypothesis": "Tube leak", "test": "Chloride in condensate", "margin": "5 mg/l vs 250 mg/l threshold"} ], "discriminating_test": {"test": "Single-point wall-thickness UT at the first bend", "decides": "Erosion vs fouling", "cost": "1 shift, no shutdown"}, "depth_score": "7/9" ``` `devtools/validate_task_results.py` warns when a study that has figure discussion, uncertainty, or a risk register reports fewer than two of them — that combination means the task was past quick-answer scale and the depth work should exist. If the moves were not achievable, say which and why rather than leaving the keys out. ### Two further depth habits - **Look for the natural experiment in the data.** Near-identical units with different duty, a repaired section that failed again, a period with a barrier out of service — these discriminate between hypotheses far more cheaply than any model. Actively search the fleet/historian/maintenance record for one. - **Bound rather than assert.** When a value cannot be measured, compute what it would have to be for the conclusion to change ("the screening factor of 4.0 would require a shear ratio of 16; this geometry produces 2.74"). A bounded unknown is a result; an asserted unknown is a gap. ### Numerical results earn their own subsection Any non-trivial computed result (CFD, FEM, transient, Monte Carlo, optimiser) gets: **validation against an analytical or independent value first**, then a **convergence/mesh/sample-count check**, then the result, then an explicit statement of **what the computation does and does not decide**. A quantity that still moves with refinement is an artefact and must be reported as one — report the converged averaged measures, not the unconverged point maximum. ### Report skeleton for a problem-solving / root-cause / PEPR report ``` Executive summary ranking table + the conclusion that inverts or confirms the source document + N further findings (count them; keep the count in sync) 0. Design/evidence basis what was retrieved, with document ids and revisions, and the two or three basis facts that change the reading 1..n Findings one section per finding, each: observation (numbers) → mechanism (physics) → implication (for the decision) → recommendation (specific action) n+1 Robustness sensitivity table + where the conclusion flips n+2 Ruled out each eliminated hypothesis with its quantitative margin n+3 Assessment of the verdict table over the source document's own source's recommendations recommendations n+4 What remains open per-finding, not one lumped register; each with the test that would close it and its owner ``` Every section that reaches a conclusion ends with **"what remains open"** for that conclusion specifically. One consolidated gap register at the end of a report is where gaps go to be ignored. ### Depth failure modes to check for before sending | Symptom | What it means | |---------|---------------| | The report's recommendations are the source document's recommendations | Moves 1–4 were not attempted | | Every hypothesis is still "possible" | Move 3 was not attempted | | The only number in the executive summary is a restatement of the input | The study produced description, not analysis | | "Further study is recommended" with no named test | Move 7 was not attempted | | No sentence in the report contradicts anything | Moves 2, 4, and 8 were not attempted — verify this is genuinely the case, not avoidance | ## Principle 1 — Traceability Chain (MANDATORY) Every figure → discussion → result must be linkable both ways: ``` results.json[key] ──→ discussed in §3.2 ──→ shown in figures/fig_03.png ↑ ↓ └──── caption references key ────────────┘ ``` Required JSON schema fragment: ```json { "figures": [ { "id": "fig_03", "path": "figures/fig_03_phase_envelope.png", "caption": "Phase envelope at 95 mol% methane composition.", "discussed_in": "section_3_2", "linked_results": ["dew_point_T_K", "cricondentherm_K"] } ], "results": { "dew_point_T_K": {"value": 244.3, "unit": "K", "source": "neqsim TPflash"}, "cricondentherm_K": {"value": 254.8, "unit": "K", "source": "calcPTphaseEnvelope"} } } ``` ## Principle 2 — Executive Summary Structure Every report opens with a 1-page executive summary built from these blocks (in order): 1. **Objective** — one sentence: "Determine X for Y under Z conditions." 2. **Method** — one sentence: "Using EOS / equipment model / standard X." 3. **Key result** — 2–3 numbers with units and uncertainty (P10/P50/P90 if Monte Carlo run) 4. **Conclusion** — one sentence with the engineering decision 5. **Limitations** — 1–2 bullets on key caveats The executive summary and problem description are report-blocking sections. Do not leave template text such as "[Replace with ...]" or "[Auto-populated ...]" in a final HTML/Word report. If `results.json` and `task_spec.md` contain enough information, generate these sections automatically from those sources; otherwise pause and fill the missing source material before finalizing. ## Principle 3 — Units & Significant Figures - **State units everywhere** — `bara`, `°C`, `kg/h`, `MJ/Sm³`, never bare numbers - **Significant figures match accuracy** — 3 sig fig for thermo; 2 for cost; never more than 4 unless source is exact - **Consistent within report** — pick one set (SI, °C/bara) and don't switch - **Standard conditions** — always disclaim Sm³ basis (15 °C / 1.01325 bara, or 20 °C, or 0 °C — they differ ~5%) - **Stream tables** — use standardized columns: name, T [°C], P [bara], ṁ [kg/h], xi [mol%] - **Tables: one value per cell.** Never write `"12.3 / 4.5"` or `"bias / MAE"` in a cell; give each quantity its own column (or row) with the unit in the header and the same number of decimals down a column. Keep a table to at most nine columns and split wide ones by topic (for example one table for pressure and one for temperature per well). For results over several days or cases put the days in the columns and the quantities in the rows, mark the calibration day `(cal)`, and use a separate table per quantity group. `validate_task_results.py` warns on both. ## Principle 4 — Citations For every standard, correlation, or vendor source: ```markdown Per **API 521 §5.15 (2020)**, fire heat input is Q = C × F × A_w^0.82 [API521-2020]. References: [API521-2020] API Standard 521, Pressure-Relieving and Depressuring Systems, 7th ed., 2020. [NORSOK-P-100] NORSOK Standard P-100, Process Systems, Rev. 3, 2018. [Turton-5e] Turton et al., Analysis, Synthesis and Design of Chemical Processes, 5th ed., 2018. ``` Avoid: "as is well known", "industry standard says". State the source. ## Principle 5 — Math (KaTeX) For documents rendered through Jekyll docs site: ```markdown Inline: the acentric factor $\omega$ affects $\alpha(T_r, \omega)$. Display: $$ P = \frac{RT}{v - b} - \frac{a(T)}{v(v + b)} $$ ``` Never use `\[ ... \]` or `\( ... \)` — they are stripped by markdown processors. ## Principle 6 — Figure Quality Every plot must have: - **Axis labels with units** — `Pressure [bara]`, not `P` - **Title** — what is shown, at what conditions - **Legend** — even with 1 series (states what is plotted) - **Grid** — minor or major, increases readability - **Annotation of key values** — pinch point, surge line, design point - **Resolution** — ≥ 150 DPI for embedding, vector (SVG/PDF) preferred for line plots ```python fig, ax = plt.subplots(figsize=(8, 5), dpi=150) ax.plot(T, P, label="Phase envelope") ax.scatter([T_op], [P_op], color="red", marker="x", s=80, label="Operating point") ax.set_xlabel("Temperature [K]") ax.set_ylabel("Pressure [bara]") ax.set_title("Phase envelope — sales gas, 95% C1") ax.legend(loc="best", fontsize=9) ax.grid(alpha=0.3) fig.tight_layout() fig.savefig("figures/fig_03_phase_envelope.png", dpi=150) ``` ## Principle 7 — Uncertainty Disclosure Standard / Comprehensive task reports MUST include: - **Monte Carlo with P10 / P50 / P90** for any economic or reservoir-tied output - **Tornado diagram** ranking inputs by impact on the key output - **Sensitivity scan** to top-3 driving inputs - **AACE class declaration** for any cost number (Class 5: ±100%, Class 4: ±50%, Class 3: ±30%) Quick tasks may skip MC but still must state qualitative uncertainty. **`uncertainty` sub-schema (validated by the gate).** `p10`, `p50`, `p90` must be **numeric** and **monotonically ordered** (`p10 ≤ p50 ≤ p90`); a non-numeric or out-of-order percentile is a hard error in both `TaskResultValidator` and `devtools/validate_task_results.py`. Include `method` and `n_simulations` (≥ 200 when the Monte Carlo loop runs full NeqSim simulations). The community skill `neqsim-uncertainty-quantification` emits this block directly (`UncertaintyReport.to_results_json()`), in the correct ascending convention, with the sampler and seed, the tornado, a convergence check, and a `blockers` field. Note the trap it guards: `p10` here is the 10th percentile (the *low* estimate), the opposite of the petroleum resource convention where P10 is the optimistic volume. State which convention a resource table uses. ## Principle 8 — Risk Section Standard / Comprehensive reports include a **risk register** scored on a 5×5 matrix (probability × consequence) per ISO 31000 / NORSOK Z-013, with mitigation actions. Use [`neqsim-process-safety`](../neqsim-process-safety/SKILL.md) classes. ## Principle 9 — Benchmark Validation Every numerical result must be benchmarked against an independent reference: | Output | Benchmark | | ----------------------- | ------------------------------------------------------- | | Phase envelope | Lab CME / CVD / GERG-2008 reference | | Equipment cost | Vendor budget quote OR another correlation | | Heat duty | Hand check: Q = ṁ × cp × ΔT | | PSV size | Independent calc per API 520 worked example | | NPV | Two methods: DCF and (NPV/CAPEX) ratio | State the benchmark in the report. **No benchmark = result is provisional.** **`benchmark_validation` sub-schema (validated by the gate).** Emit it as a JSON array (or an object wrapping `benchmarks`/`cases`). Each entry must carry: | Field | Purpose | |-------|---------| | `what` / `name` / `output` / `parameter` | what was compared | | `reference` / `source` / `benchmark` / `reference_value` | the independent reference | | `delta_pct` / `deviation_pct` / `status` / `neqsim_value` | the comparison result | | `status` (optional) | one of `PASS`, `FAIL`, `WARN`, `INFO` (any other value is rejected) | | `disposition` (optional) | why a `FAIL` stands, e.g. two published input sources disagree and nothing was tuned | A `FAIL` above 20% deviation is an ERROR ("model may need retuning") unless it carries a written `disposition`; then it is reported as a documented finding. Use it only when the deviation is not a model misfit: a conflict between two input sources, or a cross-check of an alternative model that the deliverable does not use. Still name the failure in