# Controller to couple different networks¶

Controllers that connect to nets are stored in multinet[‘controller’].

## Basic Controller¶

These are some simple controllers that read values from one net, apply efficiency factors and unit conversions, and write the results to another net.

class P2GControlMultiEnergy(multinet, element_index_power, element_index_gas, efficiency, name_power_net='power', name_gas_net='gas', in_service=True, order=0, level=0, drop_same_existing_ctrl=False, initial_run=True, **kwargs)

A controller to be used in a multinet. Converts power consumption to gas production.

This controller couples a power network (from pandapower) and a gas network (from pandapipes) that are stored in a multinet. Requires one or multiple ‘load’ elements in the power net and as many corresponding ‘source’ elements in the gas net. It reads the power load values for given ‘load’ elements, applies the efficiency factor and unit conversions and writes the resulting gas mass flow to ‘source’ elements in the gas net. It is stored in the controller-DataFrame of the multinet (multinet.controller). It is run by run_control_multinet.run_control() or within run_time_series_multinet.run_timeseries().

Parameters
• multinet (attrdict (pandapipes.MultiNet)) – pandapipes-Mulitnet that includes the power and gas network with load and source elements

• element_index_power (int or iterable of integers) – Index of one or more load elements in the power net from which the power consumption will be read. For each load element, a corresponding source element has to be provided in element_index_gas.

• element_index_gas (int or iterable of integers) – Index of one or more source elements in the gas net to which the calculated mass flow will be written. For each source element, a corresponing el. load element has to be provided in element_index_power.

• efficiency (float) – constant efficiency factor (default: based on HHV)

• name_power_net (str) – Key name to find the power net in multinet[‘nets’]

• name_gas_net (str) – Key name to find the gas net in multinet[‘nets’]

• in_service (bool) – Indicates if the controllers are currently in_service

• order (real) – within the same level, controllers with lower order are called before controllers with numerical higher order

• level (real) – level to which the controller belongs. Low level is called before higher level. Respective run function for the nets are called at least once per level.

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

• initial_run (bool) – Whether a power and pipe flow should be run before the control step is applied or not

• kwargs (any) – optional additional controller arguments that were implemented by users

control_step(multinet)

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.

initialize_control(multinet)

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(multinet)

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.

class G2PControlMultiEnergy(multinet, element_index_power, element_index_gas, efficiency, name_power_net='power', name_gas_net='gas', element_type_power='sgen', in_service=True, order=0, level=0, drop_same_existing_ctrl=False, initial_run=True, calc_gas_from_power=False, **kwargs)

A controller to be used in a multinet. Connects power generation and gas consumption.

This controller couples a gas network (from pandapipes) and a power network (from pandapower) that are stored in a multinet. Requires one or multiple ‘sink’ elements in the gas net and as many corresponding ‘sgen’/’gen’ elements in the power net. If ‘calc_gas_from_power’ is False (default), it reads the gas mass consumption values of given ‘sink’ elements, applies the efficiency factor and unit conversions and writes the resulting power output to ‘sgen’ (default) or ‘gen’ elements in the power net. If ‘calc_gas_from_power’ is True, it reads the power output of given ‘sgen’ (default) or ‘gen’ elements, calculates the corresponding gas consumption by appling the efficiency factor and unit conversions, and writes the resulting gas consumption mass flow to the given ‘sink’ elements in the gas net. It is stored in the controller-DataFrame of the multinet (multinet.controller). It is run by run_control_multinet.run_control() or within run_time_series_multinet.run_timeseries().

Parameters
• multinet (attrdict (pandapipes.MultiNet)) – pandapipes-Mulitnet that includes the power and gas network with sgen/gen and sink elements

• element_index_power (int or iterable of integers) – Index of one or more elements in the power net from which the power generation will be read from or written to (either ‘sgen’ or ‘gen’ elements, as defined by element_type_power). For each entry, a corresponding gas sink element has to be provided in element_index_gas.

• element_index_gas (int or iterable of integers) – Index of one or more sink elements in the gas net from which the G2P units’ gas consumption (mass flow) is read from or written to. For each sink element, a corresponding sgen/gen element has to be provided in element_index_power.

• efficiency (float) – constant efficiency factor (default: based on HHV)

• name_power_net (str) – Key name to find the power net in multinet[‘nets’]

• name_gas_net (str) – Key name to find the gas net in multinet[‘nets’]

• element_type_power (str) – type of the corresponding power generation units, either ‘sgen’ or ‘gen’

• in_service (bool) – Indicates if the controllers are currently in_service

• order (int or float) – within the same level, controllers with lower order are called before controllers with numerical higher order

• level (int or float) – level to which the controller belongs. Low level is called before higher level. Respective run function for the nets are called at least once per level.

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

• initial_run (bool) – Whether a power and pipe flow should be run before the control step is applied or not

• calc_gas_from_power (bool) – (default: False) If False, the power output will be calculated on the basis of the sink’s gas consumption. If True, the gas consumption will be calculated on the basis of the generator’s power output.

• kwargs (any) – optional additional controller arguments that were implemented by users

control_step(multinet)

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.

initialize_control(multinet)

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(multinet)

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.

class GasToGasConversion(multinet, element_index_from, element_index_to, efficiency, name_gas_net_from='gas1', name_gas_net_to='gas2', in_service=True, order=0, level=0, drop_same_existing_ctrl=False, initial_run=True, **kwargs)

A controller to be used in a multinet with two gas nets that have different gases.

This controller represents a gas conversion unit (e.g. methanization or steam methane reformer) and couples two pandapipes-gas networks that are stored together in a multinet. Requires one or multiple sinks in one net (‘gas_net_from’) and as many corresponding sources in the other net (‘gas_net_to’). It reads the gas consumption values for given ‘sink’ elements in one gas net, applies the efficiency factor and writes the resulting gas mass flow to ‘source’ elements in the other gas net. It is stored in the controller-DataFrame of the multinet (multinet.controller). It is run by run_control_multinet.run_control() or within run_time_series_multinet.run_timeseries().

Parameters
• multinet (attrdict (pandapipes.MultiNet)) – pandapipes-Mulitnet that includes the gas networks that will be coupled with sink and source elements

• element_index_from (int or iterable of integers) – Index of one or more sink elements in the name_gas_net_from from which the gas consumption will be read

• element_index_to (int or iterable of integers) – Index of one or more source elements in the name_gas_net_to to which the calculated mass flow will be written

• efficiency (float) – constant efficiency factor (default: based on HHV)

• name_gas_net_from (str) – Key name to find the gas net from which gas is consumed in multinet[‘nets’]

• name_gas_net_to (str) – Key name to find the gas net in which gas is fed into in multinet[‘nets’]

• in_service (bool) – Indicates if the controllers are currently in_service

• order (int or float) – within the same level, controllers with lower order are called before controllers with numerical higher order

• level (int or float) – level to which the controller belongs. Low level is called before higher level. Respective run function for the nets are called at least once per level.

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

• initial_run (bool) – Whether a power and pipe flow should be run before the control step is applied or not

• kwargs (any) – optional additional controller arguments that were implemented by users

control_step(multinet)

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.

conversion_factor_gas1_to_gas2()

Ideal conversion with energy conservation.

initialize_control(multinet)

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(multinet)

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.

Example
>>> p2g_id_el = pandapower.create_load(net_power, bus=3, p_mw=2)
>>> p2g_id_gas = ppipes.create_source(net_gas, junction=1, mdot_kg_per_s=0)
>>> p2g_ctrl = P2GControlMultiEnergy(multinet, p2g_id_el, p2g_id_gas, efficiency=0.7)


## Run a simulation with coupling controllers¶

Usually, for single networks, the user starts a pipeflow-calculation with pandapipes.pipeflow(net). If there are controllers in the net, the pandapipes.control.run_control(net) function has to be used. However, due to the different run-functions in coupled networks (pipe flow and power flow), a special run_control function has to be used that is imported from the pandapipes.multinet module.

run_control(multinet, ctrl_variables=None, max_iter=30, **kwargs)

Main function to call a multnet with controllers Function is running control loops for the controllers specified in net.controller Runs controller until each one converged or max_iter is hit.

1. Call initialize_control() on each controller

2. Calculate an inital run (if it is enabled, i.e. setting the initial_run veriable to True)

3. Repeats the following steps in ascending order of controller_order until total convergence of all controllers for each level:

1. Evaluate individual convergence for all controllers in the level

2. Call control_step() for all controllers in the level on diverged controllers

3. Fire run function (or optionally another function like runopf or whatever you defined)

4. Call finalize_control() on each controller

Parameters
• multinet (pandapipes.Multinet) – multinet with multinet controllers, net distinct controllers and several pandapipes/pandapower nets

• ctrl_variables (dict, default: None) –

contains all relevant information and boundaries required for a successful control run. To define ctrl_variables yourself, following entries for each net are required:

• level (list): gives a list of levels to be investigated

• controller_order (list): nested list of tuples given the correct order of the different controllers within one level - run (funct, e.g. pandapower.runpp, pandapipes.pipeflow): function to be used to conduct a loadflow/pipeflow

• initial_run (boolean): Is a initial_run for a net required or not

• continue_on_divergence (boolean): What to do if loadflow/pipeflow is not converging, fires control_repair

• max_iter (int, default: 30) – number of iterations for each controller to converge

• kwargs (dict) – additional keyword arguments handed to each run function

Returns

runs an entire control loop

Return type

None

Example
>>> from  pandapipes.multinet.control.run_control_multinet import run_control
>>> run_control(multinet)


## Coupling controller for time series simulation¶

The sole purpose of the coupling controllers mentioned above is to connect generation and consumption units in different grids. They are not able to read external input data, e.g. from .csv files with profile data. Thus, for time series calculation, a ConstController is attached to the input side of the coupled elements. The ConstController reads profile data from a datasource and writes it to a dedicated element in the net (the input side of the coupled elements). Afterwards, the P2G or G2P controller is called to calculate the corresponding output values to the other net. With the following functions, matching pairs of ConstControllers and P2G/G2P controllers can be created conveniently.

Note

The order tuple (0, 1) is important to ensure that the profile values are updated before the output is calculated, based on the updated values.

coupled_p2g_const_control(multinet, element_index_power, element_index_gas, p2g_efficiency, name_power_net='power', name_gas_net='gas', profile_name=None, data_source=None, scale_factor=1.0, in_service=True, order=(0, 1), level=0, drop_same_existing_ctrl=False, matching_params=None, initial_run=False, **kwargs)

Creates a ConstController (load values) and a P2G Controller (corresponding gas mass flows).

The ConstController updates load values of a given electric load in accordance to the profile given in the datasource. The P2GControlMultiEnergy-controller couples a power network (from pandapower) and a gas network (from pandapipes). It reads the power load values that were updated by the ConstController, applies the efficiency factor and unit conversions and writes the resulting gas mass flow to ‘source’ elements in the gas net. The ConstController is stored in the power net inside the multinet. The P2GControlMultiEnergy is stored in the controller-DataFrame of the multinet (multinet.controller). Both controllers are run by run_control_multinet.run_control() or within run_time_series_multinet.run_timeseries().

Parameters
• multinet (attrdict (pandapipes.MultiNet)) – pandapipes-Mulitnet that includes the power and gas network with load and source elements

• element_index_power (int or iterable of integers) – Index of one or more load elements in the power net to which the load values from the data source will be written

• element_index_gas – Index of one or more source elements in the gas net to which the corresponding calculated mass flow will be written

• p2g_efficiency (float) – constant efficiency factor (default: based on HHV)

• name_power_net (str) – Key name to find the power net in multinet[‘nets’]

• name_gas_net (str) – Key name to find the gas net in multinet[‘nets’]

• profile_name (str) – The profile names of the elements in the data source

• data_source (object) – The data source that provides profile data

• scale_factor (real) – Scaling factor for time series input values

• in_service (bool) – Indicates if the controller is currently in_service

• order (tuple of integers) – within the same level, controllers with lower order are called before controllers with numerical higher order. Default: (0, 1) -> ConstController updates values before P2G controller calculates mass flow

• level (int or float) – level to which the controllers belong. Low level is called before higher level. Respective run function for the nets are called at least once per level.

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

• matching_params (dict) – is required to check if same controller already exists (dropping or logging)

• initial_run (bool) – Whether a power and pipe flow should be run before the control step is applied or not

• kwargs – optional additional controller arguments that were implemented by users

Returns

(ID of the ConstController, ID of P2G controller)

Return type

coupled_g2p_const_control(multinet, element_index_power, element_index_gas, g2p_efficiency=0.6, name_power_net='power', name_gas_net='gas', element_type_power='sgen', profile_name=None, data_source=None, scale_factor=1.0, power_led=False, in_service=True, order=(0, 1), level=0, drop_same_existing_ctrl=False, matching_params=None, initial_run=False, **kwargs)

Creates a ConstController (gas consumption) and a G2P Controller (corresponding power output).

The ConstController updates gas consumption values of a given sink element in accordance to the profile given in the datasource. The G2PControlMultiEnergy-controller couples a gas network (from pandapipes) and a power network (from pandapower). It reads the gas consumption values that were updated by the ConstController, applies the efficiency factor and unit conversions and writes the resulting power output to ‘sgen’ or ‘gen’ elements in the power net. The ConstController is stored in the gas net inside the multinet. The G2PControlMultiEnergy is stored in the controller-DataFrame of the multinet itself (multinet.controller). Both controllers are run by run_control_multinet.run_control() or within run_time_series_multinet.run_timeseries().

Parameters
• multinet (attrdict (pandapipes.MultiNet)) – pandapipes-Mulitnet that includes the power and gas network with load and source elements

• element_index_power (int or iterable of integers) – Index of one or more sgen/gen elements in the power net to which the power generation values from the data source will be written

• element_index_gas – Index of one or more sink elements in the gas net to which the corresponding calculated mass flow will be written

• g2p_efficiency (float) – constant efficiency factor (default: based on HHV)

• name_power_net (str) – Key name to find the power net in multinet[‘nets’]

• name_gas_net (str) – Key name to find the gas net in multinet[‘nets’]

• element_type_power (str) – type of the corresponding power generation units, either ‘sgen’ or ‘gen’

• profile_name (str) – The profile names of the elements in the data source

• data_source (object) – The data source that provides profile data

• scale_factor (real) – Scaling factor for time series input values

• in_service (bool) – Indicates if the controllers are currently in_service

• order (tuple of integers) – within the same level, controllers with lower order are called before controllers with numerical higher order. Default: (0, 1) -> ConstController updates values before G2P controller calculates power output

• level (real) – level to which the controllers belong. Low level is called before higher level. Respective run function for the nets are called at least once per level.

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

• matching_params (dict) – is required to check if same controller already exists (dropping or logging)

• initial_run (bool) – Whether a power and pipe flow should be run before the control step is applied or not

• kwargs – optional additional controller arguments that were implemented by users

Returns

(ID of the ConstController, ID of G2P controller)

Return type