bloc.boulder_plugins.calc_note_bundle#

Versioned JSON bundle for caching STONE Calculation Note scenario data.

A calc_note_bundle.json file captures all data produced by collect_scenario_bundle() for the base scenario so that generate_calculation_note_stone_from_bundles() can build the Excel workbook without re-running the simulation.

Bundle schema#

bundle_version is written to every file. Bump BUNDLE_VERSION whenever the schema changes to force cache invalidation on old entries.

Top-level keys:

  • bundle_version ΓÇö integer schema version

  • scenario_id ΓÇö string

  • bundle ΓÇö the scenario dict from collect_scenario_bundle()

  • diagram_paths ΓÇö dict {fig_name: relative_path_str}

  • workbook_meta ΓÇö title, subtitle, yaml files, header comments

Serialization helpers re-use the scalar encoder from bloc.testing.non_regression to handle numpy scalars, Path objects, etc.

ct.SolutionArray time-series (the states dict populated by _stone_states_from_sim()) are not JSON-native. They are encoded as a tagged dict via collect_data() and rebuilt on load via restore_data(), using the mechanism file path the live phase was constructed from to reconstruct an equivalent ct.Solution phase.

That mechanism path is not read from SolutionArray.source directly: Boulder/bloc reactors routinely clone or re-wrap the ct.Solution used to build a stage’s states (e.g. type(self)(gas, clone=False) in torch_mixing.py, the PFR carrier-reactor machinery in march_engine.py), and Cantera reports source == "<unknown>" on such derived phases. Callers of write_bundle() must therefore pass mechanism_hint — the authoritative mechanism path known independently (e.g. converter.gas.source, captured once right after the shared gas was built from a real file) — which is used whenever a given array’s own .source is missing or "<unknown>".

Attributes#

BUNDLE_VERSION

Functions#

write_bundle(artifacts_dir, scenario_id, bundle, ...)

Write a calc_note_bundle.json and copy figure files to artifacts_dir.

load_bundle(artifacts_dir)

Load a calc_note_bundle.json from artifacts_dir.

Module Contents#

bloc.boulder_plugins.calc_note_bundle.BUNDLE_VERSION: int = 2#
bloc.boulder_plugins.calc_note_bundle.write_bundle(artifacts_dir, scenario_id, bundle, scenario_diagrams, workbook_meta=None, figure_bytes=None, mechanism_hint=None)#

Write a calc_note_bundle.json and copy figure files to artifacts_dir.

Parameters:

  • artifacts_dir – Directory created by Boulder’s cache machinery.

  • scenario_id – Identifier for this scenario.

  • bundle – The dict returned by collect_scenario_bundle().

  • scenario_diagrams – Mapping from figure name to file path.

  • workbook_meta – Optional dict with keys title, subtitle, all_yaml_files, all_header_comments, calc_note_name, export_config.

  • figure_bytes – When the figure files exist as in-memory bytes rather than disk paths, pass them here as {fig_name: bytes}. Takes precedence over scenario_diagrams paths.

  • mechanism_hint – Authoritative mechanism file path (e.g. converter.gas.source) used to encode any ct.SolutionArray nested in bundle whose own .source has degraded to "<unknown>" (see module docstring).

bloc.boulder_plugins.calc_note_bundle.load_bundle(artifacts_dir)#

Load a calc_note_bundle.json from artifacts_dir.

Returns:

Keys: scenario_id, bundle, diagram_paths (with paths remapped to absolute Path objects), workbook_meta, bundle_version. Returns None when the file is missing, corrupt, or has an incompatible bundle_version.

Return type:

dict or None