pymgrid.modules.BatteryModule

class pymgrid.modules.BatteryModule(min_capacity, max_capacity, max_charge, max_discharge, efficiency, battery_cost_cycle=0.0, battery_transition_model=None, init_charge=None, init_soc=None, initial_step=0, normalized_action_bounds=(0, 1), raise_errors=False)

A battery module.

Battery modules are fixed: when calling Microgrid.run, you must pass a control for batteries.

Parameters

min_capacityfloat

Minimum energy that must be contained in the battery.

max_capacityfloat

Maximum energy that can be contained in the battery. If soc=1, capacity is at this maximum.

max_chargefloat

Maximum amount the battery can be charged in one step.

Warning

This amount is the maximum the battery can be charged internally, dependent on the battery_transition_model. The amount the battery can be charged externally (e.g. the amount of energy the battery can absorb) is defined as the negative of min_act.

max_dischargefloat

Maximum amount the battery can be discharged in one step.

Warning

This amount is the maximum the battery can be discharged internally, dependent on the battery_transition_model. The amount the battery can be discharged externally (e.g. the amount of energy the battery can provide) is defined as max_act.

efficiencyfloat

Efficiency of the battery. See BatteryModule.model_transition() for details.

battery_cost_cyclefloat, default 0.0

Marginal cost of charging and discharging.

battery_transition_modelcallable or None, default None

Function to model the battery’s transition. If None, BatteryTransitionModel is used.

Note

If you define a battery_transition_model, it must be YAML-serializable if you plan to serialize your battery module or any microgrid containing your battery.

For example, you can define it as a class with a __call__ method and yaml.YAMLObject as its metaclass. See the PyYAML documentation for details and BatteryTransitionModel for an example.

init_chargefloat or None, default None

Initial charge of the battery. 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.

init_socfloat or None, default None

Initial state of charge of the battery. 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_boundstuple 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_errorsbool, default False

Whether to raise errors if bounds are exceeded in an action. If False, actions are clipped to the limit possible.

Methods

as_sink(energy_excess)	Act as an energy sink to the microgrid.
as_source(energy_demand)	Act as an energy source to the microgrid.
dump([stream])	Save a module to a YAML buffer.
dynamic_action_space()	An action space bounded by the current step's maximum consumption and production.
from_normalized(value[, act, obs])	Un-normalize an action or observation.
get_cost(energy_change)	Get the cost of charging or discharging.
load(stream)	Load a module from yaml representation.
log_dict()	Module's log as a dict.
log_frame()	Module's log as a DataFrame.
model_transition(energy)	Convert an external energy request to a change in internal energy.
reset()	Reset the module to step zero and flush the log.
sample_action([strict_bound])	Sample an action from the module's action space.
state_dict([normalized])	Current state of the module as a dictionary.
step(action[, normalized])	Take one step in the module, attempting to draw or send action amount of energy.
to_normalized(value[, act, obs])	Normalize an action or observation.
transition_kwargs()	Values passed to transition models.
update(external_energy_change[, as_source, ...])	Update the state of the module given an energy request.
verbose_eq(other[, indent])

Attributes

absorption_marginal_cost	Expected marginal cost of energy absorption.
action_space	Action spaces of the module.
battery_transition_model
current_charge	Battery charge.
current_step	Current step of the module.
is_sink	Whether the module is a sink.
is_source	Whether the module is a source.
log	Module's log as a DataFrame.
logger	The module's logger.
logger_last	The most recent entry in the log.
marginal_cost	Average marginal cost of producing with the module.
max_act	Maximum action that the module allows.
max_consumption	Maximum amount of consumption at the current time step.
max_external_charge	Maximum amount of energy the battery can absorb when charging.
max_external_discharge	Maximum amount of energy the battery can provide when discharging.
max_obs	Maximum observation that the module gives.
max_production	Maximum amount of production at the current time step.
min_act	Minimum action that the module allows.
min_obs	Minimum observation that the module gives.
min_production	Minimum amount of production at the current time step.
module_type	Type of the module.
observation_space	Observation space of the module.
production_marginal_cost	Expected marginal cost of energy production.
soc	Battery state of charge.
state	Current state of the module as a vector.
yaml_tag	Tag used for yaml serialization.