mmgp.utils
==========

.. py:module:: mmgp.utils


Attributes
----------

.. autoapisummary::

   mmgp.utils.expected_structure


Functions
---------

.. autoapisummary::

   mmgp.utils.load_backend
   mmgp.utils.validate_configs
   mmgp.utils.read_configuration
   mmgp.utils.read_problem
   mmgp.utils.reset_folder
   mmgp.utils.remove_file
   mmgp.utils.print_setting


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

.. py:data:: expected_structure

   This dictionary defines the expected structure of a YAML configuration file.
   It specifies the keys that should be present in the configuration file and their
   expected data types.

.. py:function:: load_backend(backend_module: str)

.. py:function:: validate_configs(configs: dict, v_structure: dict, depth_accumulator: str = '')

   Recursively validate the structure and data types of a configuration dictionary.

   This function checks whether a given dictionary `configs` conforms to the
   expected structure and data types defined in the `v_structure` dictionary.

   :param configs: The configuration dictionary to be validated.
   :type configs: dict
   :param v_structure: The expected structure.
   :type v_structure: dict
   :param depth_accumulator: The path from the root of the concerned.
   :type depth_accumulator: str

   :returns:

             True if the `configs` dictionary matches the expected structure
                   and data types; False otherwise.
   :rtype: bool


.. py:function:: read_configuration(config_file: str) -> dict[str, str]

   Read and process the YAML configuration file specified during class initialization.
   It then defines the configuration details inside the class.

   :param config_file: The path to the YAML configuration file.
   :type config_file: str

   :returns: A dictionary containing configuration information.
   :rtype: dict[str,str]

   .. rubric:: Example

   .. code-block:: python

       configuration = read_configuration('config.yaml')

   .. attention::

      - Ensure that the configuration file exists at the specified path.
      - The method assumes that the configuration file is in YAML format.


.. py:function:: read_problem(configuration: dict) -> plaid.problem_definition.ProblemDefinition

   Read and process problem definition data from a directory.

   :param configuration: A dictionary containing configuration information.
   :type configuration: dict

   :returns: An instance of the `ProblemDefinition` class representing the problem.
   :rtype: ProblemDefinition

   .. note:: The fields: "init_dataset_location", "zone_name" and "base_name" of the configuration file will be used to get and set the 'problem definition'.

   .. attention:: Ensure that the initial dataset and problem definition files exist at the specified path.


.. py:function:: reset_folder(path: str) -> None

   Reset or create a folder by deleting its contents.

   :param path: The path to the folder to be reset or created.
   :type path: str

   .. attention:: Use this function with caution, as it permanently deletes the contents of the specified folder.


.. py:function:: remove_file(path: str) -> None

   Remove a file if it exists.

   :param path: The path to the file to be removed.
   :type path: str

   .. attention:: Use this function with caution, as it permanently deletes the contents of the specified folder.


.. py:function:: print_setting(configuration: dict, problem: plaid.problem_definition.ProblemDefinition) -> None

   Return a string representation of the settings in a readable format (pretty print).