bloc.reporting.orchestrator#

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.reporting.orchestrator 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).

Module Contents#

bloc.reporting.orchestrator.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.io.boulder_bridge.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.