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. `DesignTubeFurnace`). 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"`
`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.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.spring_kpi:compute_spring_kpis"

This is equivalent to:

from bloc.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.spring_kpi:compute_spring_kpis`	Torch → PSR → PFR (SPRING)
`bloc.reactor_models:compute_tube_furnace_kpis`	DesignTubeFurnace

Figure generators#

Figure generators are registered in bloc.yaml_utils.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 DesignTubeFurnace
`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.

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.calc_note 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.calc_note import generate_calculation_note_stone
generate_calculation_note_stone("my_stone.yaml", output_dir="Results")

expand_scenarios is called automatically; each sweeps: / scenarios: entry becomes a column in the Summary sheet.

Passing a custom KPI function at call time#

from bloc.calc_note 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",
)