annular.coupling
================

.. py:module:: annular.coupling

.. autoapi-nested-parse::

   coupling.py: core model coupling functionality using MUSCLE3.

   This file contains the creation of the coupling structure, and the MUSCLE3
   instance definitions for both the central market model and the (arbitrary)
   number of satellite models.

   The standard coupling structure is one central market model linked to many
   individual satellite models. The market model receives bid tables from the
   satellite models, and after market clearing sends back the amount of satisfied
   power and cleared market price.



Attributes
----------

.. autoapisummary::

   annular.coupling.logger


Functions
---------

.. autoapisummary::

   annular.coupling.satellite_model
   annular.coupling.central_market_model
   annular.coupling.summarize_scheduled_demand
   annular.coupling.prepare_results_folder
   annular.coupling.run


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

.. py:data:: logger

.. py:function:: satellite_model() -> None

   A simple satellite model to determine demand bids.


.. py:function:: central_market_model() -> None

   The central market model.


.. py:function:: summarize_scheduled_demand(demand_bids: pandas.DataFrame, window: Iterable[pandas.Timestamp]) -> dict[str, numpy.ndarray]

   Summarize explicitly scheduled demand per bid to amounts per timestamp.

   Bids do not have to be submitted for the entire bidding window, but
   scheduled demand does have to be reported per satellite model per timestamp.

   :param demand_bids: Bids table with a `scheduled` column to be summarized.
   :param window: Bidding window over which to summarize.

   :returns: A dictionary with satellite names as keys, and an array of scheduled
             demand as values. This array is the same length as the given window,
             with `0` value if no demand is scheduled.


.. py:function:: prepare_results_folder(config_file: pathlib.Path, results_path: pathlib.Path) -> dict

   Prepare the results folder to contain copies of the settings files to be used.

   Set up a unique folder for the model coupling run being executed.
   This folder will be the default location for any generated output by central
   or satellite models.

   :param config_file: Initial configuration file from which settings for the
                       model coupling run will be loaded.
   :param results_path: Path where a new folder for the results can be created.

   :returns: Finalized settings dictionary for the model coupling run.

   :raises RuntimeError: if the given `results_path` already contains a results
       folder for this configuration file.


.. py:function:: run(config_file: pathlib.Path, results_path: pathlib.Path = Path('results/')) -> None

   Run the coupled simulation.

   :param config_file: configuration file for the simulation to run.
   :param results_path: location where a folder can be created for output files.
                        Defaults to "results/".