Groups

With pandapower version > 2.10.1, functionality to group network elements is available. Basically, these are helper functions to better handle and interact with multiple elements, even of different element types, such as buses, generators and lines, at once.

For first steps with group functionality, as often, it is recommended to have a look to the tutorial.

Plenty of group related functions are presented in the following.

Create and delete groups

pandapower.create_group(net, element_types, elements, name='', reference_columns=None, index=None, **kwargs)

Add a new group to net[‘group’] dataframe.

Attention

If you declare a group but forget to declare all connected elements although
you wants to (e.g. declaring lines but forgetting to mention the connected switches),
you may get problems after using drop_elements_and_group() or other functions.
There are different pandapower toolbox functions which may help you to define
'elements_dict', such as get_connecting_branches(),
get_inner_branches(), get_connecting_elements_dict().
Parameters:
netpandapowerNet

pandapower net

element_typesstr or list of strings

defines, together with ‘elements’, which net elements belong to the group

elementslist of list of indices

defines, together with ‘element_types’, which net elements belong to the group

namestr, optional

name of the group, by default “”

reference_columnsstring or list of strings, optional

If given, the elements_dict should not refer to DataFrames index but to another column. It is highly relevant that the reference_column exists in all DataFrames of the grouped elements and have the same dtype, by default None

indexint, optional

index for the dataframe net.group, by default None

EXAMPLES:
>>> create_group_from_lists(net, ["bus", "gen"], [[10, 12], [1, 2]])
>>> create_group_from_lists(net, ["bus", "gen"], [["Berlin", "Paris"], ["Wind_1", "Nuclear1"]], reference_columns="name")
pandapower.create_group_from_dict(net, elements_dict, name='', reference_column=None, index=None, **kwargs)

Wrapper function of create_group().

pandapower.drop_group(net, index)

Drops the group of given index.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the group which should be dropped

pandapower.drop_group_and_elements(net, index)

Drops all elements of the group and in net.group the group itself.

Adapt group members

pandapower.attach_to_group(net, index, element_types, elements, reference_columns=None, take_existing_reference_columns=True)

Appends the group by the elements given.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the considered group

element_typesstr or list of strings

defines, together with ‘elements’, which net elements belong to the group

elementslist of list of indices

defines, together with ‘element_types’, which net elements belong to the group

reference_columnsstring or list of strings, optional

If given, the elements_dict should not refer to DataFrames index but to another column. It is highly relevant that the reference_column exists in all DataFrames of the grouped elements and have the same dtype, by default False

take_existing_reference_columnsbool, optional

Determines the behavior if the given reference_columns does not match the reference_column existing in net.group. If True, the existing reference_column is taken for both. If False, an error is raised.

pandapower.attach_to_groups(net, index, element_types, elements, reference_columns=None)

Appends the groups by the elements given.

Parameters:
netpandapowerNet

pandapower net

indexlist[int]

index of the considered group

element_typesstr or list of strings

defines, together with ‘elements’, which net elements belong to the group

elementslist of list of indices

defines, together with ‘element_types’, which net elements belong to the group

reference_columnsstring or list of strings, optional

If given, the elements_dict should not refer to DataFrames index but to another column. It is highly relevant that the reference_column exists in all DataFrames of the grouped elements and have the same dtype, by default None

See also

attach_to_group
pandapower.detach_from_group(net, index, element_type, element_index)

Detaches elements from the group with the given group index ‘index’. No errors are raised if elements are passed to be drop from groups which alread don’t have these elements as members. A reverse function is available -> pp.group.attach_to_group().

Parameters:
netpandapowerNet

pandapower net

indexint

Index of the group from which the element should be dropped

element_typestr

The element type of which elements should be dropped from the group(s), e.g. “bus”

element_indexint or list of integers

indices of the elements which should be dropped from the group

pandapower.detach_from_groups(net, element_type, element_index, index=None)

Detaches elements from one or multiple groups, defined by ‘index’. No errors are raised if elements are passed to be dropped from groups which alread don’t have these elements as members. A reverse function is available -> pp.group.attach_to_group().

Parameters:
netpandapowerNet

pandapower net

element_typestr

The element type of which elements should be dropped from the group(s), e.g. “bus”

element_indexint or list of integers

indices of the elements which should be dropped from the group

indexint or list of integers, optional

Indices of the group(s) from which the element should be dropped. If None, the elements are dropped from all groups, by default None

Access group data and evaluate membership

pandapower.group_name(net, index)

Returns the name of the group and checks that all group rows include the same name

Parameters:
netpandapowerNet

pandapower net

indexint

index of the group

verbosebool, optional

Setting to False, accelerate the code but don’t check inconsistent names, by default True

See also

group_index

recursive function

pandapower.group_index(net, name)

Returns the index of the group named as given

Parameters:
netpandapowerNet

pandapower net

namestr

name of the requested group

See also

group_name

recursive function

pandapower.group_element_index(net, index, element_type)

Returns the indices of the elements of the group in the element table net[element_type]. This function considers net.group.reference_column.

Parameters:
netpandapowerNet

pandapower net

indexint

Index of the group

element_typestr

name of the element table to which the returned indices of the elements of the group belong to

Returns:
pd.Index

indices of the elements of the group in the element table net[element_type]

pandapower.group_row(net, index, element_type)

Returns the row which consists the data of the requested group index and element type.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the group

element_typestr

element type (defines which row of the data of the group should be returned)

Returns:
pandas.Series

data of net.group, defined by the index of the group and the element type

Raises:
KeyError

Now row exist for the requested group and element type

ValueError

Multiple rows exist for the requested group and element type

pandapower.element_associated_groups(net, element_type, element_index, return_empties=True, drop_empty_lines=True)

Returns to which groups given elements belong to.

Parameters:
netpandapowerNet

pandapower net

element_typestr

element type of the elements to be found in the groups, e.g. “gen” or “load”

element_indexstr

indices of the element table which should be found in the groups

return_emptiesbool, optional

whether entries with an empty list of assiciated groups should be returned, by default True

drop_empty_linesbool, optional

This parameter decides whether empty entries should be removed (the complete row in net.group), by default True

Returns:
dict[int, list[int]]

for each element index a list of associated group indices is returned as a dict

pandapower.isin_group(net, element_type, element_index, index=None, drop_empty_lines=True)

Returns whether elements are in group(s).

Parameters:
netpandapowerNet

pandapower net

element_typestr

element type of the elements to be found in the groups, e.g. “gen” or “load”

element_indexint or list of integers

indices of the element table which should be found in the groups

indexint or list of integers, optional

Can narrow the number of groups in which the elements are searched, by default None

drop_empty_linesbool, optional

This parameter decides whether empty entries should be removed (the complete row in net.group), by default True

Returns:
boolean or boolean numpy.array

Information whether the element are in any group

pandapower.count_group_elements(net, index)

Returns a Series concluding the number of included elements in self.elements_dict

Parameters:
netpandapowerNet

pandapower net

indexint

index of the considered group

Returns:
pd.Series

number of elements per element type existing in the group

See also

count_elements

Compare groups

pandapower.groups_equal(net, index1, index2, **kwargs)

Returns a boolean whether both group are equal.

Parameters:
netpandapowerNet

pandapower net

index1int

index of the first group to compare

index2int

index of the second group to compare

pandapower.compare_group_elements(net, index1, index2)

allow_cross_reference_column_comparison

Parameters:
netpandapowerNet

pandapower net

index1int

index of the first group to compare

index2int

index of the second group to compare

Fix group data

pandapower.check_unique_group_rows(net, raise_error=True, log_level='warning')

Checks whether all groups have unique names. raise_error decides whether duplicated names lead to error or log message.

Parameters:
netpandapowerNet

pandapower net

raise_errorbool, optional

decides whether duplicated names lead to error or log message., by default False

log_levelstr, optional

the level for logs, relevant if raise_error is False

Notes

Using different reference_columns for the same group and element_type is not supported.

pandapower.remove_not_existing_group_members(net, verbose=True)

Remove group members from net.group that do not exist in the elements tables.

Parameters:
netpandapowerNet

pandapower net

verbosebool, optional

Steers amount of logging messages, by default True

pandapower.ensure_lists_in_group_element_column(net, drop_empty_lines=True)

Ensure that all entries in net.group.element are of type list.

Parameters:
netpandapowerNet

pandapower net

drop_empty_linesbool, optional

This parameter decides whether empty entries should be removed (the complete row in net.group), by default True

pandapower.group_entries_exist_in_element_table(net, index, element_type)

Returns an array of booleans whether the entries in net.group.element exist in net[element_type], also considering reference_column

Parameters:
netpandapowerNet

pandapower net

indexint

Index of the group

element_typestr

element type which entries should be checked, e.g. “bus”

Returns:
array of booleans

Whether the entries in net.group.element exist in net[element_type]

Further group functions

pandapower.set_group_in_service(net, index)

Sets all elements of the group in service.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the considered group

pandapower.set_group_out_of_service(net, index)

Sets all elements of the group out of service.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the considered group

pandapower.set_value_to_group(net, index, value, column, replace=True, append_column=True)

Sets the same value to the column of the element tables of all elements/members of the group.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the considered group

valueint/float/object

value to be written to all group members into the element tables

columnstr

column to be manipulated

replacebool, optional

If False, value is only written to places where no value exist before (column doesn’t exist before or value is nan), by default True

append_columnbool, optional

Decides whether the column should be added to element tables where this doesn’t exist before, by default True

pandapower.group_res_p_mw(net, index)

Sums all result table values p_mw of group members.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the considered group

Examples

>>> import pandapower as pp
>>> import pandapower.networks as nw
>>> net = nw.create_cigre_network_mv(with_der="all")
>>> pp.runpp(net)
>>> gr_idx = pp.create_group(net, ["sgen", "line"], [[0, 1], [0, 1]], name="test group")
>>> net.res_line.pl_mw.loc[[0, 1]].sum() - net.res_sgen.p_mw.loc[[0, 1]].sum()  # expected value
0.057938
>>> pp.group_res_p_mw(net, gr_idx)
0.057938
pandapower.group_res_q_mvar(net, index)

Sums all result table values q_mvar of group members.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the considered group

Examples

>>> import pandapower as pp
>>> import pandapower.networks as nw
>>> net = nw.create_cigre_network_mv(with_der="all")
>>> pp.runpp(net)
>>> gr_idx = pp.create_group(net, ["sgen", "line"], [[0, 1], [0, 1]], name="test group")
>>> net.res_line.ql_mvar.loc[[0, 1]].sum() - net.res_sgen.q_mvar.loc[[0, 1]].sum()  # expected value
0.010114
>>> pp.group_res_q_mvar(net, gr_idx)
0.010114
pandapower.group_res_power_per_bus(net, index)

Returns active and reactive power consumptions of given group per bus

Parameters:
netpandapowerNet

pandapower net

indexint

_description_

Returns:
pd.DataFrame

power consumption of the group per bus (index=bus, columns=[“p_mw”, “q_mvar”])

Examples

>>> import pandapower as pp
>>> import pandapower.networks as nw
>>> net = nw.create_cigre_network_mv(with_der="all")
>>> pp.runpp(net)
>>> gr_idx = pp.create_group(net, ["sgen", "line"], [[0, 1], [0, 1]], name="test group")
>>> pp.group_res_power_per_bus(net, gr_idx)
             p_mw        q_mvar
bus
1    2.953004e+00  1.328978e+00
2   -3.641532e-14  4.618528e-14
3   -2.875066e+00 -1.318864e+00
4   -2.000000e-02  0.000000e+00
pandapower.set_group_reference_column(net, index, reference_column, element_type=None)

Set a reference_column to the group of given index. The values in net.group.element get updated.

Parameters:
netpandapowerNet

pandapower net

indexint

Index of the group

reference_columnstr

column in the elemt tables which should be used as reference to link the group members. If no column but the index should be used as the link (is the default), reference_column should be None.

element_typestr, optional

Type of element which should get a new column to reference. If None, all element types are considered, by default None

Raises:
ValueError

net[element_type][reference_column] has duplicated values.

pandapower.return_group_as_net(net, index, keep_everything_else=False, verbose=True, **kwargs)

Returns a pandapower net consisting of the members of this group.

Parameters:
netpandapowerNet

pandapower net

indexint

index of the considered group

keep_everything_elsebool, optional

Decides whether other data than element tables are kept, by default False

verbosebool, optional

Decides whether logging messages are triggered, by default True

Returns:
pandapowerNet

pandapower net, only with elements that are members of the group