pyampp.io.model

Canonical pyAMPP Model I/O: Provenance-Agnostic Loader/Writer Contract

This module enforces the canonical, provenance-agnostic contract for all pyAMPP model I/O:

  1. All supported input formats (SAV, old H5, new H5) are normalized by the loader to a single canonical in-memory structure.

  2. The loader injects or upgrades all required geometry_contract and related metadata if missing or outdated.

  3. The writer serializes the in-memory structure as-is, without adding or mutating metadata.

  4. The output HDF5 is canonical and idempotent: repeated load/save cycles produce identical files, regardless of provenance.

  5. The CLI (e.g., clone_sav.py) is a thin wrapper around this process.

This guarantees that pyAMPP model data is provenance-agnostic and round-trip idempotent, and that all downstream consumers see a single, canonical data structure.

Functions

load_model(…)

Load a pyAMPP model through the canonical provenance-agnostic boundary.

save_thin_model(→ None)

Write a thin model HDF5 containing only metadata and optional observer.

export_thin_model(→ pathlib.Path)

Generate a metadata-only thin model HDF5 from any supported full model input.

load_model_metadata(→ dict[str, Any] | None)

Load canonical metadata plus optional observer from any supported model file.

save_model(→ None)

Save a model to HDF5 with geometry contract persistence.

Module Contents

pyampp.io.model.load_model(filename: pathlib.Path | str, *, strict: bool = False, keep_temp_h5: Literal[False] = False) → dict[str, Any][source]
pyampp.io.model.load_model(filename: pathlib.Path | str, *, strict: bool = False, keep_temp_h5: Literal[True]) → tuple[dict[str, Any], pathlib.Path | None]

Load a pyAMPP model through the canonical provenance-agnostic boundary.

pyampp.io.model.save_thin_model(thin_model: dict[str, Any], h5_path: pathlib.Path | str) → None[source]

Write a thin model HDF5 containing only metadata and optional observer.

Required input:

  • thin_model[“metadata”][“geometry_contract”] present as either GeometryContract or a dict-like contract payload.

Optional input:

  • thin_model[“observer”]

pyampp.io.model.export_thin_model(source_model: pathlib.Path | str, output_h5: pathlib.Path | str | None = None, *, strict: bool = False) → pathlib.Path[source]

Generate a metadata-only thin model HDF5 from any supported full model input.

The output file contains only:

  • metadata (full metadata section)

  • observer (if present)

Parameters:

  • source_model – Path to source full model (.h5 or .sav)

  • output_h5 – Destination path. If omitted, writes sibling <source_stem>_metadata.h5 next to source.

  • strict – Passed to load_model for contract completion.

Returns:

Path to written thin HDF5 file.

pyampp.io.model.load_model_metadata(model_path: pathlib.Path | str, *, strict: bool = False) → dict[str, Any] | None[source]

Load canonical metadata plus optional observer from any supported model file.

Returns None when the restored model has no metadata dictionary or when the completed metadata still lacks a geometry contract.

pyampp.io.model.save_model(model_dict: dict[str, Any], h5_path: pathlib.Path | str) → None[source]

Save a model to HDF5 with geometry contract persistence.

If the model has a completed geometry_contract in metadata, this function persists it to HDF5 so it will be reused on next load without recomputation.

Parameters:

  • model_dict – Model dictionary to save

  • h5_path – Path to write HDF5 file