Assumptions (the assumption book)

Preliminary — this area is being deepened. The assumption book works today and is canonical, but its sourcing surface is an early version. See Where this is heading — do not read this page as a final design.

In simple terms

Every number the engines use — a CAPEX, an efficiency, a WACC — lives in the project’s assumption book. The Assumptions room is where you read and edit them. The book is canonical: change a number here and every result changes, because the engines read from the book, not from hard-coded defaults.

Why it exists

Transparency is the product’s whole positioning: no black box. A single, editable, versioned book means a developer can see exactly what drives a result, override any value, and trace where it came from — the opposite of numbers baked into code.

Where it lives

Room: frontend/src/rooms/assumptions/AssumptionsRoom.tsx; the per-parameter provenance panel is the shared components/ParamDetail.tsx (reused in Settings/DAB).
Backend: core/parameters/ (registry, book.py → typed params, references.py provenance); stored in the assumption_values table (see data model).

How it works, step by step

Structure. Rows are grouped into collapsible domain sections (Generation, Hydrogen, Water, Derivatives, CO₂, Financials) with fine group sub-headers, plus search, an “overridden only” filter, and expand/collapse-all. A “Used by” stage filter (All / Prefeas / Feas / Financing) hides params that don’t apply to the stage you’re in.
Editing. Change a value → it writes to the working book (source becomes user) and the cockpit re-solves. Numeric inputs are locale-safe (parseDecimal). Values are range-validated against the registry — an out-of-range edit is rejected with a specific message, exactly like the Excel import.
Provenance (per row). Expand a row (▸) to the ParamDetail card: a confidence chip (literature / indicative), the source family + year, the literature range and rationale, candidate value chips (adopt a published value in one click), a reset-to-default, and a free-text caveat note that round-trips through Excel and never dirties a solve.
Versioning. The book is one axis of the project’s two version axes (see the feature index): save / save-as / switch a whole assumption set via the book version bar in the Assumptions tab’s header. Distinct from snapshots (which capture results too).
Excel round-trip. Export the book to the standard workbook, edit offline, and STRICT-import it back (structure/units/ranges validated → diff preview → confirm). See the document standard.

Provenance honesty (today)

The curated references are indicative pointers to public report families (IRENA / IEA / DEA / NREL classes) — not page-precise citations. They orient you; they are not a substitute for your own verification before FEED. The project’s source ladder dab < user < quote < contract still outranks any reference: a number you entered or quoted beats a default.

Where this is heading

Ratified direction (2026-07-13) — not yet built. The assumption surface will be deepened so each relevant assumption becomes robust and sourced:

Per-assumption user comments + changes as a first-class surface (an evolution of today’s caveat notes + candidate picks).
Multiple source choices per assumption — not a single reference, but a set of candidate sources you can choose among.
Aggregate / consolidate multiple sources into one consolidated value for each relevant assumption (e.g. blend / average / select across sources), with the rationale retained.

This supersedes today’s single-reference-per-parameter shape for the parameters that warrant it. Tracked as an open item (BoA robustness, B6).

Failure & edge cases

Out-of-range value: rejected with a 422 naming the key and the allowed range (in-app edit and Excel import share the check).
Notes vs values: a note is commentary only — it never changes a value, its source, or triggers a re-solve.
Editing the DAB (Settings) never mutates existing projects — they were frozen at create; only future projects seed from it.

How to modify this safely

New parameter → register it in core/parameters/ (it flows through assumption_values by key — no DB migration). Add a references.py entry if it deserves provenance.
Keep the range-validation and the notes-never-dirty-a-solve invariants.
When the multi-source direction lands, update this page and flip its status:.

From the app’s documentation, docs/02-features/assumptions.md · Hyprisma 1.0.5