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

Module Contents#

bloc.calc_note.generate_calculation_note(base_yaml, module, output_dir='Results', extra_yamls=None)#

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

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

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) – Imported simulation module (from bloc.batch.import_simulation()).

  • 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).

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.