The OpfEnv Base Class

The OpfEnv base class is the core of the OPF-Gym library. It inherits from the gymnasium.Env class and implements the gymnasium API. Additionally, it provides the following main functionalities:

• Automatic conversion of a pandapower OPF problem to a gymnasium environment.

• Extended API to compute a baseline OPF solution (using pandapower) and to evaluate the performance of the RL agent.

• Various pre-implemented environment design options for representing the OPF problem as an RL environment. (see Environment Design Options)

All environments that inherit from the OpfEnv base class will have these functionalities.

Methods:

The OpfEnv base class provides the following methods:

OpfEnv.reset(seed: int | None = None, options: dict | None = None) → tuple[ndarray, dict]

gymnasium API. Reset the environment to a new state. Samples a random state from the given data distribution, applies an initial action, runs a power flow calculation (optional), and returns the initial observation.

Parameters:

• seed – Seed for the random number generator.

• options – Additional options for the reset method. Available options: ‘step’ (int) to control the data sampling, ‘test’ (bool) to sample from test data.

OpfEnv.step(action: ndarray) → tuple[ndarray, float, bool, bool, dict]

gymnasium API: Step the environment to a new state. Applies the actions, runs a power flow, checks for constraint violations, calculates the reward, and returns all information requires for learning

Parameters:

action – The action to apply to the power system.

OpfEnv.render(**kwargs)

gymnasium API. Render the current state of the power system. Uses the simple_plot pandapower method. Overwrite for more sophisticated rendering. For kwargs information, refer to the pandapower docs: https://pandapower.readthedocs.io/en/latest/plotting/matplotlib/simple_plot.html

OpfEnv.get_state() → ndarray

Return the state of the underlying power system. Relevant for partially observable environments. Steal the popgym API for this, compare https://popgym.readthedocs.io/en/latest/autoapi/popgym/core/env/index.html

OpfEnv.run_power_flow(**kwargs)

Updates the current power system state with the respective power flow (line loading, voltage magnitudes, etc.). Should be called whenever the power system state changed. The keyword arguments can be used to pass additional arguments to the power flow solver.

Parameters:

kwargs – Additional arguments for the power flow solver. (default: pandapower. Compare: https://pandapower.readthedocs.io/en/latest/powerflow/ac.html)

OpfEnv.run_optimal_power_flow(**kwargs)

Creates and internal copy of the power system with its current state and performs the OPF on that copy. Should be called to compare the current solution with the optimal solution. The keyword arguments can be used to pass additional arguments to the pandapower OPF solver.

Parameters:

kwargs – Additional arguments for the OPF solver. (default: pandapower. Compare: https://pandapower.readthedocs.io/en/latest/opf/formulation.html)

OpfEnv.get_objective() → float

Returns the currrent value of the objective function.

OpfEnv.get_optimal_objective() → float

Returns the optimal value of the objective function. Warning: Can only be called if run_optimal_power_flow() method was called before.

OpfEnv.is_state_valid() → bool

Returns True if the current state does not contain constraint violations.

OpfEnv.is_optimal_state_valid() → bool

Returns True if the state after OPF calculation does not contain constraint violations.

Warning: Can only be called if run_optimal_power_flow() method was called before.

Warning 2: Usually, the OPF does not converge if no valid solutions can be found. This method is only applicable if the OPF yielded a solution. However, a non-converged OPF can be counted as an invalid state in most cases.

OpfEnv.get_actions() → ndarray

Returns the current actions that were applied to the power system.

Warning: Not necessarily the exact same actions that were used in the step() method because some rounding, clipping, etc. might have happened. However, the resulting power flows should be same. Useful for storing and reproducing results.

OpfEnv.get_optimal_actions() → ndarray

Returns the optimal actions that were calculated by the OPF. Useful for creating datasets for supervised learning.

Warning: Can only be called if run_optimal_power_flow() method was called before.