diff --git a/docs/source/index.rst b/docs/source/index.rst index 7ae99bf2..9ef87bff 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/reference/modules/battery_transition_models/index.rst b/docs/source/reference/modules/battery_transition_models/index.rst new file mode 100644 index 00000000..f2837501 --- /dev/null +++ b/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 + diff --git a/docs/source/reference/modules/index.rst b/docs/source/reference/modules/index.rst index 23cb5f8d..26c75602 100644 --- a/docs/source/reference/modules/index.rst +++ b/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 \ No newline at end of file + 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 diff --git a/src/pymgrid/forecast/forecaster.py b/src/pymgrid/forecast/forecaster.py index bb90f5f9..c6192cf8 100644 --- a/src/pymgrid/forecast/forecaster.py +++ b/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, diff --git a/src/pymgrid/modules/base/base_module.py b/src/pymgrid/modules/base/base_module.py index 132c3160..e673d17d 100644 --- a/src/pymgrid/modules/base/base_module.py +++ b/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 diff --git a/src/pymgrid/modules/base/timeseries/base_timeseries_module.py b/src/pymgrid/modules/base/timeseries/base_timeseries_module.py index 3f8b6803..2bfbd907 100644 --- a/src/pymgrid/modules/base/timeseries/base_timeseries_module.py +++ b/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 ------- diff --git a/src/pymgrid/modules/battery/battery_module.py b/src/pymgrid/modules/battery/battery_module.py index 918e3999..d2480226 100644 --- a/src/pymgrid/modules/battery/battery_module.py +++ b/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. diff --git a/src/pymgrid/modules/genset_module.py b/src/pymgrid/modules/genset_module.py index f356428c..d0cb992e 100644 --- a/src/pymgrid/modules/genset_module.py +++ b/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. diff --git a/src/pymgrid/modules/grid_module.py b/src/pymgrid/modules/grid_module.py index 89864ad1..4bc0ccaa 100644 --- a/src/pymgrid/modules/grid_module.py +++ b/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. diff --git a/src/pymgrid/modules/load_module.py b/src/pymgrid/modules/load_module.py index 29486b95..8a7387bc 100644 --- a/src/pymgrid/modules/load_module.py +++ b/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. diff --git a/src/pymgrid/modules/renewable_module.py b/src/pymgrid/modules/renewable_module.py index 7710cfec..12388bf3 100644 --- a/src/pymgrid/modules/renewable_module.py +++ b/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.