Predefined Controllers

Basic Controller

The basic controller is the base controller class that should be subclassed when implementing custom controllers.

class pandapower.control.basic_controller.Controller(net, in_service=True, order=0, level=0, index=None, recycle=False, drop_same_existing_ctrl=False, initial_run=True, overwrite=False, matching_params=None, **kwargs)

Base-Class of all controllable elements within a network.

add_controller_to_net(net, in_service, initial_run, order, level, index, recycle, drop_same_existing_ctrl, overwrite, **kwargs)

adds the controller to net[‘controller’] dataframe.

INPUT:

in_service (bool) - in service status

order (int) - order

index (int) - index

recycle (bool) - if controller needs a new bbm (ppc, Ybus…) or if it can be used with prestored values. This is mostly needed for time series calculations

control_step(net)

If the is_converged method returns false, the control_step will be called. In other words: if the controller did not converge yet, this method should implement actions that promote convergence e.g. adapting actuating variables and writing them back to the data structure.

finalize_control(net)

Some controller require extended finalization. This method is being called at the end of a loadflow. It is a separate method from restore_init_state because it is possible that control finalization does not only restore the init state but also something in addition to that, that would require the results in net

finalize_step(net)

Note

This method is ONLY being called during time-series simulation!

After each time step, this method is being called to clean things up or similar. The OutputWriter is a class specifically designed to store results of the loadflow. If the ControlHandler.output_writer got an instance of this class, it will be called before the finalize step.

initialize_control(net)

Some controller require extended initialization in respect to the current state of the net (or their view of it). This method is being called after an initial loadflow but BEFORE any control strategies are being applied.

This method may be interesting if you are aiming for a global controller or if it has to be aware of its initial state.

is_converged(net)

This method calculated whether or not the controller converged. This is where any target values are being calculated and compared to the actual measurements. Returns convergence of the controller.

repair_control(net)

Some controllers can cause net to not converge. In this case, they can implement a method to try and catch the load flow error by altering some values in net, for example load scaling. This method is being called in the except block in run_control. Either implement this in a controller that is likely to cause the error, or define a special “load flow police” controller for your use case

restore_init_state(net)

Some controllers manipulate values in net and then restore them back to initial values, e.g. DistributedSlack. This method should be used for such a purpose because it is executed in the except block of run_control to make sure that the net condition is restored even if load flow calculation doesn’t converge

set_active(net, in_service)

Sets the controller in or out of service

set_recycle(net)

Checks the recyclability of this controller and changes the recyclability of the control handler if necessary. With this a faster time series calculation can be achieved since not everything must be recalculated.

Beware: Setting recycle wrong can mess up your results. Set it to False in init if in doubt!

time_step(net, time)

It is the first call in each time step, thus suited for things like reading profiles or prepare the controller for the next control step.

Note

This method is ONLY being called during time-series simulation!

ConstControl

This controller is made for the use with the time series module to read data from a DataSource and write it to the net. The controller can write the values either to a column of an element table (e.g. net.load.p_mw) or an attribute of another object that is stored in an element table (e.g. another controller, net.controller.object). To change a controller attribute, the variable must be defined in the format “object.attribute” (e.g. “object.set_vm_pu”). Note that ConstControl writes values to net in time_step, in order to set the values of the time step before the initial power flow. If ConstControl is used without a data_source, it will reset the controlled values to the initial values, preserving the initial net state.

class pandapower.control.controller.const_control.ConstControl(net, element, variable, element_index, profile_name=None, data_source=None, scale_factor=1.0, in_service=True, recycle=True, order=- 1, level=- 1, drop_same_existing_ctrl=False, matching_params=None, initial_run=False, **kwargs)

Class representing a generic time series controller for a specified element and variable. Control strategy: “No Control” -> updates values of specified elements according to timeseries input data. If ConstControl is used without timeseries input data, it will reset the controlled values to the initial values, preserving the initial net state. The timeseries values are written to net during time_step before the initial powerflow run and before other controllers’ control_step. It is possible to set attributes of objects that are contained in a net table, e.g. attributes of other controllers. This can be helpful e.g. if a voltage setpoint of a transformer tap changer depends on the time step. An attribute of an object in the “object” column of a table (e.g. net.controller[“object”] -> net.controller.object.at[0, “vm_set_pu”] can be set if the attribute is specified as “object.attribute” (e.g. “object.vm_set_pu”).

INPUT:

net (attrdict) - The net in which the controller resides

element - element table (‘sgen’, ‘load’ etc.)

variable - variable (‘p_mw’, ‘q_mvar’, ‘vm_pu’, ‘tap_pos’ etc.)

element_index (int[]) - IDs of the controlled elements

data_source (obj) - The data source that provides profile data

profile_name (str[]) - The profile names of the elements in the data source

OPTIONAL:

scale_factor (real, 1.0) - Scaling factor for time series input values

in_service (bool, True) - Indicates if the controller is currently in_service

recycle (bool, True) - Re-use of internal-data in a time series loop.

drop_same_existing_ctrl (bool, False) - Indicates if already existing controllers of the same type and with the same matching parameters (e.g. at same element) should be dropped

Note

If multiple elements are represented with one controller, the data source must have integer columns. At the moment, only the DFData format is tested for the multiple const control.

control_step(net)

Set applied to True, which means that the values set in time_step have been included in the load flow calculation.

is_converged(net)

Actual implementation of the convergence criteria: If controller is applied, it can stop

set_recycle(net)

Checks the recyclability of this controller and changes the recyclability of the control handler if necessary. With this a faster time series calculation can be achieved since not everything must be recalculated.

Beware: Setting recycle wrong can mess up your results. Set it to False in init if in doubt!

time_step(net, time)

Get the values of the element from data source Write to pandapower net by calling write_to_net() If ConstControl is used without a data_source, it will reset the controlled values to the initial values, preserving the initial net state.

write_to_net(net)

Writes to self.element at index self.element_index in the column self.variable the data from self.values

TrafoController

The following controllers to control tap changers are predefined within the pandapower control module.

Continuous Tap Control

class pandapower.control.controller.trafo.ContinuousTapControl.ContinuousTapControl(net, tid, vm_set_pu, tol=0.001, side='lv', trafotype='2W', in_service=True, check_tap_bounds=True, level=0, order=0, drop_same_existing_ctrl=False, matching_params=None, **kwargs)

Trafo Controller with local tap changer voltage control.

INPUT:

net (attrdict) - Pandapower struct

tid (int) - ID of the trafo that is controlled

vm_set_pu (float) - Maximum OLTC target voltage at bus in pu

OPTIONAL:

tol (float, 0.001) - Voltage tolerance band at bus in percent (default: 1% = 0.01pu)

side (string, “lv”) - Side of the transformer where the voltage is controlled

trafo_type (float, “2W”) - Trafo type (“2W” or “3W”)

in_service (bool, True) - Indicates if the controller is currently in_service

check_tap_bounds (bool, True) - In case of true the tap_bounds will be considered

drop_same_existing_ctrl (bool, False) - Indicates if already existing controllers of the same type and with the same matching parameters (e.g. at same element) should be dropped

control_step(net)

Implements one step of the ContinuousTapControl

is_converged(net)

The ContinuousTapControl is converged, when the difference of the voltage between control steps is smaller than the Tolerance (tol).


Discrete Tap Control

class pandapower.control.controller.trafo.DiscreteTapControl.DiscreteTapControl(net, tid, vm_lower_pu, vm_upper_pu, side='lv', trafotype='2W', tol=0.001, in_service=True, order=0, drop_same_existing_ctrl=False, matching_params=None, **kwargs)

Trafo Controller with local tap changer voltage control.

INPUT:

net (attrdict) - Pandapower struct

tid (int) - ID of the trafo that is controlled

vm_lower_pu (float) - Lower voltage limit in pu

vm_upper_pu (float) - Upper voltage limit in pu

OPTIONAL:

side (string, “lv”) - Side of the transformer where the voltage is controlled (hv or lv)

trafotype (float, “2W”) - Trafo type (“2W” or “3W”)

tol (float, 0.001) - Voltage tolerance band at bus in Percent (default: 1% = 0.01pu)

in_service (bool, True) - Indicates if the controller is currently in_service

drop_same_existing_ctrl (bool, False) - Indicates if already existing controllers of the same type and with the same matching parameters (e.g. at same element) should be dropped

control_step(net)

Implements one step of the Discrete controller, always stepping only one tap position up or down

classmethod from_tap_step_percent(net, tid, vm_set_pu, side='lv', trafotype='2W', tol=0.001, in_service=True, order=0, drop_same_existing_ctrl=False, matching_params=None, **kwargs)

Alternative mode of the controller, which uses a set point for voltage and the value of net.trafo.tap_step_percent to calculate vm_upper_pu and vm_lower_pu. To this end, the parameter vm_set_pu should be provided, instead of vm_lower_pu and vm_upper_pu. To use this mode of the controller, the controller can be initialized as following:

>>> c = DiscreteTapControl.from_tap_step_percent(net, tid, vm_set_pu)
INPUT:

net (attrdict) - Pandapower struct

tid (int) - ID of the trafo that is controlled

vm_set_pu (float) - Voltage setpoint in pu

initialize_control(net)

Some controller require extended initialization in respect to the current state of the net (or their view of it). This method is being called after an initial loadflow but BEFORE any control strategies are being applied.

This method may be interesting if you are aiming for a global controller or if it has to be aware of its initial state.

is_converged(net)

Checks if the voltage is within the desired voltage band, then returns True

CharacteristicControl

The following controllers that use characteristics are predefined within the pandapower control module.

CharacteristicControl

class pandapower.control.controller.characteristic_control.CharacteristicControl(net, output_element, output_variable, output_element_index, input_element, input_variable, input_element_index, characteristic, tol=0.001, in_service=True, order=0, level=0, drop_same_existing_ctrl=False, matching_params=None, **kwargs)

Controller that adjusts a certain parameter of an element in pandapower net based on a specified input parameter in pandapower net, according to a provided characteristic. Example: change the tap position of the transformers (net.trafo.tap_pos) based on transformer loading (net.res_trafo.loading_percent) according to a specified linear relationship. To this end, the input element is “res_trafo”, the input variable is “loading_percent”, the output element is “trafo” and the output variable is “tap_pos”. The relationship between the values of the input and output variables is specified using the Characteristic class (or a scipy interpolator, e.g. scipy.interpolate.interp1d).

INPUT:

net (attrdict) - Pandapower net

output_element (str) - name of the element table in pandapower net where the values are adjusted by the controller

output_variable (str) - variable in the output element table, values of which are adjusted by the controller. Can also be an

attribute of an object (e.g. parameter of a controller object), for this case it must start with “object.” (e.g. “object.vm_set_pu”)

output_element_index (int or list or numpy array) - index of the elements, values fro which are adjusted

input_element (str) - name of the element table or the element result table in pandapower net that provides input values for

the controller

input_variable (str) - name of the input variable in the input element table. Can also be an attribute of an object,

similarly to output_variable

input_element_index (int or list or numpy array) - index of elements in the input element table

characteristic (object of class Characteristic, or a scipy interpolator object) - characteristic curve that describes the

relationship between the input and output values

tol (float) - tolerance for convergence

OPTIONAL:

in_service (bool, True) - Indicates if the controller is currently in_service

drop_same_existing_ctrl (bool, False) - Indicates if already existing controllers of the same type and with the same matching parameters (e.g. at same element) should be dropped

control_step(net)

Set applied to true to make sure it runs at least once

initialize_control(net)

At the beginning of each run_control call reset applied-flag

is_converged(net)

Actual implementation of the convergence criteria: If controller is applied, it can stop

read_from_net(net, output=False)

Writes to self.element at index self.element_index in the column self.variable the data from self.values

write_to_net(net)

Writes to self.element at index self.element_index in the column self.variable the data from self.values


USetTapControl

class pandapower.control.controller.trafo.USetTapControl.USetTapControl(net, cid, variable='p_hv_mw', characteristic=<pandapower.control.util.characteristic.Characteristic object>, tol=0.001, in_service=True, order=0, level=0, drop_same_existing_ctrl=False, matching_params=None, **kwargs)

Controller that adjusts the setpoint of a local tap changer voltage control based on a load flow result (e.g. p_lv_mw, i_lv_ka etc.) according to a defined characteristic.

INPUT:

net (attrdict) - Pandapower net

cid (int) - ID of the tap changer controller, an attribute of which is controlled

variable (float) - Variable from the result table that is used for the characteristic

OPTIONAL:

in_service (bool, True) - Indicates if the controller is currently in_service

drop_same_existing_ctrl (bool, False) - Indicates if already existing controllers of the same type and with the same matching parameters (e.g. at same element) should be dropped