cronian.configuration
=====================

.. py:module:: cronian.configuration


Functions
---------

.. autoapisummary::

   cronian.configuration.load_configurations
   cronian.configuration.load_general_config
   cronian.configuration.load_configurations_subfolder
   cronian.configuration.check_duplicate_ids


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

.. py:function:: load_configurations(configurations_folder: pathlib.Path) -> dict

   Load configurations and perform basic validation check for duplicate IDs.

   Args:
       configurations_folder: Path to folder containing configuration files.

   Returns:
       configurations: Nested dictionary containing the configurations defining
           generators, prosumers, and general parameters of the simulation.

   Raises:
       ValueError: If duplicate IDs exist among generator or prosumer agents.

   Example usage:

   >>> from pyprojroot import here
   ...
   >>> configurations_folder = here("tests/test_data/demo_configurations")
   >>> configurations = load_configurations(configurations_folder)
   >>> print(configurations["Generators"])
   >>> print()
   >>> print(configurations["Prosumers"])


.. py:function:: load_general_config(general_config_path: pathlib.Path) -> dict

   Load the general configuration file.

   Args:
       general_config_path: Path to the general configuration.

   Returns:
       general_config: The loaded general configuration.

   Raises:
       ValueError: If 'General' key is missing in general configuration file.


.. py:function:: load_configurations_subfolder(folder: pathlib.Path, top_level_key: str) -> dict[str, dict]

   Helper function to load YAML configuration files from a subfolder.

   Args:
       folder: Path to the folder containing configuration files.
       top_level_key: Top keys in configurations: `Generators` or `Prosumers`.

   Returns:
       agent_configurations: Dict with agent id as key and config as value.

   Raises:
       ValueError: If the top-level key is missing in any of the config files
           or if any configurations share an ID.


.. py:function:: check_duplicate_ids(ids: list[str]) -> None

   Check for duplicate ids within generator and prosumer agents.

   Args:
       ids: List of ids listed in the configuration files.

   Raises:
       ValueError: If any duplicates are detected.