smartgrid.observation.global_observation.GlobalObservation¶

class smartgrid.observation.global_observation.GlobalObservation(hour: float, available_energy: float, equity: float, energy_loss: float, autonomy: float, exclusion: float, well_being: float, over_consumption: float)[source]¶

Bases: BaseObservation

Global observations of the World, shared by all Agents in the smart grid.

Observations cannot be modified once created, to limit potential bugs. Global observations are not directly linked to a particular agent, but rather to the whole society of agents in the World, i.e., in this smart grid. Thus, the measures are the same for all agents.

To optimize computations, we thus create global observations only once each step. This is done through the last_step_compute and computed class attributes. We emphasize that they should not be accessed through an instance, as they are not relevant as observations, merely to compute observations.

A global observation contains the following measures:

hour: The current hour in the simulated world. It is computed as a ratio between 0 and 1, and days are ignored by using a modulo. Specifically, assuming that the current time step is t, the hour measure is computed as (t % 24) / 24.
available_energy: The quantity of energy available in the grid, which is accessible to all agents. This is a large pool of energy, however they should avoid over-consuming it, and take an appropriate quantity so as to let other agents profit as well. This measure is normalized as a value between 0 and 1, from the real available quantity, w.r.t. the bounds of energy that could have been generated at this step. See the energy_generator module for more details on energy generators, and their bounds.
equity: The equity of comforts between all agents in the grid, i.e., to which degree do they have a similar comfort. It is computed as a statistical indicator of dispersion named the Hoover index, which is a well-known tool in economy, originally made to describe income inequality. equity is computed as 1 - hoover(comforts), such that 0 represents a perfect inequality (one person has everything, the others nothing), and 1 a perfect equality (everybody has the same comfort).
energy_loss: The quantity of energy that was available to agents, but not used (i.e., neither consumed nor stored) at this time step.
autonomy: This measure represents the autonomy, or self-sustainability, of the smart grid. It is measured based on the transactions (i.e., selling or buying energy from and to the national grid), w.r.t. the total amount of energy exchanged within the grid (given, stored, consumed).
exclusion: The proportion of agents that have a comfort lower than half the median of agents’ comforts. Such agents are said to be excluded.
well_being: The median of all agents’ comfort. Using a median rather than an average reduces the impact of outliers.
over_consumption: The quantity of energy that agents have consumed, but was not originally available in the grid. We assume that the grid automatically bought this missing energy from the national grid. It is computed as the sum of energy consumed from the grid and stored from the grid, by all agents, minus the sum of energy given by all agents, and the energy initially available, divided by the sum of energy taken by all agents, to obtain a ratio between 0 and 1. If the measure is less than 0, we set it to 0.

__init__(hour: float, available_energy: float, equity: float, energy_loss: float, autonomy: float, exclusion: float, well_being: float, over_consumption: float) → None¶

Methods

`__init__`(hour, available_energy, equity, ...)
`asdict`()	Return the Observation as a dictionary.
`compute`(world)	Return the global observations computed from the World state.
`fields`()	Returns the names of fields that compose an Observation.
`reset`()	Reset the counter of steps computed, i.e., the memoization.
`space`(world, agent)	Describe the space in which Observations take their values.

Attributes

`computed`	Memoized global observations, computed at the time step indicated by `last_step_compute`.
`last_step_compute`	Last time step at which global observations were computed.
`hour`	The current hour, represented in `[0,1]`.
`available_energy`	The ratio of available energy in the Grid, compared to the maximum possible.
`equity`	The equity, a statistical measure of dispersion, between agents' comforts.
`energy_loss`	The ratio of energy not consumed over the total energy exchanges.
`autonomy`	The ratio of exchanges that are not with the national grid, over the total exchanges.
`exclusion`	The proportion of agents with a comfort less than half the median.
`well_being`	The median of agents' comforts.
`over_consumption`	The ratio of energy consumed that was not available, over the total exchanges.

classmethod _is_compute(world: World) → bool[source]¶: Private method to know whether the current step has already been computed.

asdict() → Dict[str, Any]¶

Return the Observation as a dictionary.

Fields can be excluded by setting the metadata include custom property to False, such as: my_field: Any = field(metadata={'include': False}).

Parameters:: self – An instance of observation.
Returns:: The observation represented as a dictionary, with the fields’ names as keys and the fields’ values as values, in the order of definition.

autonomy: float¶: The ratio of exchanges that are not with the national grid, over the total exchanges.

available_energy: float¶: The ratio of available energy in the Grid, compared to the maximum possible.

classmethod compute(world: World) → Self[source]¶

Return the global observations computed from the World state.

This method uses memoization through computed, _is_compute() and last_step_compute to avoid re-computing already known observations. In such cases, the cached instance is returned. Otherwise, measures are computed, and a new instance is created, memoized, and returned.

Parameters:: world (smartgrid.world.World) – The World for which we want to compute the global observations.
Return type:: GlobalObservation

computed: ClassVar[Self | None] = None¶: Memoized global observations, computed at the time step indicated by last_step_compute.

energy_loss: float¶: The ratio of energy not consumed over the total energy exchanges.

equity: float¶: The equity, a statistical measure of dispersion, between agents’ comforts.

exclusion: float¶: The proportion of agents with a comfort less than half the median.

classmethod fields() → Tuple[str]¶

Returns the names of fields that compose an Observation.

Fields can be excluded by setting the metadata include custom property to False, such as: my_field: Any = field(metadata={'include': False}).

Parameters:: cls – Either the class itself, or an instance of the class; this method supports both. In other words, it can be used as Observation.fields(), or obs = Observation(...); obs.fields().
Returns:: The fields’ names as a tuple, in their order of definition.

hour: float¶: The current hour, represented in [0,1].

last_step_compute: ClassVar[int] = -1¶

Last time step at which global observations were computed.

This is used to optimize the computations and avoid re-computing already known observations, since these are the same for all agents at a given time step.

over_consumption: float¶: The ratio of energy consumed that was not available, over the total exchanges.

classmethod reset()[source]¶: Reset the counter of steps computed, i.e., the memoization.

classmethod space(world: World, agent: Agent) → Space¶

Describe the space in which Observations take their values.

This method is useful if an algorithm has assumptions or requirements on the observation space. For example, values can be interpolated, by knowing their original domain.

We currently use ratios in [0, 1] for each metric of observations. This makes it easier for learning algorithms (avoids perceiving a given dimension as more important than another because of an extended range). It also means that the world and agent parameters do not influe on the space (they could be None).

In the future, we could use the true ranges from the agent’s AgentProfile and let users convert these observations to [0, 1] when necessary. This would provide more useful information, e.g., the actual battery storage in [0, capacity], rather than a ratio, or the actual hour in [0, 23] rather than a value (h % 24) / 24, which is hard to interpret for human users.

Parameters:

world – The World instance in which observations will be computed. Currently unused.
agent – The Agent instance of the agent for which we compute observations. Currently unused.

Return type:

gymnasium.spaces.Box

Returns:

A gym Box, whose low field indicates the minimum value of each element of the observation vector. Similarly, the high field indicates the maximum value of each element, such that each element i of the vector is contained between low[i] and high[i]. The Box’s shape is the number of fields.

well_being: float¶: The median of agents’ comforts.