API reference

Module agent

class pypownet.agent.ActIOnManager(destination_path='saved_actions.csv', delete=True)

dump(action)

static load(filepath)

class pypownet.agent.ActionsFileReaderControler(environment)

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

class pypownet.agent.Agent(environment)

The template to be used to create an agent: any controller of the power grid is expected to be a daughter of this class.

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

feed_reward(action, consequent_observation, rewards_aslist)

class pypownet.agent.DoNothing(environment)

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

class pypownet.agent.FlowsSaver(environment)

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

class pypownet.agent.GreedySearch(environment)

This agent is a tree-search model of depth 1, that is constrained to modifiying at most 1 substation configuration or at most 1 line status. This controller used the simulate method of the environment, by testing every 1-line status switch action, every new configuration for substations with at least 4 elements, as well as the do-nothing action. Then, it will seek for the best reward and return the associated action, expecting the maximum reward for the action pool it can reach. Note that the simulate method is only an approximation of the step method of the environment, and in three ways: * simulate uses the DC mode, while step is in AC * simulate uses only the predictions given to the player to simulate the next timestep injections * simulate can not compute the hazards that are supposed to come at the next timestep

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

class pypownet.agent.RandomAction(environment)

An example of a baseline controller that produce random actions (ie random line switches and random node switches.

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

class pypownet.agent.RandomLineSwitch(environment)

An example of a baseline controller that randomly switches the status of one random power line per timestep (if the random line is previously online, switch it off, otherwise switch it on).

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

class pypownet.agent.RandomNodeSplitting(environment)

Implements a “random node-splitting” agent: at each timestep, this controller will select a random substation (id), then select a random switch configuration such that switched elements of the selected substations change the node within the substation on which they are directly wired.

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

class pypownet.agent.RandomPointAction(environment)

An example of a baseline controller that produce 1 random activation (ie an array with all 0 but one 1).

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

class pypownet.agent.TreeSearchLineServiceStatus(environment)

Exhaustive tree search of depth 1 limited to no action + 1 line switch activation

act(observation)

Produces an action given an observation of the environment.

Takes as argument an observation of the current state, and returns the chosen action of class Action or np array.

Module grid

exception pypownet.grid.DivergingLoadflowException(last_observation, *args)

class pypownet.grid.Grid(loadflow_backend, src_filename, dc_loadflow, new_imaps)

apply_topology(new_topology)

Applies a new topology to self. topology should be an instance of class Topology, with computed values to be replaced in self.

Parameters:new_topology – an instance of Topology, with destination values for the nodes values/lines service status

compute_loadflow(fname_end)

Given the current state of the grid (topology + injections), compute the new loadflow of the grid. This function subtreats the Octave pipeline to self.__vanilla_matpower_callback.

Returns:0 for failed computation, 1 for success Raises:DivergingLoadflowException – if the loadflow did not converge, raise diverging exception (could be because of grid not connexe, or voltages issues, or angle issues etc).

compute_topological_mapping_permutation()

Computes a permutation that shuffles the construction order of a topology (prods->loads->lines or->lines ex) into a representation where all elements of a substation are consecutive values (same order, but locally). By construction, the topological vector is the concatenation of the subvectors: productions nodes (for each value, on which node, 0 or 1, the prod is wired), loads nodes, lines origin nodes, lines extremity nodes and the lines service status.

This function should only be called once, at the instantiation of the grid, for it computes the fixed mapping function for the remaining of the game (also fixed along games).

discard_flows()

export_lines_capacity_usage(safe_mode=False)

Computes and returns the lines capacity usage, i.e. the elementwise division of the flows in Ampere by the lines nominal thermal limit.

Returns:a list of size the number of lines of positive values

export_to_observation()

Exports the current grid state into an observation.

extract_flows_a(safe_mode=False)

get_lines_status()

get_number_elements()

get_thermal_limits()

get_topology()

load_timestep_injections(timestep_injections, prods_p=None, prods_v=None, loads_p=None, loads_q=None)

Loads a scenario from class Scenario: contains P and V values for prods, and P and Q values for loads. Other timestep entries are loaded using other modules (including pypownet.game). If one of input except TimestepInjections are not None, they are all used for next injections (used in simulate with planned injections).

Parameters:timestep_injections – an instance of class Scenario Returns:if do_trigger_lf_computation then the result of self.compute_loadflow else nothing

normalize_prods_voltages(voltages)

set_flows_to_0()

set_lines_status(new_lines_status)

set_voltage_angles(new_voltage_angles)

set_voltage_magnitudes(new_voltage_magnitudes)

exception pypownet.grid.GridNotConnexeException(last_observation, *args)

class pypownet.grid.Topology(prods_nodes, loads_nodes, lines_or_nodes, lines_ex_nodes, mapping_array)

This class is a container for the topology lists defining the current topological state of a grid. Topology should be manipulated using this class, as it maintains the adopted convention consistently.

get_length()

get_unzipped()

get_zipped()

static unzip(topology, n_prods, n_loads, n_lines, invert_mapping_function)

pypownet.grid.compute_flows_a(active, reactive, voltage, are_lines_on)

Module env

class pypownet.environment.ActionSpace(number_generators, number_consumers, number_power_lines, number_substations, substations_ids, prods_subs_ids, loads_subs_ids, lines_or_subs_id, lines_ex_subs_id)

_verify_action_shape(action)

array_to_action(array)

Converts and returns an pypownet.game.Action from a array-object (e.g. list, numpy arrays).

Parameters:array – array-style object Returns:an instance of pypownet.game.Action equivalent to input action Raises:ValueError – the input array is not of the same length than the expected action (self.action_length)

get_do_nothing_action(as_class_Action=False)

Creates and returns an action equivalent to a do-nothing: all of the activable switches are 0 i.e. not activated.

Returns:an instance of pypownet.game.Action that is equivalent to an action doing nothing

static get_lines_status_switch_from_id(action, line_id)

get_lines_status_switches_of_substation(action, substation_id)

get_number_elements_of_substation(substation_id)

get_substation_switches_in_action(action, substation_id, concatenated_output=True)

From the input action, retrieves the list of value of the switch (0 or 1) of the switches on which each element of the substation with input id. This function also computes the type of element associated to each switch value of the returned switches-value list.

Parameters:

• action – input action whether a numpy array or an element of class pypownet.game.Action.
• substation_id – an integer of the id of the substation to retrieve the switches of its elements in the input action.
• concatenated_output – False to return an array per elementype, True to return a single concatenated array

Returns:

a switch-values list (binary list) in the order: production (<=1), loads (<=1), lines origins, lines extremities; also returns a ElementType list of same size, where each value indicates the type of element associated to each first-returned list values.

static set_lines_status_switch_from_id(action, line_id, new_switch_value)

set_lines_status_switches_of_substation(action, substation_id, new_configuration)

set_substation_switches_in_action(action, substation_id, new_values)

Replaces the switches (binary) values of the input substation in the input action with the new specified values. Note that the mapping between the new values and the elements of the considered substation are the same as the one retrieved by the opposite function self.get_substation_switches. Consequently, the length of the array new_values is len(self.get_substation_switches(action, substation_id)[1]).

Parameters:

• action – input action whether a numpy array or an element of class pypownet.game.Action.
• substation_id – an integer of the id of the substation to retrieve the switches of its elements in the input action

Returns:

the modified action; WARNING: the input action is not modified in place if of array type: ensure that you catch the returned action as the modified action.

exception pypownet.environment.DivergingLoadflowException(last_observation, *args)

class pypownet.environment.ElementType

An enumeration.

CONSUMPTION = 'consumption'

EXTREMITY_POWER_LINE = 'extremity of power line'

ORIGIN_POWER_LINE = 'origin of power line'

PRODUCTION = 'production'

exception pypownet.environment.IllegalActionException(text, illegal_lines_reconnections, illegal_unavailable_lines_switches, illegal_oncoolown_substations_switches, *args)

class pypownet.environment.MinimalistACObservation(active_loads, reactive_loads, voltage_loads, active_productions, reactive_productions, voltage_productions, active_flows_origin, reactive_flows_origin, voltage_flows_origin, active_flows_extremity, reactive_flows_extremity, voltage_flows_extremity, ampere_flows, lines_status, are_loads_cut, are_productions_cut, timesteps_before_lines_reconnectable, timesteps_before_lines_reactionable, timesteps_before_nodes_reactionable, timesteps_before_planned_maintenance, planned_active_loads, planned_reactive_loads, planned_active_productions, planned_voltage_productions, date_year, date_month, date_day, date_hour, date_minute, date_second, productions_nodes, loads_nodes, lines_or_nodes, lines_ex_nodes)

as_array()

as_dict()

as_minimalist()

class pypownet.environment.MinimalistObservation(active_loads, active_productions, ampere_flows, lines_status, are_loads_cut, are_productions_cut, timesteps_before_lines_reconnectable, timesteps_before_lines_reactionable, timesteps_before_nodes_reactionable, timesteps_before_planned_maintenance, planned_active_loads, planned_active_productions, date_year, date_month, date_day, date_hour, date_minute, date_second, productions_nodes, loads_nodes, lines_or_nodes, lines_ex_nodes)

as_array()

as_dict()

class pypownet.environment.Observation(substations_ids, active_loads, reactive_loads, voltage_loads, active_productions, reactive_productions, voltage_productions, active_flows_origin, reactive_flows_origin, voltage_flows_origin, active_flows_extremity, reactive_flows_extremity, voltage_flows_extremity, ampere_flows, thermal_limits, lines_status, are_loads_cut, are_productions_cut, loads_substations_ids, productions_substations_ids, lines_or_substations_ids, lines_ex_substations_ids, timesteps_before_lines_reconnectable, timesteps_before_lines_reactionable, timesteps_before_nodes_reactionable, timesteps_before_planned_maintenance, planned_active_loads, planned_reactive_loads, planned_active_productions, planned_voltage_productions, date_year, date_month, date_day, date_hour, date_minute, date_second, productions_nodes, loads_nodes, lines_or_nodes, lines_ex_nodes, initial_productions_nodes, initial_loads_nodes, initial_lines_or_nodes, initial_lines_ex_nodes)

The class State is a container for all the values representing the state of a given grid at a given time. It contains the following values: * The active and reactive power values of the loads * The active power values and the voltage setpoints of the productions * The values of the power through the lines: the active and reactive values at the origin/extremity of the lines as well as the lines capacity usage * The exhaustive topology of the grid, as a stacked vector of one-hot vectors

as_ac_minimalist()

as_array()

as_dict()

as_minimalist()

get_lines_capacity_usage()

get_lines_status_of_substation(substation_id)

From the current observation, retrieves the list of lines status (binary) from lines connected to the input substations. This function also computes and retrieve the list of ifs of ids at the other end of each corresponding lines.

Parameters:substation_id – an integer of the id of the substation to retrieve the nodes on which its elements are wired Returns:(consistently fixed-order list of binary (0 or 1) values, list of ids of other end substations)

get_nodes_of_substation(substation_id)

From the current observation, retrieves the list of value of the nodes on which each element of the substation with input id. This function also computes the type of element associated to each node value of the returned nodes-value list.

Parameters:substation_id – an integer of the id of the substation to retrieve the nodes on which its elements are wired Returns:a nodes-values list in the order: production (<=1), loads (<=1), lines origins, lines extremities; also returns a ElementType list of same size, where each value indicates the type of element associated to each first-returned list values.

class pypownet.environment.ObservationSpace(number_generators, number_consumers, number_power_lines, number_substations, n_timesteps_horizon_maintenance)

array_to_observation(array)

Converts and returns an pypownet.game.Observation from a array-object (e.g. list, numpy arrays).

Parameters:array – array-style object Returns:an instance of pypownet.game.Action equivalent to input action Raises:ValueError – the input array is not of the same length than the expected action (self.action_length)

class pypownet.environment.RunEnv(parameters_folder, game_level, chronic_looping_mode='natural', start_id=0, game_over_mode='soft', renderer_latency=None, without_overflow_cutoff=False, seed=None)

static _RunEnv__wrap_exception(flag)

_get_obs()

get_current_chronic_name()

get_current_datetime()

get_observation(as_array=True)

is_action_valid(action)

process_game_over()

render(game_over=False)

reset()

Instantiate the game Environment based on the specified parameters.

simulate(action, do_sum=True)

Computes the reward of the simulation of action to the current grid.

step(action, do_sum=True)

Performs a game step given an action. The as list pattern is: load_cut_reward, prod_cut_reward, action_cost_reward, reference_grid_distance_reward, line_usage_reward

exception pypownet.environment.TooManyConsumptionsCut(*args)

exception pypownet.environment.TooManyProductionsCut(*args)

Module game

class pypownet.game.Action(prods_switches_subaction, loads_switches_subaction, lines_or_switches_subaction, lines_ex_switches_subaction, lines_status_subaction, substations_ids, prods_subs_ids, loads_subs_ids, lines_or_subs_id, lines_ex_subs_id, elementtype)

as_array()

get_lines_ex_switches_subaction()

get_lines_or_switches_subaction()

get_lines_status_subaction()

get_loads_switches_subaction()

get_node_splitting_subaction()

get_prods_switches_subaction()

get_substation_switches(substation_id, concatenated_output=True)

set_as_do_nothing()

set_node_splitting_subaction(new_node_splitting_subaction)

set_substation_switches(substation_id, new_values)

exception pypownet.game.DivergingLoadflowException(last_observation, *args)

class pypownet.game.Game(parameters_folder, game_level, chronic_looping_mode, chronic_starting_id, game_over_mode, renderer_frame_latency, without_overflow_cutoff)

apply_action(action)

Applies an action on the current grid (topology). The action is first into lists of same objects (e.g. nodes on which productions are connected), then the destination values are computed, such that the grid will replace its current topology with the latter. Since actions come from pypownet.env.RunEnv.Action, they are switches. Here, given the last values of the grid and the switches, this function computes the actual destination values (e.g. switch line status of line 10: if line 10 is on, put its status to off i.e. 0, otherwise put to on i.e. 1)

Parameters:action – an instance of pypownet.env.RunEnv.Action

export_observation()

Retrieves an observation of the current state of the grid.

Returns:an instance of class pypownet.env.Observation

get_changed_substations(action)

Computes the boolean array of changed substations from an Action.

get_current_chronic_name()

get_current_datetime()

get_current_timestep_id()

Retrieves the current index of scenario; this index might differs from a natural counter (some id may be missing within the chronic).

Returns:an integer of the id of the current scenario loaded

get_initial_topology()

Retrieves the initial topology of the grid (when it was initially loaded). This is notably used to reinitialize the grid after a game over.

Returns:an instance of pypownet.grid.Topology or a list of integers

get_max_seconds_per_timestep()

get_next_chronic()

get_number_elements()

get_reward_signal_class()

get_substations_ids()

get_substations_ids_lines_ex()

get_substations_ids_lines_or()

get_substations_ids_loads()

get_substations_ids_prods()

is_action_valid(action)

load_entries_from_next_timestep(is_simulation=False)

Loads the next timestep injections (set of injections, maintenance, hazard etc for the next timestep id).

Returns:

raise ValueError:  raised in the case where they are no more scenarios available

load_entries_from_timestep_id(timestep_id, is_simulation=False, silence=False)

parameters_environment_tostring()

process_game_over()

Handles game over behavior of the game: put the grid topology to the initial one + if restart is True, then the game will load the first set of injections (i)_{t0}, otherwise the next set of injections of the chronics (i)_{t+1}.

render(rewards, game_over=False, cascading_frame_id=None, date=None, timestep_id=None)

Initializes the renderer if not already done, then compute the necessary values to be carried to the renderer class (e.g. sum of consumptions).

Parameters:

• rewards – list of subrewards of the last timestep (used to plot reward per timestep)
• game_over – True to plot a “Game over!” over the screen if game is over

Returns:

raise ImportError:  pygame not found raises an error (it is mandatory for the renderer)

reset_grid()

Reinitialized the grid by applying the initial topology to the current state (topology).

simulate(action)

step(action, _is_simulation=False)

exception pypownet.game.IllegalActionException(text, has_too_much_activations, illegal_lines_reconnections, illegal_unavailable_lines_switches, illegal_oncoolown_substations_switches, *args)

get_has_too_much_activations()

get_illegal_broken_lines_reconnections()

get_illegal_oncoolown_lines_switches()

get_illegal_oncoolown_substations_switches()

is_empty

exception pypownet.game.ListExceptions(exceptions)

exception pypownet.game.NoMoreScenarios

exception pypownet.game.TooManyConsumptionsCut(*args)

exception pypownet.game.TooManyProductionsCut(*args)

Module main

pypownet.main.main()

Module renderer

class pypownet.renderer.Renderer(grid_case, or_ids, ex_ids, are_prods, are_loads, timestep_duration_seconds)

create_plot_loads_curve(n_timesteps, left_xlabel)

static draw_plot_game_over()

static draw_plot_pause()

draw_surface_diagnosis(number_loads_cut, number_prods_cut, number_nodes_splitting, number_lines_switches, distance_initial_grid, line_capacity_usage, n_offlines_lines, number_unavailable_lines, number_unavailable_nodes, max_number_isolated_loads, max_number_isolated_prods)

draw_surface_grid(relative_thermal_limits, lines_por, lines_service_status, prods, loads, are_substations_changed, number_nodes_per_substation)

draw_surface_legend()

draw_surface_loads_curves(n_hours_to_display_top_loadplot, n_hours_to_display_bottom_loadplot)

draw_surface_n_overflows(n_timesteps, left_xlabel=' 7 days ago ')

draw_surface_nodes_headers(scenario_id, date, cascading_result_frame)

draw_surface_relative_thermal_limits(n_timesteps, left_xlabel='24 hours ago')

render(lines_capacity_usage, lines_por, lines_service_status, epoch, timestep, scenario_id, prods, loads, date, are_substations_changed, number_nodes_per_substation, number_loads_cut, number_prods_cut, number_nodes_splitting, number_lines_switches, distance_initial_grid, number_off_lines, number_unavailable_lines, number_unactionable_nodes, max_number_isolated_loads, max_number_isolated_prods, game_over=False, cascading_frame_id=None)

pypownet.renderer.recenter()

pypownet.renderer.scale(u, z, t)

Module runner

class pypownet.runner.Runner(environment, agent, render=False, verbose=False, vverbose=False, parameters=None, level=None, max_iter=None, log_filepath='runner.log', machinelog_filepath='machine_logs.csv')

dump_machinelogs(timestep_id, done, reward, reward_aslist, cumul_rew, datetime)

loop(iterations, epochs=1)

Runs the simulator for the given number of iterations time the number of episodes. :param iterations: int of number of iterations per episode :param epochs: int of number of episodes, each resetting the environment at the beginning :return:

step(observation)

Performs a full RL step: the agent acts given an observation, receives and process the reward, and the env is resetted if done was returned as True; this also logs the variables of the system including actions, observations. :param observation: input observation to be given to the agent :return: (new observation, action taken, reward received)

exception pypownet.runner.TimestepTimeout

Module scenarios_chronic

class pypownet.chronic.Chronic(source_folder, with_previsions=True)

construct_timesteps_injections()

Loop over all the pertinent data row by row creating scenarios that are stored within the self.scenarios container.

static get_csv_content(csv_absolute_fpath)

get_imaps()

get_planned_maintenance(timestep_id, horizon)

get_timestep_duration()

get_timestep_entries(timestep_id)

get_timestep_ids()

import_data(data)

retrieve_data()

retrieve_input_files()

class pypownet.chronic.ChronicLooper(chronics_folder, game_level, start_id, looping_mode)

get_current_chronic_name()

get_next_chronic_folder()

class pypownet.chronic.TimestepEntries(timestep_id, loads_p, loads_q, prods_p, prods_v, maintenance, hazards, date, planned_loads_p=None, planned_loads_q=None, planned_prods_p=None, planned_prods_v=None)

get_datetime()

get_hazards()

get_id()

get_loads_p()

get_loads_q()

get_maintenance()

get_planned_loads_p()

get_planned_loads_q()

get_planned_prods_p()

get_planned_prods_v()

get_prods_p()

get_prods_v()

Indices and tables

• Index