bloc.yaml_utils#

YAML utilities for Bloc: comment-aware parsing and deep merge.

Uses ruamel.yaml to preserve and extract inline comments from YAML files. Comment convention: # [<unit>] <description> [| <remark>]

Example YAML:

initial:
  G_PW_IN: 111  # [kW] Generator power IN
  G_ETA: 0.80   # [-] Generator efficiency

Attributes#

`INPUT_VARIABLE_MAP`
`OUTPUT_VARIABLE_MAP`
`INPUT_CATEGORIES`
`NESTED_INPUT_MAP`
`OUTPUT_CATEGORIES`
`ENERGY_THERMAL_INLET_KEYS`
`ENERGY_THERMAL_OUTLET_KEYS`
`ELEMENT_BALANCE_DEFAULT_H`
`ELEMENT_BALANCE_DEFAULT_C`

Functions#

`load_yaml_raw`(path)	Load a YAML file preserving comments (ruamel.yaml round-trip mode).
`extract_comment_metadata`(data[, section])	Extract inline comment metadata from a YAML section.
`extract_header_comments`(path)	Extract leading comments from a YAML file (before the first key).
`get_bloc_version_info`()	Get Bloc version and git commit hash.
`deep_merge`(base, overlay)	Deep-merge overlay into base. Overlay values win.
`load_yaml_with_inheritance`(path)	Load YAML config with optional `from:` inheritance.
`load_scenario`(base_path[, overlay_path])	Load a scenario by deep-merging an optional overlay onto a base YAML.

Module Contents#

bloc.yaml_utils.load_yaml_raw(path)#

Load a YAML file preserving comments (ruamel.yaml round-trip mode).

Parameters:: path (str or Path) – Path to the YAML file.
Returns:: The parsed YAML data with comments preserved.
Return type:: CommentedMap

bloc.yaml_utils.extract_comment_metadata(data, section='initial')#

Extract inline comment metadata from a YAML section.

Parses comments following the convention # [unit] description [| remark].

Parameters:

data (CommentedMap) – Parsed YAML data (from load_yaml_raw()).
section (str) – The top-level section to extract from (default "initial").

Returns:

{key: {"value": ..., "unit": str, "description": str, "remark": str}}

Return type:

dict

bloc.yaml_utils.extract_header_comments(path)#

Extract leading comments from a YAML file (before the first key).

These are typically the file description, update log, etc.

Parameters:: path (str or Path) – Path to the YAML file.
Returns:: Each line of header comments (with # prefix stripped).
Return type:: list of str

bloc.yaml_utils.get_bloc_version_info()#

Get Bloc version and git commit hash.

Returns:: {"version": str, "commit": str}
Return type:: dict

bloc.yaml_utils.deep_merge(base, overlay)#

Deep-merge overlay into base. Overlay values win.

Parameters:

base (dict) – The base dictionary.
overlay (dict) – The overlay dictionary (overrides take precedence).

Returns:

A new dictionary with the merged result.

Return type:

dict

bloc.yaml_utils.load_yaml_with_inheritance(path)#

Load YAML config with optional from: inheritance.

If a top-level from key is present, that file is loaded first (recursively) and deep-merged with the current file content (excluding from). Relative from paths are resolved against the current file directory.

bloc.yaml_utils.load_scenario(base_path, overlay_path=None)#

Load a scenario by deep-merging an optional overlay onto a base YAML.

If the overlay has a top-level from key, it must match the base filename (e.g. from: SPRING_A3_BG_20260212.yaml when base is that file); otherwise a ValueError is raised. The from key is not merged into the result (metadata only).

Parameters:

base_path (str or Path) – Path to the base YAML file.
overlay_path (str or Path or None) – Path to the overlay YAML file. If None, only the base is returned.

Returns:

The merged configuration dictionary (plain dict, no comments).

Return type:

dict

bloc.yaml_utils.INPUT_VARIABLE_MAP: dict[str, tuple[str, str, str]]#

bloc.yaml_utils.OUTPUT_VARIABLE_MAP: dict[str, tuple[str, str, str]]#

bloc.yaml_utils.INPUT_CATEGORIES: dict[str, list[str]]#

bloc.yaml_utils.NESTED_INPUT_MAP: dict[str, dict[str, tuple[str, str, str]]]#

bloc.yaml_utils.OUTPUT_CATEGORIES: dict[str, list[str]]#

bloc.yaml_utils.ENERGY_THERMAL_INLET_KEYS: list[str] = ['G_PW_IN (kW)', 'HHV_torch_input (kW)', 'HHV_2nd_inj_input (kW)']#

bloc.yaml_utils.ENERGY_THERMAL_OUTLET_KEYS: list[str] = ['Heat_residual (kW)', 'HHV_pre_quench (kW)', 'Heat_losses_reactor (kW)', 'Torch_generator_losses (kW)']#

bloc.yaml_utils.ELEMENT_BALANCE_DEFAULT_H: float = 0.95#

bloc.yaml_utils.ELEMENT_BALANCE_DEFAULT_C: float = 0.95#