docs updates

docs/source/index.rst

@@ -1,25 +1,26 @@
-.. pymgrid documentation master file, created by
+.. python-microgrid documentation master file, created by
    sphinx-quickstart on Sat Nov 19 12:49:18 2022.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
 *********************
-pymgrid documentation
+python-microgrid documentation
 *********************
 
 **Version**: |version|
 
 **Maintainer**: Avishai Halev
 
-*pymgrid* is a Python library to simulate tertiary control of electrical microgrids. *pymgrid* allows
+*python-microgrid* is a Python library to simulate tertiary control of electrical microgrids.
+It is an extension of TotalEnergies' [pymgrid](https://github.com/Total-RD/pymgrid). *python-microgrid* allows
 users to create and customize microgrids of their choosing. These microgrids can then be controlled using a user-defined
-algorithm or one of the control algorithms contained in *pymgrid*: rule-based control and model predictive control.
+algorithm or one of the control algorithms contained in *python-microgrid*: rule-based control and model predictive control.
 
 Environments corresponding to the OpenAI-Gym API are also provided, with both continuous and discrete action space
 environments available. These environments can be used with your choice of reinforcement learning algorithm to train
 a control algorithm.
 
-*pymgrid* attempts to offer the simplest and most intuitive API possible, allowing the user to
+*python-microgrid* attempts to offer the simplest and most intuitive API possible, allowing the user to
 focus on their particular application.
 
 See the :doc:`getting_started` section for further information, including instructions on how to

docs/source/reference/modules/battery_transition_models/index.rst

@@ -0,0 +1,16 @@
+.. _api.battery_transition_models:
+
+Battery Transition Models
+=========================
+
+.. currentmodule:: pymgrid.modules.battery.transition_models
+
+Various battery transition models.
+
+.. autosummary::
+    :toctree: ../../api/battery_transition_models/
+
+    BatteryTransitionModel
+    BiasedTransitionModel
+    DecayTransitionModel
+

docs/source/reference/modules/index.rst

@@ -41,4 +41,22 @@ A module that cleans up after all the other modules are deployed.
 .. autosummary::
     :toctree: ../api/modules/
 
-    UnbalancedEnergyModule
+    UnbalancedEnergyModule
+
+
+Module Functions
+================
+
+Battery Transition Models
+-------------------------
+
+Various battery transition models.
+
+.. currentmodule:: pymgrid.modules.battery.transition_models
+
+.. autosummary::
+    :toctree: ../api/battery_transition_models/
+
+    BatteryTransitionModel
+    BiasedTransitionModel
+    DecayTransitionModel

src/pymgrid/forecast/forecaster.py

@@ -218,6 +218,22 @@ def _forecast(self, val_c, val_c_n, n):
 
 
 class GaussianNoiseForecaster(Forecaster):
+    """
+    Forecaster that adds Gaussian noise to true future values.
+    """
+    increase_uncertainty: bool
+    """
+    Whether uncertainty should increase for points farther in the future.
+
+    If True, uncertainty increases logarithmically in the number of steps ahead.
+    """
+    relative_noise: bool
+    """
+    Whether the Gaussian noise should be relative to the scale of the time series.
+
+    If True, the noise_std will be computed as `input_noise_std * time_series.mean()`.
+    If False, the noise_std will be equal to `input_noise_std`.
+    """
     def __init__(self,
                  noise_std,
                  observation_space,

src/pymgrid/modules/base/base_module.py

@@ -683,10 +683,38 @@ def marginal_cost(self):
 
     @property
     def production_marginal_cost(self):
+        """
+        Expected marginal cost of energy production.
+
+        Cost of producing one unit of energy.
+
+        .. warning::
+            This is a scalar value, and thus will be inaccurate for modules that do not have scalar costs.
+            It is thus only an expectation.
+
+        Returns
+        -------
+        production_marginal_cost : float
+
+        """
         return 0.0
 
     @property
     def absorption_marginal_cost(self):
+        """
+        Expected marginal cost of energy absorption.
+
+        Cost of absorbing one unit of energy.
+
+        .. warning::
+            This is a scalar value, and thus will be inaccurate for modules that do not have scalar costs.
+            It is thus only an expectation.
+
+        Returns
+        -------
+        absorption_marginal_cost : float
+
+        """
         return 0.0
 
     @property

src/pymgrid/modules/base/timeseries/base_timeseries_module.py

@@ -277,15 +277,15 @@ def forecast_horizon(self, value):
     @property
     def forecaster_increase_uncertainty(self):
         """
-        View of :class:`pymgrid.forecast.GaussianNoiseForecaster``.increase_uncertainty`.
+        View of :attr:`.GaussianNoiseForecaster.increase_uncertainty`.
 
         Required for serialization as a mirror to the class parameter.
-        Will only ever be True if ``self.forecaster`` is a ``GaussianNoiseForecaster``.
+        Will only ever be True if :attr:`.forecaster` is a :class:`.GaussianNoiseForecaster`.
 
         Returns
         -------
         forecaster_increase_uncertainty : bool
-            Associated attribute of ``self.forecaster``.
+            Associated attribute of `:attr:`.forecaster`.
 
         """
         try:
@@ -296,10 +296,10 @@ def forecaster_increase_uncertainty(self):
     @property
     def forecaster_relative_noise(self):
         """
-        View of :class:`pymgrid.forecast.GaussianNoiseForecaster``.forecaster_relative_noise`.
+        View of :attr:`.GaussianNoiseForecaster.relative_noise`.
 
         Required for serialization as a mirror to the class parameter.
-        Will only ever be True if ``self.forecaster`` is a ``GaussianNoiseForecaster``.
+        Will only ever be True if ``self.forecaster`` is a :class:`.GaussianNoiseForecaster`.
 
         Returns
         -------

src/pymgrid/modules/battery/battery_module.py

@@ -67,6 +67,10 @@ class BatteryModule(BaseMicrogridModule):
         One of ``init_charge`` or ``init_soc`` must be passed, else an exception is raised.
         If both are passed, ``init_soc`` is ignored and ``init_charge`` is used.
 
+    normalized_action_bounds : tuple of int or float, default (0, 1).
+        Bounds of normalized actions.
+        Change to (-1, 1) for e.g. an RL policy with a Tanh output activation.
+
     raise_errors : bool, default False
         Whether to raise errors if bounds are exceeded in an action.
         If False, actions are clipped to the limit possible.

src/pymgrid/modules/genset_module.py

@@ -43,6 +43,10 @@ class GensetModule(BaseMicrogridModule):
     init_start_up : bool, default True
         Whether the genset is running upon reset.
 
+    normalized_action_bounds : tuple of int or float, default (0, 1).
+        Bounds of normalized actions.
+        Change to (-1, 1) for e.g. an RL policy with a Tanh output activation.
+
     raise_errors : bool, default False
         Whether to raise errors if bounds are exceeded in an action.
         If False, actions are clipped to the limit possible.

src/pymgrid/modules/grid_module.py

@@ -56,6 +56,10 @@ class GridModule(BaseTimeSeriesMicrogridModule):
     cost_per_unit_co2 : float, default 0.0
         Marginal cost of grid co2 production.
 
+    normalized_action_bounds : tuple of int or float, default (0, 1).
+        Bounds of normalized actions.
+        Change to (-1, 1) for e.g. an RL policy with a Tanh output activation.
+
     raise_errors : bool, default False
         Whether to raise errors if bounds are exceeded in an action.
         If False, actions are clipped to the limit possible.

src/pymgrid/modules/load_module.py

@@ -41,7 +41,11 @@ class LoadModule(BaseTimeSeriesMicrogridModule):
         Number of steps in the future to forecast. If forecaster is None, ignored and 0 is returned.
 
     forecaster_increase_uncertainty : bool, default False
-        Whether to increase uncertainty for farther-out dates if using a GaussianNoiseForecaster. Ignored otherwise..
+        Whether to increase uncertainty for farther-out dates if using a GaussianNoiseForecaster. Ignored otherwise.
+
+    normalized_action_bounds : tuple of int or float, default (0, 1).
+        Bounds of normalized actions.
+        Change to (-1, 1) for e.g. an RL policy with a Tanh output activation.
 
     raise_errors : bool, default False
         Whether to raise errors if bounds are exceeded in an action.

src/pymgrid/modules/renewable_module.py

@@ -46,6 +46,10 @@ class RenewableModule(BaseTimeSeriesMicrogridModule):
     provided_energy_name: str, default "renewable_used"
         Name of the energy provided by this module, to be used in logging.
 
+    normalized_action_bounds : tuple of int or float, default (0, 1).
+        Bounds of normalized actions.
+        Change to (-1, 1) for e.g. an RL policy with a Tanh output activation.
+
     raise_errors : bool, default False
         Whether to raise errors if bounds are exceeded in an action.
         If False, actions are clipped to the limit possible.