bloc.calc_note#

Automated Calculation Note generation from YAML export configuration.

This module provides generate_calculation_note(), which reads the export section of a base YAML file to determine which scenarios to run and then produces an Excel Calculation Note with side-by-side scenario columns, embedded diagrams, and structured metadata.

Typical usage from a run script:

from bloc.calc_note import generate_calculation_note
generate_calculation_note(base_yaml=yml_file, module=module)

Functions#

generate_calculation_note(base_yaml[, module, ...])

Run scenarios and generate an automated Calculation Note (Excel).

generate_calculation_note_stone(base_yaml[, ...])

Run STONE scenarios and generate Calculation Note Excel.

Module Contents#

bloc.calc_note.generate_calculation_note(base_yaml, module=None, output_dir='Results', extra_yamls=None, *, backend='ctwrap', kpi_fn=None, validate_strict=False)#

Run scenarios and generate an automated Calculation Note (Excel).

This is the unified entry point for Bloc’s Calculation Note generation. Two backends are supported:

  • backend="stone" (recommended) — YAML-only path using bloc.simulation_builder.build_simulation_from_yaml(); no Python module needed. Accepts kpi_fn and validate_strict and forwards them to generate_calculation_note_stone().

  • backend="ctwrap" (deprecated) — legacy path that drives a ctwrap simulation module. Requires the module argument. Emits a DeprecationWarning. Port to STONE using docs/migration_guide.md and switch to backend="stone".

The function reads the export section of base_yaml to configure the report. Recognised keys inside export:

  • calc_note – output Excel filename (default: <stem>_Calculation_Note.xlsx)

  • title – report title row

  • subtitle – report subtitle row

  • main_species – number of top species by mole fraction (default 8, gas-phase only)

  • main_species_mass – number of top species by mass fraction (default 6, gas-phase only)

  • minimum_mole_fraction_balance – include species until cumulative mole fraction >= this (0–1, default 0.95); use 0 to disable

  • minimum_mass_fraction_balance – include species until cumulative mass fraction >= this (0–1, default 0.95); use 0 to disable

  • mandatory_species – species that must always appear

  • minimum_hydrogen_balance – target H balance threshold (0–1, default 0.95); species are added in descending order of H-atom contribution until the cumulative sum accounts for at least this fraction of total inlet H

  • minimum_carbon_balance – target C balance threshold (0–1, default 0.95); same logic as minimum_hydrogen_balance but for carbon atoms

  • reactor_kind – selects the variable-map set; supported values: "TubeFurnace" (TF maps from bloc.yaml_utils); omit or leave blank for the default SPRING maps.

Minimal export section example:

export:
  calc_note: "MyProject_Calculation_Note.xlsx"
  title: "Hydrogen Production Analysis"
  subtitle: "Baseline vs. Optimized Configuration"
Parameters:

  • base_yaml (str or Path) – Absolute or relative path to the base YAML configuration file.

  • module (module, optional) – Imported simulation module (from bloc.batch.import_simulation()). Required when backend="ctwrap"; ignored when backend="stone".

  • output_dir (str) – Sub-directory (relative to base_yaml’s parent) for output files.

  • extra_yamls (str, list[str], or None) – YAML files to use as overlay scenarios. Can be: - A glob pattern (e.g., "SPRING_A3_BG_20260212_gen*.yaml") - A list of file paths or glob patterns - None (default): only the base scenario is run (no overlay scenarios).

  • backend ({"stone", "ctwrap"}) – Which simulation backend to use (see above). Prefer "stone"; "ctwrap" is deprecated and will be removed in a future release.

  • kpi_fn (callable, optional) – STONE-only; forwarded to generate_calculation_note_stone().

  • validate_strict (bool) – STONE-only; forwarded to generate_calculation_note_stone().

Returns:

Path to the generated Excel file, or None if no export section was found in the YAML.

Return type:

Path or None

Raises:

None – If no export section is present in the YAML, the function returns None without raising an error.

bloc.calc_note.generate_calculation_note_stone(base_yaml, output_dir='Results', extra_yamls=None, scenario_yamls=None, include_base=True, validate_strict=False, kpi_fn=None)#

Run STONE scenarios and generate Calculation Note Excel.

Uses bloc.simulation_builder.build_simulation_from_yaml() for each scenario (base + overlays). Validates YAML with validate_yaml_file() (no strict unit check for STONE). Writes the same Excel format as generate_calculation_note().

Parameters:

  • base_yaml (str or Path) – Path to the base STONE YAML (e.g. SPRING_A3_BG_20260212_stone.yaml).

  • output_dir (str) – Output directory relative to the YAML parent.

  • extra_yamls (str or list[str] or None) – Glob pattern(s) for overlay STONE YAMLs (e.g. “_stone.yaml”). Deprecated — prefer declaring variations inline in the base YAML via scenarios: or sweeps: (see bloc.yaml_utils.expand_scenarios()). Combining inline scenarios with extra_yamls is rejected.

  • scenario_yamls (str or list[str] or None) – Standalone scenario YAML files/patterns to run and aggregate into the same workbook. Supports files using from: master.yaml inheritance. Unlike extra_yamls, these files are not deep-merged onto base_yaml; each is treated as a complete scenario definition.

  • include_base (bool) – If True, run the base YAML as a scenario in addition to inline/standalone scenarios. If False, base is used only as workbook/export template.

  • validate_strict (bool) – If True, raise on any YAML validation issue.

  • kpi_fn (callable or None) – Optional kpi_fn(sim) -> dict that computes domain-specific KPIs from each solved Simulation. Its output is merged into the outputs column of the Calculation Note. Equivalent to setting export.kpi_fn: "module:attr" in the YAML; specifying both is ambiguous and raises ValueError. Use bloc.spring_kpi.compute_spring_kpis() for SPRING architectures.

Notes

The STONE export: block also accepts:

Returns:

Path to the generated Excel file, or None if base YAML has no metadata.

Return type:

Path or None