annular.market.tulipa.utils
===========================

.. py:module:: annular.market.tulipa.utils


Attributes
----------

.. autoapisummary::

   annular.market.tulipa.utils.logger


Functions
---------

.. autoapisummary::

   annular.market.tulipa.utils.strip_timezone
   annular.market.tulipa.utils.create_tulipa_input_data
   annular.market.tulipa.utils.write_inputs_to_db
   annular.market.tulipa.utils.read_outputs_from_db
   annular.market.tulipa.utils.convert_data_for_tulipa


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

.. py:data:: logger

.. py:function:: strip_timezone(timestamp: pandas.Series | pandas.DatetimeIndex | list) -> pandas.Series | pandas.DatetimeIndex

   Convert an input to pd.Series or pd.Index and strip timezone.

   :param timestamp: The input to process.


.. py:function:: create_tulipa_input_data(generator_configs: dict[str, dict], timeseries_data: pandas.DataFrame, db_file: str | None = None, csv_folder: str | pathlib.Path | None = None) -> None

   Creates the Tulipa input from the given arguments.

   Populates a `duckdb` database with the input files for Tulipa.
   This creates one producer asset per generator in `generator_configs` plus one consumer asset named `bid_manager`.

   The profiles for the generators is stored in the `timeseries_data`.

   :param generator_configs: dict of configurations defining of all generators.
   :param timeseries_data: DataFrame containing all timeseries_data for generators.
   :param db_file: A path to duckdb database. By default, an in-memory database is used
                   and not persisted, in which case `csv_folder` should be specified.
   :param csv_folder: If given, all tables are saved as csv files in this location.

   .. rubric:: Notes

   The intended use of this function is to transform supply-side input data
   for an annular model to a Tulipa model. The `bid_manager` asset is created
   because we attach bids later to an (arbitrary) existing consumer asset,
   but the supply-side data do not have any demand assets.


.. py:function:: write_inputs_to_db(connection: duckdb.DuckDBPyConnection, bids: pandas.DataFrame, timeseries_data: pandas.DataFrame, window_df: pandas.DataFrame) -> None

   Write input data to DuckDB tables.

   :param connection: Open DuckDB connection.
   :param bids: DataFrame with bids.
   :param timeseries_data: DataFrame with timestamp and timestep columns.
   :param window_df: DataFrame with timestamp and timestep columns for the window.


.. py:function:: read_outputs_from_db(connection: duckdb.DuckDBPyConnection, snapshots: pandas.DatetimeIndex, bid_idx_cols: list[str], bids: pandas.DataFrame) -> tuple[pandas.DataFrame, pandas.DataFrame]

   Read output data from DuckDB tables.

   :param connection: Open DuckDB connection
   :param snapshots: DatetimeIndex to filter market_price rows (the bidding window)
   :param bid_idx_cols: Column names to use for setting the index
   :param bids: Dataframe with with submitted bids.

   :returns: Tuple of (market_price, scheduled_bids) DataFrames.
             scheduled_bids timestamps are localized back to UTC.


.. py:function:: convert_data_for_tulipa(bids: pandas.DataFrame, timeseries_data: pandas.DataFrame, snapshots: pandas.DatetimeIndex, bidding_window: pandas.DatetimeIndex) -> tuple[pandas.DataFrame, pandas.DataFrame, pandas.DatetimeIndex, pandas.DataFrame]

   Convert data so that Tulipa can use them.

   In particular
   - Strip timezone from inputs to prepare for database storage
   - Reset all indexes
   - Create 1-based time index that is used in Tulipa
   - Denote `sense` column with strings "demand" and "supply" instead of numerics

   To avoid mutation, input dataframes are copied.

   :param bids: MultiIndex DataFrame with a 'timestamp' level.
   :param timeseries_data: DataFrame with DatetimeIndex.
   :param snapshots: Optimization window as a DatetimeIndex of timesteps.
   :param bidding_window: timestamps for bidding window.

   :returns: Tuple of (bids, timeseries_data, snapshots, and window_df).
             window_df is a correspondence between pd.Datetime timestamps in Annular and
             integer timesteps in Tulipa, subset to the optimization window.