bloc.reporting.orchestrator_stone#

STONE backend for Calculation Note generation.

Functions#

collect_scenario_bundle(scenario_id, sim, metadata, ...)

Collect inputs, outputs, metadata and figures for one STONE scenario.

generate_calculation_note_stone_from_bundles(...[, ...])

Generate a Calculation Note Excel from pre-collected scenario bundles.

generate_calculation_note_stone(base_yaml[, ...])

Run STONE scenarios and generate Calculation Note Excel.

Module Contents#

bloc.reporting.orchestrator_stone.collect_scenario_bundle(scenario_id, sim, metadata, export_config, out_dir, yaml_path=None, kpi_fn=None)#

Collect inputs, outputs, metadata and figures for one STONE scenario.

Wraps _collect_scenario_stone() and returns the collected data as a (bundle, diagram_paths) tuple suitable for caching. The caller is responsible for serialising the result to disk.

Parameters:

  • scenario_id – String identifier for this scenario (used as dict key and filename prefix).

  • sim – Solved Simulation with live Cantera objects.

  • metadata – Scenario metadata dict (from the YAML metadata: block).

  • export_config – Resolved export: block from the YAML.

  • out_dir – Directory where figure files may be written.

  • yaml_path – Optional path to the source YAML (used for provenance in the bundle).

  • kpi_fn – Optional kpi_fn(sim) -> dict callable for domain-specific KPIs.

Returns:

(bundle, diagram_paths) where bundle is the scenario dict (inputs, outputs, node_data, energy_flows, etc.) and diagram_paths maps figure names to their on-disk Path objects.

Return type:

tuple[dict, dict]

bloc.reporting.orchestrator_stone.generate_calculation_note_stone_from_bundles(scenario_results, diagram_paths, out_dir, base_dir=None, calc_note_name='Calculation_Note.xlsx', title='STONE Calculation Note', subtitle='Generated by Bloc (STONE / Boulder)', all_yaml_files=None, all_header_comments=None, export_config=None)#

Generate a Calculation Note Excel from pre-collected scenario bundles.

Skips the simulation step by reusing data collected by collect_scenario_bundle() (stored in the cache entry’s artifacts/ directory). All arguments map directly to _finalize_calculation_note_excel().

Parameters:

  • scenario_results – Mapping {scenario_id: bundle_dict} as returned by collect_scenario_bundle().

  • diagram_paths – Mapping {scenario_id: {fig_name: Path}} as returned by collect_scenario_bundle().

  • out_dir – Directory where the Excel file is written.

  • base_dir – Base directory for relative path resolution (defaults to out_dir).

  • calc_note_name – Output Excel filename.

  • title – Workbook title string.

  • subtitle – Workbook subtitle string.

  • all_yaml_files – List of YAML filenames recorded in the workbook provenance tab.

  • all_header_comments – List of header comment strings from source YAML files.

  • export_config – Resolved export: block; used for variable-map resolution.

Returns:

Path to the generated Excel file, or None on failure.

Return type:

Path or None

bloc.reporting.orchestrator_stone.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.io.boulder_bridge.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.reporting.spring_kpi.compute_spring_kpis() for SPRING architectures.

Notes

The STONE export: block also accepts:

  • kpi_fn — dotted path ("module:attr") resolved via bloc.yaml_utils.resolve_dotted().

  • figures — list of keys into bloc.yaml_utils.STONE_FIGURE_GENERATORS. Each generator has signature (sim, out_dir) -> dict[str, str].

Returns:

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

Return type:

Path or None