Calculation Note — Reporting Contract#

This page describes the full contract between a STONE YAML file and the generated Excel Calculation Note. It covers every export: key, how kpi_fn and figures are resolved, what figure keys are available, and what goes into each section of the output workbook.

`export:` block reference#

All keys live under the top-level export: key of the STONE YAML.

Key	Required	Type	Description
`calc_note`	No	string	Output Excel filename. Default: `<yaml_stem>_Calculation_Note.xlsx`
`title`	No	string	Report title row in the Excel header
`subtitle`	No	string	Report subtitle row
`reactor_kind`	No	string	Reactor class name (e.g. `TubeFurnace`). Required only when disambiguation is needed (multiple registered kinds in the YAML)
`kpi_fn`	No	dotted path	Python callable for model-specific KPI extraction. Format: `"module.path:attribute"`
`conservation_rtol`	No	float	Relative tolerance of the per-node mass/energy closure gate the export enforces (default `5e-3`). Set it per model only with a comment saying why: the energy check is an HHV-vs-enthalpy consistency test, not an element balance, and a furnace outlet far below the feed temperature moves it by a fraction of a percent.
`figures`	No	list of keys	Figure generators to call. Keys must be registered in `STONE_FIGURE_GENERATORS` (see below)
`main_species`	No	int	Number of top species by mole fraction to include (default 8)
`main_species_mass`	No	int	Number of top species by mass fraction to include (default 6)
`minimum_mole_fraction_balance`	No	float (0–1)	Add species until cumulative mole fraction ≥ this value (default 0.95; set to 0 to disable)
`minimum_mass_fraction_balance`	No	float (0–1)	Same logic for mass fractions (default 0.95)
`minimum_hydrogen_balance`	No	float (0–1)	Add species in descending H-atom contribution until cumulative H ≥ this value (default 0.95)
`minimum_carbon_balance`	No	float (0–1)	Same logic for carbon atoms (default 0.95)
`mandatory_species`	No	list of strings	Species that must always appear in the composition tables

Minimal `export:` example#

export:
  calc_note: "MyProject_Calculation_Note.xlsx"
  title: "Hydrogen Production Analysis"
  kpi_fn: "bloc.reporting.spring_kpi:compute_spring_kpis"

How `kpi_fn` is resolved#

kpi_fn may be declared in the YAML or passed as a Python kwarg to generate_calculation_note_stone.

Resolution order:

The kpi_fn kwarg passed to generate_calculation_note_stone(kpi_fn=...).
export.kpi_fn in the YAML — parsed as "module.path:attribute" and imported at runtime using importlib.
If neither is set, no model-specific KPI extraction is performed and the output sheet contains only generic thermodynamic outputs (T, P, X, Y per node).

YAML format:

export:
  kpi_fn: "bloc.reporting.spring_kpi:compute_spring_kpis"

This is equivalent to:

from bloc.reporting.spring_kpi import compute_spring_kpis
generate_calculation_note_stone("my.yaml", kpi_fn=compute_spring_kpis)

Built-in KPI functions:

Function	Reactor chain
`bloc.reporting.spring_kpi:compute_spring_kpis`	Torch → PSR → PFR (SPRING)
`bloc.reactors:compute_tube_furnace_kpis`	TubeFurnace

Figure generators#

Figure generators are registered in bloc.io.scenario.STONE_FIGURE_GENERATORS. List the keys you want under export.figures:.

Key	What it produces
`network`	Graphviz network topology diagram (nodes + connections)
`tube_furnace`	Spatial temperature and species profiles for TubeFurnace
`pfr_profile`	Spatial temperature and species profiles along the PFR axis
`sankey`	Sankey mass-flow diagram

Example:

export:
  figures:
    - pfr_profile
    - network
    - sankey

If a figure key is not in STONE_FIGURE_GENERATORS, generate_calculation_note_stone raises a KeyError listing the known keys.

Figures are saved as PNG files in the output_dir and embedded in the Excel Calculation Note on a dedicated “Diagrams” sheet.

The GUI’s Cytoscape network graph (the picture under the first sheet’s header) is captured by the browser when you export from the GUI. CLI and batch exports render it headlessly instead, through the optional playwright extra (pip install bloc[gui-export] then playwright install chromium); without it the picture is simply omitted. Pass render_network_schema=False to generate_calculation_note_stone to skip it. The graphviz network figure on the scenario sheets is separate and needs the dot executable, which the bloc conda env provides.

Excel workbook structure#

The generated workbook contains the following sheets:

Sheet	Contents
Summary	One column per scenario: inputs, outputs, KPIs, and metadata
Inputs	Parameter table: symbol, value, unit, description, remark (from `# note:` YAML comments)
Outputs	KPI table: symbol, value, unit, description
Composition	Per-node species table (mole and mass fractions)
Diagrams	Embedded PNG figures (one per figure key)
(one sheet per scenario)	Detailed per-scenario tabular data when multiple scenarios are present

Generating the Calculation Note#

Single scenario#

from bloc.reporting.orchestrator_stone import generate_calculation_note_stone
path = generate_calculation_note_stone("my_stone.yaml", output_dir="Results")
print(f"Saved: {path}")

Multiple scenarios (inline sweeps / scenarios block)#

from bloc.reporting.orchestrator_stone import generate_calculation_note_stone
generate_calculation_note_stone("my_stone.yaml", output_dir="Results")

expand_scenarios is called automatically whenever the YAML declares a top-level scenarios: and/or sweep:/sweeps: block; each entry (plus the BASELINE unmodified base, added automatically by Boulder) becomes a column in the Summary sheet and its own detail sheet. include_base=False skips running the base case itself (kept only as the workbook/export template); scenario_yamls= runs additional standalone scenario files (each with its own complete from:-resolved definition, not deep-merged onto the base).

This is the same expansion the GUI’s Run Sweep action and the headless bloc some.yaml --sweep --headless CLI invocation use — see the CLI reference (“Running scenario sweeps”) for those two other entry points into the same run-set.

Passing a custom KPI function at call time#

from bloc.reporting.orchestrator_stone import generate_calculation_note_stone
from mypackage.kpis import my_kpi_fn

generate_calculation_note_stone(
    "my_stone.yaml",
    kpi_fn=my_kpi_fn,
    output_dir="Results",
)