plaid.containers.utils
======================

.. py:module:: plaid.containers.utils

.. autoapi-nested-parse::

   Utility functions for PLAID containers.



Functions
---------

.. autoapisummary::

   plaid.containers.utils._check_names
   plaid.containers.utils._read_index
   plaid.containers.utils._read_index_array
   plaid.containers.utils._read_index_range
   plaid.containers.utils.get_sample_ids
   plaid.containers.utils.get_number_of_samples
   plaid.containers.utils.get_feature_type_and_details_from
   plaid.containers.utils.check_features_type_homogeneity
   plaid.containers.utils.check_features_size_homogeneity
   plaid.containers.utils.has_duplicates_feature_ids


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

.. py:function:: _check_names(names: Union[str, list[str]])

   Check that names do not contain invalid character ``/``.

   :param names: The names to check.
   :type names: Union[str, list[str]]

   :raises ValueError: If any name contains the invalid character ``/``.


.. py:function:: _read_index(pyTree: list, dim: list[int])

   Read Index Array or Index Range from CGNS.

   :param pyTree: CGNS node which has a child Index to read
   :type pyTree: list
   :param dim: dimensions of the coordinates
   :type dim: list

   :returns: indices


.. py:function:: _read_index_array(pyTree: list)

   Read Index Array from CGNS.

   :param pyTree: CGNS node which has a child of type IndexArray_t to read
   :type pyTree: list

   :returns: indices


.. py:function:: _read_index_range(pyTree: list, dim: list[int])

   Read Index Range from CGNS.

   :param pyTree: CGNS node which has a child of type IndexRange_t to read
   :type pyTree: list
   :param dim: dimensions of the coordinates
   :type dim: list[str]

   :returns: indices


.. py:function:: get_sample_ids(savedir: Union[str, pathlib.Path]) -> list[int]

   Return list of sample ids in a dataset on disk.

   :param savedir: The path to the directory where sample files are stored.
   :type savedir: Union[str,Path]

   :returns: List of sample ids.
   :rtype: list[int]


.. py:function:: get_number_of_samples(savedir: Union[str, pathlib.Path]) -> int

   Return number of samples in a dataset on disk.

   :param savedir: The path to the directory where sample files are stored.
   :type savedir: Union[str,Path]

   :returns: number of samples.
   :rtype: int


.. py:function:: get_feature_type_and_details_from(feature_identifier: plaid.types.FeatureIdentifier) -> tuple[str, plaid.types.FeatureIdentifier]

   Extract and validate the feature type and its associated metadata from a feature identifier.

   This utility function ensures that the `feature_identifier` dictionary contains a valid
   "type" key (e.g., "scalar", "time_series", "field", "node") and returns the type along
   with the remaining identifier keys, which are specific to the feature type.

   :param feature_identifier: A dictionary with a "type" key, and
                              other keys (some optional) depending on the feature type. For example:
                              - {"type": "scalar", "name": "Mach"}
                              - {"type": "time_series", "name": "AOA"}
                              - {"type": "field", "name": "pressure"}
                              - {"type": "field", "name": "pressure", "time":0.}
                              - {"type": "nodes", "base_name": "Base_2_2"}
   :type feature_identifier: dict

   :returns:

             A tuple `(feature_type, feature_details)` where:
                 - `feature_type` is the value of the "type" key (e.g., "scalar").
                 - `feature_details` is a dictionary of the remaining keys.
   :rtype: tuple[str, dict]

   :raises AssertionError: - If "type" is missing.
       - If the type is not in `AUTHORIZED_FEATURE_TYPES`.
       - If any unexpected keys are present for the given type.


.. py:function:: check_features_type_homogeneity(feature_identifiers: list[plaid.types.FeatureIdentifier]) -> None

   Check type homogeneity of features, for tabular conversion.

   :param feature_identifiers: dict with a "type" key, and
                               other keys (some optional) depending on the feature type. For example:
                               - {"type": "scalar", "name": "Mach"}
                               - {"type": "time_series", "name": "AOA"}
                               - {"type": "field", "name": "pressure"}
   :type feature_identifiers: list[dict]

   :raises AssertionError: if types are not consistent


.. py:function:: check_features_size_homogeneity(feature_identifiers: list[plaid.types.FeatureIdentifier], features: dict[int, list[plaid.types.Feature]]) -> int

   Check size homogeneity of features, for tabular conversion.

   Size homogeneity is check through samples for each feature, and through features for each sample.
   To be converted to tabular data, each sample must have the same number of features and each feature
   must have the same dimension

   :param feature_identifiers: dict with a "type" key, and
                               other keys (some optional) depending on the feature type. For example:
                               - {"type": "scalar", "name": "Mach"}
                               - {"type": "time_series", "name": "AOA"}
                               - {"type": "field", "name": "pressure"}
   :type feature_identifiers: list[dict]
   :param features: dict with sample index as keys and one or more features as values.
   :type features: dict

   :returns: the common feature dimension
   :rtype: int

   :raises AssertionError: if sizes are not consistent


.. py:function:: has_duplicates_feature_ids(feature_identifiers: list[plaid.types.FeatureIdentifier])

   Check whether a list of feature identifier contains duplicates.

   :param feature_identifiers: A list of dictionaries representing feature identifiers.
   :type feature_identifiers: list[FeatureIdentifier]

   :returns: True if a duplicate is found in the list, False otherwise.
   :rtype: bool