smartgrid.world.World

class smartgrid.world.World(agents: Iterable[Agent], energy_generator: EnergyGenerator)

Bases: object

Represents the “physical” (simulated) smart grid.

As per the Gym framework, our World represents the smart grid, and manages interactions within agents in the smart grid. It handles transitions between time steps, i.e., simulating the changes that happen, which are provoked by the agents’ actions and the smart grid dynamics (energy generation, etc.).

__init__(agents: Iterable[Agent], energy_generator: EnergyGenerator)

Create a new simulated world.

Parameters:

• agents – The list of agents that partake in this smart grid.

• energy_generator – The generator used to produce energy at each time step, based on the agents in the world and their needs.

Methods

__init__(agents, energy_generator)	Create a new simulated world.
reset([random_generator])	Resets the state of the world to the initial state.
step()	Perform a new step of the simulation.

Attributes

agents	Iterable of all agents acting in the world.
current_need	The total energy that agents currently need, for this time step.
max_needed_energy	The total amount of energy that all agents need.
min_needed_energy	The minimum sum of energy that all agents need, for all time steps.
agents_by_name	Agents in the World, indexed by their name.
current_step	Current time step of the world.
available_energy	Current quantity of available energy in the local grid.
energy_generator	Generator of energy for each time step, at the smart grid level.

property agents: Iterable[Agent]

Iterable of all agents acting in the world.

This iterable can be used to iterate on all agents, when accessing them by their name is not required (see agents_by_name for this). It is internally set as a view on the dictionary’s dict.values().

agents_by_name: Dict[str, Agent]

Agents in the World, indexed by their name.

This allows efficient access to a specific Agent based on its name. Agents represent prosumers (buildings) that act in this World (by consuming and exchanging energy).

Note

There is (currently) no support for “scripted” agents, i.e., all agents in the world are considered to be “policy” agents: they receive observations and algorithms must decide actions for them, through the environment interaction loop (see SmartGrid for more details).

Note

Adding agents is currently not supported in this version.

available_energy: int

Current quantity of available energy in the local grid.

At each time step, the smart grid generates an important quantity of energy that is accessible to all agents. This quantity is assumed to come from an important but local source, such as a windmill farm, or an hydraulic power plant.

It is separated from the national grid, which is considered unlimited, but must be paid by agents. On the contrary, the smart grid’s available energy is free, but limited, and agents must learn not to consume too much so as to let energy for others.

See energy_generator for more details on how the available energy is generated at each step.

property current_need

The total energy that agents currently need, for this time step.

For now computed on-demand, but may be stored as an attribute in the future, to avoid computations.

current_step: int

Current time step of the world.

Each time step corresponds to a simulated hour, which the world keeps track of. The world is also responsible for incrementing the time steps, and simulating the next step.

Initially, current_step is set to 0.

energy_generator: EnergyGenerator

Generator of energy for each time step, at the smart grid level.

We recall that the smart grid locally generates an important quantity of energy accessible to all agents.

In order to make this generation agnostic to the number and profiles of agents, the energy generators rely on the maximum energy needed by all agents.

For example, consider 3 Households agents with a maximal need of 10kWh each. The maximum energy needed in the whole world will thus be 30kWh. A generator may produce between 80% and 120% of this maximal need, which means that in some cases, there is not enough energy for all agents, and they must reduce consumption (or risk preventing others from consuming), and in other cases, there is more energy than necessary, and they can store energy for later.

See EnergyGenerator for more details.

property max_needed_energy

The total amount of energy that all agents need.

It can be used for example to interpolate the current amount of available energy to [0,1]. This maximum amount depends on the list of current agents, especially the maximum amount of energy that each may need.

property min_needed_energy

The minimum sum of energy that all agents need, for all time steps.

Currently simplified to return 0, may be more accurate in the future.

reset(random_generator: Generator | None = None)

Resets the state of the world to the initial state.

This resets the current step, the observation manager, the agents themselves, and the available energy.

This function must be called when initializing the world.

Parameters:

random_generator – The NumPy random generator, for reproducibility purposes. This is automatically handled by the SmartGrid reset() method. By default (to facilitate using the World and to avoid breaking the API), it will be set to a new Random Generator.

step()

Perform a new step of the simulation.

This function performs the following:

1. Actions are truly enacted. They were “intended” before, i.e., agents output a decision; now they are applied to the world, and the world is updated accordingly. For exemple by updating the agents’ payoffs, their battery, the available energy, and so on.

2. Agents are updated. They generate a new need, a new production, and they compute their comfort.

3. A new available_energy is generated, based on the (new) agents’ needs.