plaid.storage.common.bridge
===========================

.. py:module:: plaid.storage.common.bridge

.. autoapi-nested-parse::

   Common bridge utilities.

   This module provides bridge functions for converting between PLAID samples and
   storage formats, including flattening/unflattening and sample reconstruction.



Functions
---------

.. autoapisummary::

   plaid.storage.common.bridge.unflatten_path
   plaid.storage.common.bridge.flatten_path
   plaid.storage.common.bridge.to_sample_dict
   plaid.storage.common.bridge.flat_dict_to_sample_dict
   plaid.storage.common.bridge.to_plaid_sample
   plaid.storage.common.bridge.plaid_to_sample_dict


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

.. py:function:: unflatten_path(key: str) -> str

   Unflattens a Zarr key by replacing underscores with slashes.

   :param key: The flattened key with underscores.
   :type key: str

   :returns: The unflattened key with slashes.
   :rtype: str


.. py:function:: flatten_path(key: str) -> str

   Flattens a path key by replacing slashes with underscores.

   :param key: The path key to flatten.
   :type key: str

   :returns: The flattened key with slashes replaced by underscores.
   :rtype: str


.. py:function:: to_sample_dict(var_sample_dict: dict[str, Any], flat_cst: dict[str, Any], cgns_types: dict[str, str], features: Optional[list[str]] = None) -> dict[float, dict[str, Any]]

   Convert variable sample dict to time-based sample dict.

   :param var_sample_dict: Variable features dictionary.
   :param flat_cst: Constant features dictionary.
   :param cgns_types: CGNS types dictionary.
   :param features: Optional list of features to include.

   :returns: Time-based sample dictionary.
   :rtype: dict


.. py:function:: flat_dict_to_sample_dict(flat_dict: dict[str, Any], cgns_types: dict[str, str], features: Optional[list[str]] = None) -> dict[float, dict[str, Any]]

   Convert a flattened sample dict into a time-indexed flat-tree mapping.

   This function processes a single flattened sample dictionary where keys
   are feature paths or feature path suffixed with '_times' (holding time
   interval specs). It splits values and their corresponding time
   specifications, slices feature arrays per interval and groups features
   by their sample time into CGNS-style flattened trees.

   :param flat_dict: Mapping of flattened feature paths to values or to time
                     specifications (keys ending with '_times'). Time specifications
                     must be sequences or arrays reshapeable to (-1, 3) rows of
                     (time, start, end).
   :param cgns_types: Mapping from feature path to CGNS node type; used to
                      determine which None-valued features should be preserved.
   :param features: Optional list of feature paths to include; if None all
                    features are included.

   :returns: A dict mapping time (float) to a flattened tree dict (path -> array or None).


.. py:function:: to_plaid_sample(sample_dict: dict[float, dict[str, Any]], cgns_types: dict[str, str]) -> plaid.containers.sample.Sample

   Convert sample dict to PLAID Sample.

   :param sample_dict: Time-based sample dictionary.
   :param cgns_types: CGNS types dictionary.

   :returns: The reconstructed PLAID Sample.
   :rtype: Sample


.. py:function:: plaid_to_sample_dict(sample: plaid.containers.sample.Sample, variable_features: list[str], constant_features: list[str]) -> dict[str, Any]

   Convert PLAID Sample to sample dict.

   :param sample: The PLAID Sample.
   :param variable_features: List of variable feature names.
   :param constant_features: List of constant feature names.

   :returns: sample_dict
   :rtype: dict[str, Any]