pyampp.io.model
===============

.. py:module:: pyampp.io.model

.. autoapi-nested-parse::

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

.. autoapisummary::

   pyampp.io.model.load_model
   pyampp.io.model.save_thin_model
   pyampp.io.model.export_thin_model
   pyampp.io.model.load_model_metadata
   pyampp.io.model.save_model


Module Contents
---------------

.. py:function:: load_model(filename: pathlib.Path | str, *, strict: bool = False, keep_temp_h5: Literal[False] = False) -> dict[str, Any]
                 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.


.. py:function:: save_thin_model(thin_model: dict[str, Any], h5_path: pathlib.Path | str) -> None

   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"]


.. py:function:: export_thin_model(source_model: pathlib.Path | str, output_h5: pathlib.Path | str | None = None, *, strict: bool = False) -> pathlib.Path

   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)

   :param source_model: Path to source full model (.h5 or .sav)
   :param output_h5: Destination path. If omitted, writes sibling
                     ``<source_stem>_metadata.h5`` next to source.
   :param strict: Passed to ``load_model`` for contract completion.

   :returns: Path to written thin HDF5 file.


.. py:function:: load_model_metadata(model_path: pathlib.Path | str, *, strict: bool = False) -> dict[str, Any] | None

   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.


.. py:function:: save_model(model_dict: dict[str, Any], h5_path: pathlib.Path | str) -> None

   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.

   :param model_dict: Model dictionary to save
   :param h5_path: Path to write HDF5 file