463 general tutorial notebook fixes (#503)

- Fixed `04_reinforcement_learning_example.ipynb` not working
- Changes on notebook understandability
- added comment to explain end_excl variable
- corrected bug rendering Shell command falsely
- added comment about why two critics are being used
- multiple improvements on notebooks

Co-authored-by: kim-mskw <[email protected]>

assume/common/base.py

@@ -149,6 +149,7 @@ def set_dispatch_plan(
         for order in orderbook:
             start = order["start_time"]
             end = order["end_time"]
+            # end includes the end of the last product, to get the last products' start time we deduct the frequency once
             end_excl = end - self.index.freq
             if isinstance(order["accepted_volume"], dict):
                 added_volume = list(order["accepted_volume"].values())
@@ -256,6 +257,7 @@ def calculate_cashflow(self, product_type: str, orderbook: Orderbook):
         for order in orderbook:
             start = order["start_time"]
             end = order["end_time"]
+            # end includes the end of the last product, to get the last products' start time we deduct the frequency once
             end_excl = end - self.index.freq
 
             if isinstance(order["accepted_volume"], dict):

assume/strategies/flexable.py

@@ -595,6 +595,7 @@ def calculate_reward_EOM(
 
     for order in orderbook:
         start = order["start_time"]
+        # end includes the end of the last product, to get the last products' start time we deduct the frequency once
         end_excl = order["end_time"] - unit.index.freq
 
         order_times = unit.index[start:end_excl]

assume/strategies/flexable_storage.py

@@ -201,6 +201,7 @@ def calculate_reward(
 
         for order in orderbook:
             start = order["start_time"]
+            # end includes the end of the last product, to get the last products' start time we deduct the frequency once
             end_excl = order["end_time"] - unit.index.freq
 
             # Extract outputs and costs in one step

assume/strategies/learning_advanced_orders.py

@@ -255,6 +255,7 @@ def create_observation(
             The scaling factors are defined by the maximum residual load, the maximum bid price
             and the maximum capacity of the unit.
         """
+        # end includes the end of the last product, to get the last products' start time we deduct the frequency once
         end_excl = end - unit.index.freq
 
         # get the forecast length depending on the time unit considered in the modelled unit

assume/strategies/learning_strategies.py

@@ -388,6 +388,7 @@ def create_observation(
         the total capacity and marginal cost, scaled by maximum power and bid price, respectively.
         """
 
+        # end includes the end of the last product, to get the last products' start time we deduct the frequency once
         end_excl = end - unit.index.freq
 
         # get the forecast length depending on the tme unit considered in the modelled unit
@@ -521,6 +522,7 @@ def calculate_reward(
         for order in orderbook:
             start = order["start_time"]
             end = order["end_time"]
+            # end includes the end of the last product, to get the last products' start time we deduct the frequency once
             end_excl = end - unit.index.freq
 
             # depending on way the unit calculates marginal costs we take costs
@@ -992,6 +994,7 @@ def create_observation(
         the agent's action selection.
         """
 
+        # end includes the end of the last product, to get the last products' start time we deduct the frequency once
         end_excl = end - unit.index.freq
 
         # get the forecast length depending on the tme unit considered in the modelled unit

assume/units/demand.py

@@ -101,6 +101,8 @@ def calculate_min_max_power(
         Returns:
             tuple[pandas.Series, pandas.Series]: The bid colume as both the minimum and maximum power output of the unit.
         """
+
+        # end includes the end of the last product, to get the last products' start time we deduct the frequency once
         end_excl = end - self.index.freq
         bid_volume = (self.volume - self.outputs[product_type]).loc[start:end_excl]
 

assume/units/powerplant.py

@@ -260,6 +260,7 @@ def calculate_min_max_power(
         Note:
             The calculation does not include ramping constraints and can be used for arbitrary start times in the future.
         """
+        # end includes the end of the last product, to get the last products' start time we deduct the frequency once          
         end_excl = end - self.index.freq
 
         base_load = self.outputs["energy"].loc[start:end_excl]

assume/units/storage.py

@@ -300,6 +300,7 @@ def calculate_min_max_charge(
         Returns:
             tuple[np.array, np.array]: The minimum and maximum charge power levels of the storage unit in MW.
         """
+        # end includes the end of the last product, to get the last products' start time we deduct the frequency once
         end_excl = end - self.index.freq
 
         base_load = self.outputs["energy"].loc[start:end_excl]
@@ -339,6 +340,7 @@ def calculate_min_max_discharge(
         Returns:
             tuple[np.array, np.array]: The minimum and maximum discharge power levels of the storage unit in MW.
         """
+        # end includes the end of the last product, to get the last products' start time we deduct the frequency once
         end_excl = end - self.index.freq
 
         base_load = self.outputs["energy"].loc[start:end_excl]

docs/source/installation.rst

@@ -82,13 +82,13 @@ ASSUME uses `argcomplete` for argument completion on the CLI.
 
 On Windows, one needs to run:
 
-`register-python-argcomplete --shell powershell assume | Out-String | Invoke-Expression`
+    register-python-argcomplete --shell powershell assume | Out-String | Invoke-Expression
 
 in the used conda environment, to install tab completions.
 
 On Bash or zsh (Linux and Mac) run the following in the correct conda environment with assume and argcomplete installed:
 
-`eval "$(register-python-argcomplete assume)"`
+    eval "$(register-python-argcomplete assume)"
 
 
 Install using Docker

docs/source/learning.rst

@@ -98,8 +98,8 @@ The main idea is to use a centralized critic during the training phase, which ha
 Changes in state transitions and rewards can be explained by the actions of other agents.
 Meanwhile, during both training and execution, the actor has access only to its local observations :math:`o_i` derived from the entire state :math:`S`.
 
-For each agent :math:`i`, we train two centralized critics :math:`Q_{i,\theta_1,2}(S, a_1, \ldots, a_N)` together with two target critic networks.
-Similar to TD3, the smaller value of the two critics and target action noise :math:`a_i,k \sim` is used to calculate the target :math:`y_i,k`.
+For each agent :math:`i`, we train not one but two centralized critics :math:`Q_{i,\theta_1,2}(S, a_1, \ldots, a_N)` together with two target critic networks.
+Similar to TD3, the smaller value of the two critics and target action noise :math:`a_i,k \sim` is used to calculate the target :math:`y_i,k`. This is done to to address the issue of overestimation bias.
 
 .. math::
 

examples/notebooks/01_minimal_manual_example.ipynb

@@ -147,7 +147,7 @@
     "In this code:\n",
     "- `marketdesign` is a list containing a single market configuration.\n",
     "\n",
-    "- `MarketConfig(...)` defines the configuration for a specific market. In this case, it's named \"EOM\" (End of Month).\n",
+    "- `MarketConfig(...)` defines the configuration for a specific market. In this case, it's named \"EOM\" (Energy Only Market).\n",
     "\n",
     "  - `name=\"EOM\"` - Specifies the name of the market configuration as \"EOM\".\n",
     "\n",
@@ -197,7 +197,7 @@
    "source": [
     "## Adding Unit Operators and Units\n",
     "\n",
-    "After initializing the simulation, and creating a market, we add unit operators and units to the simulation world."
+    "After initializing the simulation, and creating a market, we add unit operators and units to the simulation world. A **unit** in ASSUME refers to an entity that participates in the market, either buying or selling electricity."
    ]
   },
   {

examples/notebooks/02_automated_run_example.ipynb

@@ -155,13 +155,13 @@
     "\n",
     "- `emission_factor`: A numerical value representing the amount of CO2 (or equivalent) emissions produced per unit of electricity generated.\n",
     "\n",
-    "- `max_power`: The maximum power output each unit can deliver. This is the upper limit of the unit's operational capacity.\n",
+    "- `max_power`: The maximum power output each unit can deliver. This is the upper limit of the unit's operational capacity given in MW.\n",
     "\n",
-    "- `min_power`: The minimum stable level of power that each unit can produce while remaining operational.\n",
+    "- `min_power`: The minimum stable level of power that each unit can produce while remaining operational. It is given in MW\n",
     "\n",
     "- `efficiency`: A measure of how effectively each unit converts fuel into electricity. This efficienty represent the final efficiency of converting fuel into electricity.\n",
     "\n",
-    "- `additional_cost`: The additional operational costs for each unit, such as maintenance and staffing, expressed in currency units per MWh.\n",
+    "- `additional_cost`: The additional operational costs for each unit, such as maintenance and staffing, expressed in EUR/MWh.\n",
     "\n",
     "- `unit_operator`: The entity responsible for operating each power plant unit. This could be a utility company, a private operator, or another type of organization."
    ]
@@ -253,7 +253,7 @@
     "\n",
     "You might notice, that the column name we use is demand_EOM, which is similar to the name of our demand unit. The framework is designed in such way, that multiple demand units can be defined in the same file. The column name is used to match the demand time series with the correct demand unit. Afterwards, each demand unit following a naive bidding strategy will bid the respective demand value into the market.\n",
     "\n",
-    "Also, the length of the demand time series must be at least as long as the simulation time horizon. If the time series is longer than the simulation time horizon, the framework will automatically truncate it to the correct length. If the resolution of the time series is higher than the simulation time step, the framework will automatically resample the time series to match the simulation time step. If it is shorter, an error will be raised."
+    "Also, the length of the demand time series must be at least as long as the simulation time horizon. If the time series is longer than the simulation time horizon, the framework will automatically truncate it to the correct length. This is being demonstrated by giving date ranges of eight days that will be truncated to a week. If the resolution of the time series is higher than the simulation time step, the framework will automatically resample the time series to match the simulation time step. If it is shorter, an error will be raised."
    ]
   },
   {

examples/notebooks/03_custom_unit_example.ipynb

@@ -253,6 +253,7 @@
     "        self.min_power = min_power\n",
     "        self.additional_cost = additional_cost\n",
     "\n",
+    "        # Conversion factor functions will be introduced in section 3.3\n",
     "        self.conversion_factors = self.get_conversion_factors()\n",
     "\n",
     "    # this function is a must be part of any unit class\n",
@@ -361,7 +362,7 @@
     "        else:\n",
     "            hydrogen_production = hydrogen_demand\n",
     "\n",
-    "        # get dynamic conversion factor\n",
+    "        # Conversion factor functions will be introduced in section 3.3\n",
     "        dynamic_conversion_factor = self.get_dynamic_conversion_factor(\n",
     "            hydrogen_production\n",
     "        )\n",