gtm-parametric-demo-reports

name	gtm-parametric-demo-reports
version	1.0.0
category	business
description	Create parametric engineering demo reports (HTML+PDF) for cold outreach to marine/offshore contractors. Data-first architecture: input DBs → parametric sweep → output DBs → comparison matrices → branded interactive report.
type	workflow
capabilities	["parametric_engineering_analysis","interactive_html_reports","vessel_structure_comparison","cold_outreach_collateral"]
requires	[]
trigger	manual

GTM Parametric Demo Reports

Workflow for building self-contained interactive HTML engineering reports as cold outreach sales collateral. The report IS the deliverable -- not a mockup.

When to Use

• Building demo/sample reports to send to prospective clients
• Creating parametric engineering studies that showcase capability
• Comparing vessels, structures, pipe sizes, or codes across a matrix
• Any "overnight engineering" demonstration

Cold Outreach Design Principles

1. Self-explanatory -- no one walks them through it; must stand alone
2. Case-count headline -- lead with volume: "108 cases screened overnight"
3. First 5 seconds matter -- the headline must trigger: "this would take my team 2 weeks"
4. Real deliverable feel -- not a toy, not a slide deck
5. Defensible engineering -- proper code clause refs, safety factors, material data; senior engineers will spot-check
6. LIVE MODE teaser -- plant seed for higher-value retainer: "In LIVE MODE, feed VMMS/IMMS for real-time go/no-go"

Data Architecture (Three Layers)

Layer 1: Input Databases (gtm/data/)

Create JSON databases per category BEFORE writing any demo code:

File	Purpose
pipelines.json	Pipe catalog: OD, WT schedules, grades, SMYS/SMTS, submerged weight
csv_hlv_vessels.json	Construction vessels: crane curves (SWL vs radius), dims, RAOs
pipelay_vessels.json	Pipelay vessels: tensioner capacity, stinger config, depth range
ctv_operability_<site>.json	CTV/SOV access-operability reference data: landing arrangements, monthly weather-window/workability, headline uplift metrics. Only place under gtm/data/ after explicit GTM-use/rights approval; otherwise keep in references/vessel-suitability/data/ as internal_reference_only.
mudmat_structures.json	Structures: dims, mass, CoG, hydro coefficients (C_s, C_D, C_a)
rigid_jumpers.json	Jumpers: length, OD, WT, mass per meter, total mass
freespan_scenarios.json	Environmental: currents, span lengths, soil types, gap ratios
design_codes.json	Code metadata: safety factors, clause refs, edition years

Key rule: Calculate derived values (mass/m, submerged weight) from first principles using a calc script, don't guess. Include _description, _version, _references in every JSON.

Layer 2: Output Results (gtm/results/)

One JSON per demo, array of case objects. Every case has:

{
  "case_id": "XXX-001",
  "inputs": { "vessel": {...}, "structure": {...}, "environment": {...} },
  "results": { "utilisation": N, "status": "PASS|FAIL", "governing_check": "..." },
  "code_ref": "DNV-RP-XXXX Sec Y.Z",
  "timestamp": "ISO-8601"
}

Create schema files with null result values BEFORE building the demo scripts. This forces you to think through the output structure.

Layer 3: Comparison Matrices (gtm/results/)

Two cross-demo aggregation files:

vessel_comparison_matrix.json -- "What can each vessel do?"

• Per vessel: go/no-go grid across all structures x depths
• Head-to-head: Vessel A vs B, where does one become limited?
• Overall score: total pass rate, strongest/weakest capability

structure_comparison_matrix.json -- "Which structure is hardest?"

• Per category: compare structures on same vessel at same depth
• Breakpoints: at what size/weight/length does it go from GO to NO_GO
• Code comparison: which code is most conservative, weight penalty %

Report Format (HTML + PDF)

• Primary: Interactive HTML with embedded Plotly (single .html file, works offline)
• Fallback: PDF via print-friendly CSS (@media print in same HTML)
• Both from same Python script
• Same-day client pack: when existing GTM HTML exists and the user needs PDFs immediately, generate a branded PDF pack directly from those HTML reports with headless Chrome, add a pack index, visible caveats, and a PDF-only ZIP for email. See references/client-pdf-packaging.md.
• Repo ecosystem flowchart collateral: when a prospect/pilot conversation needs a one-page explanation of how the engineering consulting repo ecosystem works, review live tier-1 repo roles, draft a self-contained HTML flowchart with clickable GitHub repo links, render to a one-page PDF, and verify page count/text/links. See references/repo-ecosystem-flowchart-collateral.md.
• Pipeline-company brochure pack: for pipeline/subsea prospects, package wall thickness multi-code screening, rigid jumper freespan/VIV screening, and optional rigid jumper installation/vessel suitability into a concise HTML+PDF+email bundle. See references/pipeline-company-brochure-pack.md.
• Field-development consulting outreach: when drafting email to a field development / subsea engineering consulting company, start from templates/field-development-consulting-outreach.md; lead with concrete analysis-pack deliverables, low-risk pilot framing, and a 30-minute review ask.
• Offshore intervention / HSE / riser outreach: for prospect-specific outreach around intervention, abandonment, HSE inputs, and riser/OrcaFlex automation, prepare a PII-safe strategy plan and minimum credible collateral packet before sending email. See references/offshore-intervention-hse-riser-outreach.md.

HTML Template Requirements

• digitalmodel branding (header, colors)
• Plotly charts (hover, zoom, pan)
• Color-coded pass/fail tables (green/red/amber)
• Methodology section with code clause references
• Assumptions and limitations footer
• LIVE MODE teaser section at bottom
• Case count in the title: "84 Freespan Cases Screened Overnight"

Workflow Steps

1. Discuss scope -- nail down parameter matrix, audience, pitch
2. Create input databases -- JSON files with real engineering values
3. Create output schemas -- empty result templates with null values
4. Create comparison matrix templates -- vessel x structure grids
5. Identify data gaps -- spin GH issues for missing data (e.g. vessel specs)
6. Build demo scripts -- start with demos that have all data available
7. Generate reports -- run scripts, populate results, build HTML
8. Populate comparison matrices -- aggregate across demos

Pitfalls

• Result filenames drift from demo names: don't infer result filenames from script names. For rigid jumper/freespan VIV, the verified output is results/demo_01_freespan_results.json (not demo_01_freespan_viv_results.json). Open the JSON metadata before declaring a result missing.
• Pipeline prospect collateral has a proven triad: wall thickness multi-code screening (Demo 2), rigid jumper freespan/VIV screening (Demo 1), and optional rigid jumper installation/vessel suitability (Demo 5). See references/pipeline-company-brochure-pack.md.
• Smaller installation vessel owner wedge: for regional CSV/MPSV/ROV-support owners and light-construction contractors, lead with vessel suitability rather than pipeline design: "one vessel data sheet + one representative jumper/mudmat/pipelay scope → client-ready GO/NO_GO envelope." Use practical tender-support language (capability envelope, limiting criterion, governing phase, crane/tensioner/deck-space bottlenecks) and keep PII outside Git. Reference pattern: aceengineer-strategy/pipeline/proposals/small-installation-vessel-owners-gtm-2026-05-07.md.
• Prospect-specific offshore automation outreach: when a named prospect requires intervention/abandonment, offshore HSE, and riser-analysis positioning, do not jump straight to an email. First verify public role context, keep private contact data out of Git, inspect worldenergydata and digitalmodel capability anchors, draft a strategy-side plan, create a tracking issue, and define the three one-pagers needed before send. See references/offshore-intervention-hse-riser-outreach.md.
• Outreach logs must be PII-safe: document sent emails in aceengineer-strategy/pipeline/conversations.md using role/company descriptors only; keep names and direct contact details out of Git.
• Prospect email language: use low-risk pilot / fixed-fee starter / 30-minute review language with concrete deliverables; avoid desperation or "survival pricing" framing. For field-development engineering consulting companies, emphasize early-phase option screening, subsea pipeline wall thickness, rigid jumper freespan/VIV, and vessel/installation suitability as reusable client-ready packs; use templates/field-development-consulting-outreach.md rather than drafting from scratch.
• Don't let missing data block everything: Create representative/generic databases, spin GH issues for real data, build demos with what you have. Swap real data in later.
• Vessel suitability has two layers: separate raw/reference intake and GTM packaging from deeper engineering implementation. Add a traceability index for the actual reference corpus reviewed, then create/link a GTM issue for scoring/report output rather than overloading the engineering anchor issue. See .

Shared Report Template (report_template.py)

The GTMReportBuilder class handles all branding, charts, and PDF export. Key API:

from report_template import GTMReportBuilder, COLORS, CHART_PALETTE

report = GTMReportBuilder(
    title="Pipeline Wall Thickness — Multi-Code Comparison",
    subtitle="72 parametric cases across 6 pipe sizes and 3 design codes",
    demo_id="demo_02",
    case_count=72,
    code_refs=["DNV-ST-F101 (2021)", "API RP 1111 (2015)", "PD 8010-2 (2015)"],
)
report.add_methodology("<p>...</p>")          # Goes first
report.add_chart("chart_id", plotly_fig, title="...", subtitle="...")
report.add_table("title", df, status_col="Status")  # Auto color-codes PASS/FAIL
report.add_live_mode_teaser("this analysis")  # VC funding + VMMS/IMMS pitch
report.add_assumptions(["assumption 1", "assumption 2"])
report.build("output/report.html")

Template features: Inter font, navy/orange brand colors, 8-color chart palette, animated LIVE badge, $500K VC funding badge, CTA mailto link, @media print for PDF.

Lifecycle Utilisation Chart Pattern (Wall Thickness Hero Chart)

The strongest visualization for pipeline demos: a single chart showing utilisation across ALL lifecycle phases with code comparison.

• X-axis: lifecycle phases (Installation, Hydrotest, Operation-Early, Operation-Late, Shutdown)
• Y-axis: utilisation ratio (0 to max, unity line at 1.0)
• Grouped bars: one per design code
• Dropdown selector: pipe size
• Color: green (<0.7), amber (0.7-0.9), red (>0.9)
• Use create_standard_phases(water_depth, design_pressure) + PhaseAnalysisRunner

This pattern applies to ANY parametric engineering demo -- show utilisation across conditions, not just pass/fail.

GIF Screencast Pattern (Issue #1809)

Each demo should produce a .gif showing the FULL WORKFLOW:

1. User types natural language prompt in CLI (3s)
2. Agent navigates digitalmodel codebase (5s)
3. Parametric analysis runs with case counter ticking (10s)
4. Report generated message (3s)
5. Browser showing interactive HTML with hover/zoom (10s)

Tool: vhs (charmbracelet/vhs) for reproducible scripted terminal GIFs. Target: <5MB, 20-30s, 1024x768.

Pre-Build Discussion Checklist (MANDATORY)

Before writing any code, resolve these with the user:

1. Who is the audience? Cold outreach vs follow-up vs live demo changes everything
2. What's the sales message? "Overnight engineering" vs "real-time ops" vs "cost savings"
3. Engineering rigor level? Real defensible calcs (slower, credible) vs approximate (faster, less impressive)
4. Data availability? Do we have vessel data or need GH issues to collect it?
5. Branding? digitalmodel vs aceengineer vs client-specific
6. Format? HTML primary + PDF fallback is the proven choice
7. Chart lineup? Discuss specific visualisations BEFORE building -- the user will have opinions on what tells the story

The user thinks in terms of "what chart will land the point" not "what data do we have." Start from the chart concept and work backwards to the engineering.

Lessons Learned

• Discuss before building: The user will course-correct the demo scope, format, and chart lineup. Items 3 and 5 were duplicates. The user added "rigid jumper" to item 5 mid-conversation. Discuss FIRST.
• Build order matters: Start with demos where modules already exist (wall thickness had full analyzer + parametric sweep + phase analysis). Demos needing new engineering calcs (freespan, catenary) take 2-3x longer.
• Mid-range WT from catalog gives better demo than minimum WT: Using minimum standard WT often shows 0.1 utilisation (boring). Mid-range shows variation across 0.2-1.4 (interesting PASS/FAIL mix).
• FAIL cases are a selling point: 16"/20" pipes all FAIL at mid-range WT -- this is GOOD for the demo. It shows "you would have caught this overnight." Don't sanitise results to all-PASS.
• Progress counter is part of the demo: Print "Case 42/72 | 12in X65 | DNV-ST-F101 | 20 MPa... util=0.716 [PASS]" -- this becomes the GIF content.
• Binary search for min WT: Finding minimum required wall thickness uses binary search with 0.1mm tolerance, not brute-force sweep. Much faster.
• Propagation buckling often governs at 500m+: At deepwater, collapse/propagation checks drive the design more than pressure containment. The demo should show this insight explicitly.
• PYTHONPATH setup: Scripts run with PYTHONPATH=examples/demos/gtm:src uv run python examples/demos/gtm/demo_XX.py
• try/except per case: Wrap individual parametric cases so one failure doesn't kill the sweep. Record failed cases as N/A in results JSON.
• First uv run takes ~17-20s for bytecode compilation (32K+ files). Subsequent runs are ~2-3s. Account for this in GIF timing -- either pre-warm or start the GIF after the compile step.
• Don't let missing vessel data block everything: Create generic databases immediately, spin GH issues for real data in parallel. The user explicitly said "create databases as needed" rather than wait.

Reference Implementation

Location: digitalmodel/examples/demos/gtm/

• report_template.py -- shared HTML builder (GTMReportBuilder class)
• data/ -- 7 input databases
• results/ -- 5 output schemas + 2 comparison matrices
• output/ -- generated HTML reports
• demo_02_wall_thickness_multicode.py -- reference demo (1116 lines, 72 cases, 5 charts)
• GitHub tracking: #1800 (master), #1798 (CSV/HLV data), #1799 (pipelay data), #1809 (GIF screencasts)