porereax.utils
==============

.. py:module:: porereax.utils

.. autoapi-nested-parse::

   Module providing utility functions for the PoreReax package.

   This module includes functions for saving and loading Python objects using
   pickle, loading YAML configuration files, and common mathematical operations
   such as the minimum-image convention.



Functions
---------

.. autoapisummary::

   porereax.utils.save_object
   porereax.utils.load_object
   porereax.utils.load_yaml
   porereax.utils.min_image_convention
   porereax.utils.min_image_midpoint
   porereax.utils.get_identifiers
   porereax.utils.get_data
   porereax.utils.read_pore_yml


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

.. py:function:: save_object(obj, filename)

   Save a Python object to a file using pickle.

   :param obj: The Python object to be saved.
   :type obj: any
   :param filename: The path to the file where the object will be saved.
   :type filename: str


.. py:function:: load_object(file_path)

   Load a Python object from a file using pickle.

   :param file_path: The path to the file from which the object will be loaded.
   :type file_path: str

   :returns: The loaded Python object.
   :rtype: any


.. py:function:: load_yaml(file_path: str) -> dict

   Load a YAML file and return its contents as a dictionary.

   :param file_path: The path to the YAML file.
   :type file_path: str

   :returns: The contents of the YAML file as a dictionary.
   :rtype: dict


.. py:function:: min_image_convention(vec: numpy.ndarray, box: numpy.ndarray) -> numpy.ndarray

   Apply the minimal image convention to a vector given the simulation box dimensions.

   :param vec: The input vector (shape: (N, 3)).
   :type vec: np.ndarray
   :param box: The simulation box dimensions (shape: (3,)).
   :type box: np.ndarray

   :returns: The vector adjusted by the minimal image convention (shape: (N, 3)).
   :rtype: np.ndarray


.. py:function:: min_image_midpoint(vec1: numpy.ndarray, vec2: numpy.ndarray, box: numpy.ndarray) -> numpy.ndarray

   Calculate the midpoint between two vectors considering the minimal image convention.

   :param vec1: The first vector (shape: (N, 3)).
   :type vec1: np.ndarray
   :param vec2: The second vector (shape: (N, 3)).
   :type vec2: np.ndarray
   :param box: The simulation box dimensions (shape: (3,)).
   :type box: np.ndarray

   :returns: The midpoint vector adjusted by the minimal image convention (shape: (N, 3)).
   :rtype: np.ndarray


.. py:function:: get_identifiers(link_data: str) -> list

   Retrieve the list of identifiers from a data file.

   :param link_data: Path to the data file created by a sampler instance.
   :type link_data: str

   :returns: List of identifiers present in the data file.
   :rtype: list


.. py:function:: get_data(link_data: str, identifier: str) -> dict

   Retrieve the data for a specific identifier from a data file.

   :param link_data: Path to the data file created by a sampler instance.
   :type link_data: str
   :param identifier: The identifier for which to retrieve the data.
   :type identifier: str

   :returns: The data corresponding to the specified identifier.
   :rtype: dict


.. py:function:: read_pore_yml(file_path: str) -> dict

   Read a YAML file containing pore system properties and extract relevant depending on the pore shape.

   :param file_path: Path to the YAML file containing pore system properties.
   :type file_path: str

   :returns: A dictionary containing the extracted pore properties.
   :rtype: dict