annular.coupling_components
===========================

.. py:module:: annular.coupling_components

.. autoapi-nested-parse::

   coupling_components.py: Utilities for coupling using MUSCLE3.



Attributes
----------

.. autoapisummary::

   annular.coupling_components.logger


Functions
---------

.. autoapisummary::

   annular.coupling_components.compact_market_info_to_msg
   annular.coupling_components.extract_market_info_from_msg
   annular.coupling_components.compact_bids_to_msg
   annular.coupling_components.extract_bids_from_msg
   annular.coupling_components.get_coupling_setup


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

.. py:data:: logger

.. py:function:: compact_market_info_to_msg(price: numpy.ndarray | None, scheduled_demand: numpy.ndarray | None, timestamp: float) -> libmuscle.Message

   Compact market information to a message.

   :param price: A numpy array with market prices.
   :param scheduled_demand: A numpy array with the demand scheduled for a satellite.
   :param timestamp: Floating point value to serve as timestamp for model coordination.

   :returns: A muscle3 message where the data attribute is a dictionary with keys
             "price" and "scheduled_demand".


.. py:function:: extract_market_info_from_msg(msg: libmuscle.Message) -> tuple[numpy.ndarray | None, numpy.ndarray | None, float]

   Extract the market information message.

   :param msg: muscle3 Message containing a dictionary with keys "price" and
               "scheduled_demand" for a single satellite.

   :returns: the market price, scheduled demand as numpy arrays, and the timestamp.
   :rtype: tuple


.. py:function:: compact_bids_to_msg(demand_bids: pandas.DataFrame, timestamp: float) -> libmuscle.Message

   Compact a DataFrame of (block) bids columns into a MUSCLE3 Message.

   This takes bids in the following format:

   +--------------------+------------------+-----------+----------+-------+
   | exclusive_group_id | profile_block_id | timestamp | quantity | price |
   +--------------------+------------------+-----------+----------+-------+
   | ...                | ...              | ...       | ...      | ...   |
   +--------------------+------------------+-----------+----------+-------+

   where:

   - `exclusive_group_id`: ID of which exclusive group this bid belongs to
   - `profile_block_id`: ID of which profile block this bid belongs to
   - `timestamp`: timestamp for this bid
   - `quantity`: quantity for this bid
   - `price`: price for this bid

   and (exclusive_group_id, profile_block_id, timestamp) are its Index.

   Every bid must have a `profile_block_id` and `exclusive_group_id`. If a bid
   does not make use of profile block or exclusive group functionality, the
   `exclusive_group_id` must be unique, while `profile_block_id` can be any value.

   The resulting message contains the dataframe converted to a dictionary where

       - column and index names become dictionary keys
       - column and index values become dictionary values.

   :param demand_bids: Dataframe table of the bids from a satellite model.
   :param timestamp: Floating point value to serve as timestamp for model coordination.

   :returns: MUSCLE3 message object containing the bids table information in a
             dictionary.


.. py:function:: extract_bids_from_msg(msg: libmuscle.Message) -> pandas.DataFrame

   Reconstruct a DataFrame of (block) bids from a MUSCLE3 Message.

   The `.data` attribute of the incoming message should be a dictionary
   with the following keys: price, quantity, exclusive_group_id, profile_block_id,
   timestamp.

   From this data, a DataFrame in the following format is created:

   +--------------------+------------------+-----------+----------+-------+
   | exclusive_group_id | profile_block_id | timestamp | quantity | price |
   +--------------------+------------------+-----------+----------+-------+
   | ...                | ...              | ...       | ...      | ...   |
   +--------------------+------------------+-----------+----------+-------+

   where:

   - `exclusive_group_id`: ID of which exclusive group this bid belongs to
   - `profile_block_id`: ID of which profile block this bid belongs to
   - `timestamp`: timestamp for this bid
   - `quantity`: quantity for this bid
   - `price`: price for this bid

   and (exclusive_group_id, profile_block_id, timestamp) are its Index.

   Every bid must have a `profile_block_id` and `exclusive_group_id`. If a bid
   does not make use of profile block or exclusive group functionality, the
   `exclusive_group_id` must be unique, while `profile_block_id` can be any value.

   :param msg: MUSCLE3 message object containing the bids table information as
               a dictionary.

   :returns: Dataframe table of the bids from a satellite model.


.. py:function:: get_coupling_setup(config_name: str, number_of_satellites: int) -> ymmsl.Model

   Create the MUSCLE3 coupling configuration for the energy system network.

   :param config_name: name of this run to be used as model name
   :param number_of_satellites: number of satellites to spin up

   :returns: MUSCLE3 Model object with the standard coupling configuration