commonpower.core.System

class System(power_flow_model: PowerFlowModel)

Bases: ControllableModelEntity

Singleton class to serve as root of the model hierarchy. The System manages all nodes/lines and provides the interfaces to simulate/control them.

Parameters:

power_flow_model (PowerFlowModel) – Power flow model to include in the system’s constraints.

Methods

add_data_provider	Adds a data provider to the entity.
add_line	Adds a line to the system.
add_node	Adds a node to the system.
add_to_model	This method adds the system to the global pyomo model.
clear_data_providers
compute_cost	Computes the cost based on the specified cost_fcn and stores the result in the systems' cost parameter.
cost_fcn	Returns the pyomo expression of the entity's cost function.
create_env_func	Creates an environment which encapsulates the power system in a way that RL algorithms can interact with it.
detach_controller	Remove the current controller from the entity
empty_copy	Creates a fresh copy of the system.
fix_inputs	Set the variables corresponding to inputs to fixed
get_all_data_providers	Recursively retrieves all data providers associated with a given node and its children.
get_children
get_controllers	Get dictionary of {controller_id : controller} based on the type of controllers (returns all controllers if no types are specified).
get_first_level_non_structure_nodes	This "unpacks" all nodes/buses which are first level children of StructureNodes.
get_input_ids	Get identifiers of input elements of a given model instance or self :param model_instance: model to get the input element identifiers for
get_inputs	Extracts model elements of type INPUT from a given model instance or self :param model_instance: model to get the input elements for :type model_instance: ConcreteModel, Optional
get_pyomo_element	Gets a pyomo element referenced by name from the given model.
get_pyomo_element_id	Constructs the global element name from the local name.
get_self_as_pyomo_block	Retrieves the pyomo block of the calling entity from a global model (based on the entity's global id).
get_value	Gets the value of the specified model element.
has_pyomo_element	This is essentially an indicator wrapper around get_pyomo_element() which returns False if no corresponding model element could be found (instead of raising an error).
info	Prints some information about this entity.
initialize	Initializes the system.
input_space	Determines the input space of an entity from the bounds of all model elements with type INPUT within the tree :param normalize: Whether or not to normalize the input space to [-1,1] :type normalize: bool
limit_date_range
load_from_file
n_inputs	Total number of model elements with type INPUT within the entire tree of this entity
observation_space	Determines the observation space of an entity based on the observation mask by retrieving the bounds of the model elements listed in the mask
observe	Get observations for all controllers within the system.
pprint	Prints an overview of the system members.
register_controller	Register a controller with this node :param controller: controller to be registered :type controller: BaseController
reset	Resets the system model to the state at a certain timestamp.
sample_start_date	Get start date and time for a power system simulation.
save_to_file
set_value	Sets the value of the specified model element to the specified value.
step	Runs one time step of the power system simulation.
terminal_step	Terminal step of the simulation.
unmodeled_update	Executes the unmodeled updates of all system nodes.
update	Moves the system one time step forward.
update_data	Updates the data sources of the system for the given timestamp.

classmethod _get_model_elements() → List[ModelElement]

This is the central method which all subclasses must implement. Here, the model elements of the entity are defined. For clarity, specify main variables and parameters here and specify constraints and auxiliary variables in _augment_model_elements().

Returns:

list[ModelElement] – List of model elements which will represent the entity in the pyomo model.

add_line(line: Line) → System

Adds a line to the system.

Parameters:

line (Line) – Line instance to add.

Returns:

System – System instance.

add_node(node: Node, at_index: int | None = None) → System

Adds a node to the system. Here, the node’s id is set according to its position in the model hierarchy.

Parameters:

• node (Node) – Node istance to add.

• at_index (int, optional) – Specifies to override the existing node at this index in the system’s node list.

Returns:

System – System instance.

add_to_model(model: ConcreteModel) → None

This method adds the system to the global pyomo model. Accordingly, it adds all specified nodes, lines and power flow definitions.

Parameters:

model (ConcreteModel) – Root (global) pyomo model.

compute_cost() → None

Computes the cost based on the specified cost_fcn and stores the result in the systems’ cost parameter.

cost_fcn(scenario: CostScenario, model: ConcreteModel, t: int = 0) → Expression

Returns the pyomo expression of the entity’s cost function.

Parameters:

• model (ConcreteModel) – Model to refer to.

• t (int, optional) – Time. Defaults to 0.

Returns:

Expression – Cost function.

create_env_func(episode_length: int = 24, wrapper: Wrapper | None = None, fixed_start: datetime | None = None, normalize_actions: bool = True, history: ModelHistory | None = None)

Creates an environment which encapsulates the power system in a way that RL algorithms can interact with it. Based on the OpenAI Gym environment API.

Parameters:

• episode_length (int) – how many environment interaction steps to complete before resetting the environment

• wrapper (gym.Wrapper) – any class to wrap around the standard ControlEnv API provided within this repository

• environment) ((used for example to map from multi-agent environment to single-agent)

• fixed_start (datetime) – whether to run on a fixed given day

• normalize_actions (bool) – whether or not to normalize the action space

• history (ModelHistory) – logger

Returns:

wrapper(ControlEnv) – environment instance

empty_copy(with_entities: bool = True) → System

Creates a fresh copy of the system.

Returns:

System – Cloned system instance.

get_all_data_providers(node=None, provider=None) → list[DataProvider]

Recursively retrieves all data providers associated with a given node and its children.

Parameters:

• node (Node) – The node to retrieve data providers from.

• provider (list[DataProvider], optional) – The list of data providers (only used for recursion). Defaults to None.

Returns:

list[DataProvider] – A list of all data providers associated with the node.

get_controllers(ctrl_types: list | None = None) → dict

Get dictionary of {controller_id : controller} based on the type of controllers (returns all controllers if no types are specified).

Parameters:

ctrl_types (list) – list of controller types to be included (if None, all controllers are included).

Returns:

dict – dictionary of {controller_id: controller} of specified types

get_first_level_non_structure_nodes() → List[ModelEntity]

This “unpacks” all nodes/buses which are first level children of StructureNodes. Used for determining all buses relevant for power flow caluculations.

Returns:

list[ModelEntity] – List of child entities.

initialize(episode_horizon: ~datetime.timedelta = datetime.timedelta(0), horizon: ~datetime.timedelta = datetime.timedelta(days=1), tau: ~datetime.timedelta = datetime.timedelta(seconds=3600), continuous_control: bool = False, solver: ~pyomo.opt.base.solvers.OptSolver = <pyomo.solvers.plugins.solvers.gurobi_direct.GurobiDirect object>) → None

Initializes the system. This constructs the pyomo model of the system by traversing through the object tree (nodes, lines, power flow), calling self.add_to_model(). It validates if required data providers are present and if controllers have been defined appropriately.

Parameters:

• episode_horizon (timedelta) – Specifies how long RL agents simulate the system before resetting. Mainly needed to adjust the date_range of the system.

• horizon (timedelta, optional) – This specifies the time period for which the controllers “look into the future”. Defaults to 24h.

• tau (timedelta, optional) – Sample time, i.e., the period of time between to control actions. This needs to match the frequency of data providers. Defaults to timedelta(hours=1).

• continuous_control (bool) – whether to use an infinite control horizon

• solver (OptSolver, optional) – Solver instance for the optimization problem that will be called by Pyomo.

observe() → dict

Get observations for all controllers within the system.

Returns:

dict – dictionary of {controller_id: controller_observation}

pprint() → None

Prints an overview of the system members.

reset(at_time: datetime) → None

Resets the system model to the state at a certain timestamp. It creates a clone of the system’s “raw” pyomo model which will then be used for simulation. Furthermore, entities’ parameters are initialized according to their configuration.

Parameters:

at_time (datetime) – Timestamp to begin the simulation from.

sample_start_date(fixed_start: datetime | None = None) → str

Get start date and time for a power system simulation. Can be a fixed start time or a start time sampled randomly from the date range for which the data sources within the system are configured. Currently, the start time will always be at the beginning of the day.

Parameters:

fixed_start (datetime) – Specific timestamp to start the simulation. If None, a random start time will be sampled.

Returns:

datetime – day, month, year, hour, minutes when to reset the system

step(obs: dict | None = None, rl_action_callback: Callable | None = None, history: ModelHistory | None = None) → tuple[dict, dict, dict]

Runs one time step of the power system simulation. This includes fixing the actions computed by the system’s controllers within the Pyomo model, solving the Pyomo model, and updating the states and data sources within the model. The return values of this function adhere to the OpenAI Gym API, such that the method can be called within the ControlEnv step() function to obtain the information required for RL training.

Parameters:

• obs (dict) – dictionary of {controller_id: controller_observation}

• rl_action_callback (Callable) – callback used to retrieve actions from RL controllers

• model_history (ModelHistroy, optional) – Instance of ModelHistory to log the system model.

Returns:

dict – dictionary of observations of all controllers {controller_id: controller_observation} AFTER applying the actions to the system dict: dictionary of rewards of all controllers {controller_id: controller_observation} AFTER applying the actions to the system. The rewards depend on the current state of the system and the action applied in this state, as well as on whether the action had to be corrected due to safety constraints. dict: additional information

terminal_step(history: ModelHistory | None = None) → None

Terminal step of the simulation. Here, we

1. log the final state of the system to the history

2. compute a perfect knowledge optimal control trajectory and store it in the prediction horizon of the last history log. This can be used to estimate the value of the terminal system state. For example, the perfect knowledge trajectory would in the standard case discharge all existing ESS within the horizon. Accordingly, the predicted final state of t_terminal + horizon is identical across different controllers, which allows for better comparability.

Parameters:

model_history (ModelHistroy, optional) – Instance of ModelHistory to log the system model.

unmodeled_update()

Executes the unmodeled updates of all system nodes.

update()

Moves the system one time step forward. Loads new values from data providers and updates state variables.

update_data(at_time: datetime)

Updates the data sources of the system for the given timestamp.

Parameters:

at_time (datetime) – Timestamp of “now”.