add additional clearing and strategy docs (#283)

* add additional clearing and strategy docs
* update copyright year
* use version from pyproject.toml in docs version
* fix usage of python typings for docs
* Attributes are called Parameters for better docs

README.md

@@ -183,6 +183,6 @@ ASSUME is funded by the Federal Ministry for Economic Affairs and Climate Action
 
 ## License
 
-Copyright 2022-2023 [ASSUME developers](https://assume.readthedocs.io/en/latest/developers.html).
+Copyright 2022-2024 [ASSUME developers](https://assume.readthedocs.io/en/latest/developers.html).
 
 ASSUME is licensed under the [GNU Affero General Public License v3.0](./LICENSES/AGPL-3.0-or-later.txt). This license is a strong copyleft license that requires that any derivative work be licensed under the same terms as the original work. It is approved by the [Open Source Initiative](https://opensource.org/licenses/AGPL-3.0).

assume/common/base.py

@@ -4,7 +4,7 @@
 
 from collections import defaultdict
 from datetime import datetime, timedelta
-from typing import Dict, List, Tuple, TypedDict, Union
+from typing import TypedDict, Union
 
 import pandas as pd
 
@@ -20,7 +20,7 @@ class BaseUnit:
     """
     A base class for a unit. This class is used as a foundation for all units.
 
-    Attributes:
+    Parameters:
         id (str): The ID of the unit.
         unit_operator (str): The operator of the unit.
         technology (str): The technology of the unit.
@@ -79,14 +79,14 @@ def __init__(
     def calculate_bids(
         self,
         market_config: MarketConfig,
-        product_tuples: List[Tuple],
+        product_tuples: list[tuple],
     ) -> Orderbook:
         """
         Calculates the bids for the next time step.
 
         Args:
             market_config (MarketConfig): The market configuration.
-            product_tuples (List[Tuple]): The product tuples.
+            product_tuples (list[tuple]): The product tuples.
 
         Returns:
             Orderbook: The bids.
@@ -173,8 +173,8 @@ def calculate_generation_cost(
         Calculates the generation cost for a specific product type within the given time range.
 
         Args:
-            start (datetime): The start time for the calculation.
-            end (datetime): The end time for the calculation.
+            start (datetime.datetime): The start time for the calculation.
+            end (datetime.datetime): The end time for the calculation.
             product_type (str): The type of product for which the generation cost is to be calculated.
 
         """
@@ -225,7 +225,7 @@ def get_output_before(self, dt: datetime, product_type: str = "energy") -> float
         else:
             return self.outputs[product_type].at[dt - self.index.freq]
 
-    def as_dict(self) -> Dict[str, Union[str, int]]:
+    def as_dict(self) -> dict[str, Union[str, int]]:
         """
         Returns a dictionary representation of the unit.
 
@@ -301,7 +301,7 @@ class SupportsMinMax(BaseUnit):
     Base class used for units supporting continuous dispatch and without energy storage.
     This class is best to be used as foundation for classes of power plants and similar units.
 
-    Attributes:
+    Parameters:
         min_power (float): The minimum power output of the unit.
         max_power (float): The maximum power output of the unit.
         ramp_down (float): How much power can be decreased in one time step.
@@ -406,7 +406,7 @@ def get_operation_time(self, start: datetime) -> int:
         Returns the time the unit is operating (positive) or shut down (negative).
 
         Args:
-            start (datetime): The start time.
+            start (datetime.datetime): The start time.
 
         Returns:
             int: The operation time.
@@ -433,7 +433,7 @@ def get_average_operation_times(self, start: datetime) -> tuple[float, float]:
         Calculates the average uninterrupted operation and down time.
 
         Args:
-            start (datetime): The current time.
+            start (datetime.datetime): The current time.
 
         Returns:
             tuple[float, float]: Tuple of the average operation time avg_op_time and average down time avg_down_time.
@@ -511,7 +511,7 @@ class SupportsMinMaxCharge(BaseUnit):
     """
     Base Class used for units with energy storage.
 
-    Attributes:
+    Parameters:
         initial_soc (float): The initial state of charge of the storage.
         min_power_charge (float): How much power must be charged at least in one time step.
         max_power_charge (float): How much power can be charged at most in one time step.
@@ -544,7 +544,7 @@ class SupportsMinMaxCharge(BaseUnit):
 
     def calculate_min_max_charge(
         self, start: pd.Timestamp, end: pd.Timestamp, product_type="energy"
-    ) -> Tuple[pd.Series, pd.Series]:
+    ) -> tuple[pd.Series, pd.Series]:
         """
         Calculates the min and max charging power for the given time period.
 
@@ -554,7 +554,7 @@ def calculate_min_max_charge(
             product_type (str, optional): The product type of the unit. Defaults to "energy".
 
         Returns:
-            Tuple[pd.Series, pd.Series]: The min and max charging power for the given time period.
+            tuple[pd.Series, pd.Series]: The min and max charging power for the given time period.
         """
         pass
 
@@ -581,7 +581,7 @@ def get_soc_before(self, dt: datetime) -> float:
         The SoC is a float between 0 and 1.
 
         Args:
-            dt (datetime): The current datetime.
+            dt (datetime.datetime): The current datetime.
 
         Returns:
             float: The SoC before the given datetime.
@@ -708,7 +708,7 @@ def calculate_bids(
         self,
         unit: BaseUnit,
         market_config: MarketConfig,
-        product_tuples: List[Product],
+        product_tuples: list[Product],
         **kwargs,
     ) -> Orderbook:
         """
@@ -717,7 +717,7 @@ def calculate_bids(
         Args:
             unit (BaseUnit): The unit.
             market_config (MarketConfig): The market configuration.
-            product_tuples (List[Product]): The product tuples.
+            product_tuples (list[Product]): The product tuples.
 
         Returns:
             Orderbook: The bids.
@@ -744,7 +744,7 @@ class LearningStrategy(BaseStrategy):
     """
     A strategy which provides learning functionality, has a method to calculate the reward.
 
-    Attributes:
+    Parameters:
         obs_dim (int): The observation dimension.
         act_dim (int): The action dimension.
 
@@ -769,7 +769,7 @@ class LearningConfig(TypedDict):
     """
     A class for the learning configuration.
 
-    Attributes:
+    Parameters:
         observation_dimension (int): The observation dimension.
         action_dimension (int): The action dimension.
         continue_learning (bool): Whether to continue learning.

assume/common/forecasts.py

@@ -15,7 +15,7 @@ class Forecaster:
     to retrieve forecasts for specific columns, availability of units, and prices of fuel types, returning
     the corresponding timeseries as pandas Series.
 
-    Attributes:
+    Parameters:
         index (pd.Series): The index of the forecasts.
 
     Args:
@@ -90,7 +90,7 @@ class CsvForecaster(Forecaster):
     It initializes with the provided index. It includes methods to retrieve forecasts for specific columns,
     availability of units, and prices of fuel types, returning the corresponding timeseries as pandas Series.
 
-    Attributes:
+    Parameters:
         index (pd.Series): The index of the forecasts.
         powerplants (dict[str, pd.Series]): The power plants.
 
@@ -365,7 +365,7 @@ class RandomForecaster(CsvForecaster):
     from the `CsvForecaster` class and initializes with the provided index, power plants, and
     standard deviation of the noise.
 
-    Attributes:
+    Parameters:
         index (pd.Series): The index of the forecasts.
         powerplants (dict[str, pd.Series]): The power plants.
         sigma (float): The standard deviation of the noise.
@@ -425,7 +425,7 @@ class NaiveForecast(Forecaster):
     provided index. If the optional parameters are lists, they are converted to pandas Series with
     the provided index and the corresponding values.
 
-    Attributes:
+    Parameters:
         index (pd.Series): The index of the forecasts.
         availability (float | list, optional): The availability of the power plants.
         fuel_price (float | list, optional): The fuel price.

assume/common/market_objects.py

@@ -30,8 +30,8 @@ class Order(TypedDict):
 
     Args:
         bid_id (str): the id of the bid
-        start_time (datetime): the start time of the order
-        end_time (datetime): the end time of the order
+        start_time (datetime.datetime): the start time of the order
+        end_time (datetime.datetime): the end time of the order
         volume (Number | dict[datetime, Number]): the volume of the order (positive if generation)
         accepted_volume (Number | dict[datetime, Number]): the accepted volume of the order
         price (Number): the price of the order
@@ -82,8 +82,8 @@ class Product(NamedTuple):
     An actual product with start and end.
 
     Args:
-        start (datetime): the start time of the product
-        end (datetime): the end time of the product
+        start (datetime.datetime): the start time of the product
+        end (datetime.datetime): the end time of the product
         only_hours (OnlyHours | None): tuple of hours from which this order is available, on multi day products
     """
 
@@ -230,8 +230,8 @@ class DataRequestMessage(TypedDict):
         context (str): the context of the message
         market_id (str): the id of the market
         metric (str): the specific metric being requested
-        start_time (datetime): the start time of the data request
-        end_time (datetime): the end time of the data request
+        start_time (datetime.datetime): the start time of the data request
+        end_time (datetime.datetime): the end time of the data request
     """
 
     context: str

assume/common/outputs.py

@@ -28,8 +28,8 @@ class WriteOutput(Role):
 
     Args:
         simulation_id (str): The ID of the simulation as a unique classifier.
-        start (datetime): The start datetime of the simulation run.
-        end (datetime): The end datetime of the simulation run.
+        start (datetime.datetime): The start datetime of the simulation run.
+        end (datetime.datetime): The end datetime of the simulation run.
         db_engine: The database engine. Defaults to None.
         export_csv_path (str, optional): The path for exporting CSV files, no path results in not writing the csv. Defaults to "".
         save_frequency_hours (int): The frequency in hours for storing data in the db and/or csv files. Defaults to None.

assume/common/units_operator.py

@@ -34,7 +34,7 @@ class UnitsOperator(Role):
     The UnitsOperator is the agent that manages the units.
     It receives the opening hours of the market and sends back the bids for the market.
 
-    Attributes:
+    Parameters:
         available_markets (list[MarketConfig]): The available markets.
         registered_markets (dict[str, MarketConfig]): The registered markets.
         last_sent_dispatch (int): The last sent dispatch.

assume/markets/base_market.py

@@ -36,7 +36,7 @@ class MarketMechanism:
     The MarketMechanism is embedded into the general MarketRole, which takes care of simulation concerns.
     In the Marketmechanism, all data needed for the clearing is present.
 
-    Attributes:
+    Parameters:
         all_orders (Orderbook): The list of all orders.
         marketconfig (MarketConfig): The configuration of the market.
         open_auctions (list[dict]): The list of open auctions.
@@ -154,7 +154,7 @@ class MarketRole(MarketMechanism, Role):
     This is the base class for all market roles. It implements the basic functionality of a market role, such as
     registering agents, clearing the market and sending the results to the database agent.
 
-    Attributes:
+    Parameters:
         longitude (float): The longitude of the market.
         latitude (float): The latitude of the market.
         marketconfig (MarketConfig): The configuration of the market.

assume/markets/clearing_algorithms/complex_clearing.py

@@ -2,7 +2,6 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-import cProfile
 import logging
 from datetime import timedelta
 from operator import itemgetter
@@ -201,7 +200,7 @@ class ComplexClearingRole(MarketRole):
 
     The complex market is a pay-as-clear market with more complex bid structures, including minimum acceptance ratios, bid types, and profiled volumes.
 
-    Attributes:
+    Parameters:
         marketconfig (MarketConfig): The market configuration.
 
     Args:

assume/reinforcement_learning/learning_role.py

@@ -26,8 +26,8 @@ class Learning(Role):
     the provided learning configuration.
 
     Args:
-        simulation_start (datetime): The start of the simulation.
-        simulation_end (datetime): The end of the simulation.
+        simulation_start (datetime.datetime): The start of the simulation.
+        simulation_end (datetime.datetime): The end of the simulation.
         learning_config (LearningConfig): The configuration for the learning process.
 
     """

assume/scenario/loader_amiris.py

@@ -3,17 +3,14 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 import logging
-from datetime import datetime, timedelta
+from datetime import timedelta
 
 import dateutil.rrule as rr
-import numpy as np
 import pandas as pd
 import yaml
-from tqdm import tqdm
 from yamlinclude import YamlIncludeConstructor
 
-from assume.common.base import LearningConfig
-from assume.common.forecasts import CsvForecaster, Forecaster, NaiveForecast
+from assume.common.forecasts import NaiveForecast
 from assume.common.market_objects import MarketConfig, MarketProduct
 from assume.world import World
 

assume/scenario/loader_csv.py

@@ -141,8 +141,8 @@ def make_market_config(
     Args:
     id (str): The id of the market.
     market_params (dict): The market parameters.
-    world_start (datetime): The start time of the world.
-    world_end (datetime): The end time of the world.
+    world_start (datetime.datetime): The start time of the world.
+    world_end (datetime.datetime): The end time of the world.
 
     Returns:
     MarketConfig: The market config.

assume/scenario/oeds/infrastructure.py

@@ -14,7 +14,7 @@
 from sqlalchemy import create_engine
 from tqdm import tqdm
 
-# !pip install git+https://github.com/maurerle/windpowerlib@maurerle
+# !pip install git+https://github.com/wind-python/windpowerlib@dev
 from windpowerlib import ModelChain, WindTurbine
 
 from assume.scenario.oeds.static import (

assume/strategies/advanced_orders.py

@@ -2,8 +2,6 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-from datetime import datetime, timedelta
-
 import pandas as pd
 
 from assume.common.base import BaseStrategy, SupportsMinMax
@@ -19,7 +17,7 @@ class flexableEOMBlock(BaseStrategy):
     """
     A strategy that bids on the EOM-market with block bids.
 
-    Attributes:
+    Parameters:
         foresight (pd.Timedelta): The foresight for the EOM-market.
 
     Args:

assume/strategies/dmas_powerplant.py

@@ -439,7 +439,7 @@ def optimize_result(
         power_prices: np.array,
     ) -> np.array:
         """
-        calculates the result with prices *2
+        calculates the result with prices times 2
         to optimize according to the result in the best way possible
 
         :param unit: unit to optimize

assume/strategies/extended.py

@@ -92,7 +92,7 @@ def calculate_bids(
         Args:
             unit (SupportsMinMax): Unit to dispatch.
             market_config (MarketConfig): Market configuration.
-            product_tuples (List[Product]): List of products to dispatch.
+            product_tuples (list[Product]): List of products to dispatch.
             **kwargs (dict): Additional arguments.
 
         Returns: