roseau.load_flow.network

This module defines the electrical network class.

Classes

ElectricalNetwork

Electrical network class.

Module Contents

class ElectricalNetwork(buses: MapOrSeq[Bus], branches: MapOrSeq[AbstractBranch], loads: MapOrSeq[AbstractLoad], sources: MapOrSeq[VoltageSource], grounds: MapOrSeq[Ground], potential_refs: MapOrSeq[PotentialRef], crs: str | pyproj.CRS | None = None)

Bases: roseau.load_flow.utils.JsonMixin, roseau.load_flow.utils.CatalogueMixin[roseau.load_flow.typing.JsonDict]

Electrical network class.

This class represents an electrical network, its elements, and their connections. After creating the network, the load flow solver can be run on it using the solve_load_flow() method.

Parameters:

  • buses – The buses of the network. Either a list of buses or a dictionary of buses with their IDs as keys. Buses are the nodes of the network. They connect other elements such as loads and sources. Buses can be connected together with branches.

  • branches – The branches of the network. Either a list of branches or a dictionary of branches with their IDs as keys. Branches are the elements that connect two buses together. They can be lines, transformers, or switches.

  • loads – The loads of the network. Either a list of loads or a dictionary of loads with their IDs as keys. There are three types of loads: constant power, constant current, and constant impedance.

  • sources – The sources of the network. Either a list of sources or a dictionary of sources with their IDs as keys. A network must have at least one source. Note that two sources cannot be connected with a switch.

  • grounds – The grounds of the network. Either a list of grounds or a dictionary of grounds with their IDs as keys. LV networks typically have one ground element connected to the neutral of the main source bus (secondary of the MV/LV transformer). HV networks may have one or more grounds connected to the shunt components of their lines.

  • potential_refs – The potential references of the network. Either a list of potential references or a dictionary of potential references with their IDs as keys. As the name suggests, this element defines the reference of potentials of the network. A potential reference per galvanically isolated section of the network is expected. A potential reference can be connected to a bus or to a ground.

  • crs – An optional Coordinate Reference System to use with geo data frames. If not provided, the EPSG:4326 CRS will be used.

buses

Dictionary of buses of the network indexed by their IDs. Also available as a GeoDataFrame.

Type:

dict[Id, Bus]

branches

Dictionary of branches of the network indexed by their IDs. Also available as a GeoDataFrame.

Type:

dict[Id, AbstractBranch]

loads

Dictionary of loads of the network indexed by their IDs. Also available as a DataFrame.

Type:

dict[Id, AbstractLoad]

sources

Dictionary of voltage sources of the network indexed by their IDs. Also available as a DataFrame.

Type:

dict[Id, VoltageSource]

grounds

Dictionary of grounds of the network indexed by their IDs. Also available as a DataFrame.

Type:

dict[Id, Ground]

potential_refs

Dictionary of potential references of the network indexed by their IDs. Also available as a DataFrame.

Type:

dict[Id, PotentialRef]

classmethod from_element(initial_bus: Bus) → typing_extensions.Self

Construct the network from only one element (bus) and add the others automatically.

Parameters:

initial_bus – Any bus of the network. The network is constructed from this bus and all the elements connected to it. This is usually the main source bus of the network.

Returns:

The network constructed from the given bus and all the elements connected to it.

property buses_frame: GeoDataFrame

The buses of the network as a geo dataframe.

property branches_frame: GeoDataFrame

The branches of the network as a geo dataframe.

property transformers_frame: GeoDataFrame

The transformers of the network as a geo dataframe.

This is similar to branches_frame but only contains the transformers. It has a max_power column that contains the maximum power loading (VA) of the transformers.

property lines_frame: GeoDataFrame

The lines of the network as a geo dataframe.

This is similar to branches_frame but only contains the lines. It has a max_current column that contains the maximum current loading (A) of the lines.

property switches_frame: GeoDataFrame

The switches of the network as a geo dataframe.

This is similar to branches_frame but only contains the switches.

property loads_frame: DataFrame

The loads of the network as a dataframe.

property sources_frame: DataFrame

The sources of the network as a dataframe.

property grounds_frame: DataFrame

The grounds of the network as a dataframe.

property potential_refs_frame: DataFrame

The potential references of the network as a dataframe.

property short_circuits_frame: DataFrame

The short-circuits of the network as a dataframe.

property buses_clusters: list[set[Id]]

Sets of galvanically connected buses, i.e buses connected by lines or a switches.

This can be useful to isolate parts of the network for localized analysis. For example, to study a LV subnetwork of a MV feeder.

See also

Bus.get_connected_buses(): Get the buses in the same galvanically isolated section as a certain bus.

to_graph() → Graph

Create a networkx graph from this electrical network.

The graph contains the geometries of the buses in the nodes data and the geometries and branch types in the edges data.

Note

This method requires networkx to be installed. You can install it with the "graph" extra if you are using pip: pip install "roseau-load-flow[graph]".

solve_load_flow(max_iterations: int = 20, tolerance: float = 1e-06, warm_start: bool = True, solver: Solver = _DEFAULT_SOLVER, solver_params: JsonDict | None = None) → tuple[int, float]

Solve the load flow for this network.

To get the results of the load flow for the whole network, use the res_ properties on the network (e.g. print(net.res_buses). To get the results for a specific element, use the res_ properties on the element (e.g. print(net.buses["bus1"].res_potentials).

You need to activate the license before calling this method. Alternatively you may set the environment variable ROSEAU_LOAD_FLOW_LICENSE_KEY to your license key and it will be picked automatically when calling this method. See the License page for more information.

Parameters:

  • max_iterations – The maximum number of allowed iterations.

  • tolerance – Tolerance needed for the convergence.

  • warm_start – If true (the default), the solver is initialized with the potentials of the last successful load flow result (if any). Otherwise, the potentials are reset to their initial values.

  • solver –

    The name of the solver to use for the load flow. The options are:

    • 'newton': the classical Newton-Raphson solver.

    • 'newton_goldstein': the Newton-Raphson solver with the Goldstein and Price linear search.

  • solver_params – A dictionary of parameters used by the solver. Available parameters depend on the solver chosen. For more information, see the General information page.

Returns:

The number of iterations performed and the residual error at the last iteration.

property res_buses: DataFrame

The load flow results of the network buses.

The results are returned as a dataframe with the following index:

  • bus_id: The id of the bus.

  • phase: The phase of the bus (in {'a', 'b', 'c', 'n'}).

and the following columns:

  • potential: The complex potential of the bus (in Volts) for the given phase.

property res_buses_voltages: DataFrame

The load flow results of the complex voltages of the buses (V).

The voltages are computed from the potentials of the buses. If the bus has a neutral, the voltage is the line-to-neutral voltage. Otherwise, the voltage is the line-to-line voltage. The result dataframe has a phase index that depicts this behavior.

The results are returned as a dataframe with the following index:

  • bus_id: The id of the bus.

  • phase: The phase of the bus (in {'an', 'bn', 'cn', 'ab', 'bc', 'ca'}).

and the following columns:

  • voltage: The complex voltage of the bus (in Volts) for the given phase.

  • min_voltage: The minimum voltage of the bus (in Volts).

  • max_voltage: The maximum voltage of the bus (in Volts).

property res_branches: DataFrame

The load flow results of the network branches.

The results are returned as a dataframe with the following index:

  • branch_id: The id of the branch.

  • phase: The phase of the branch (in {'a', 'b', 'c', 'n'}).

and the following columns:

  • type: The type of the branch, can be {'line', 'transformer', 'switch'}.

  • current1: The complex current of the branch (in Amps) for the given phase at the

    first bus.

  • current2: The complex current of the branch (in Amps) for the given phase at the

    second bus.

  • power1: The complex power of the branch (in VoltAmps) for the given phase at the

    first bus.

  • power2: The complex power of the branch (in VoltAmps) for the given phase at the

    second bus.

  • potential1: The complex potential of the first bus (in Volts) for the given phase.

  • potential2: The complex potential of the second bus (in Volts) for the given phase.

property res_transformers: DataFrame

The load flow results of the network transformers.

This is similar to the res_branches property but provides more information that only apply to transformers.

The results are returned as a dataframe with the following index:

  • transformer_id: The id of the transformer.

  • phase: The phase of the transformer (in {'a', 'b', 'c', 'n'}).

and the following columns:
  • current1: The complex current of the transformer (in Amps) for the given phase at the

    first bus.

  • current2: The complex current of the transformer (in Amps) for the given phase at the

    second bus.

  • power1: The complex power of the transformer (in VoltAmps) for the given phase at the

    first bus.

  • power2: The complex power of the transformer (in VoltAmps) for the given phase at the

    second bus.

  • potential1: The complex potential of the first bus (in Volts) for the given phase.

  • potential2: The complex potential of the second bus (in Volts) for the given phase.

  • max_power: The maximum power loading (in VoltAmps) of the transformer.

Note that values for missing phases are set to nan. For example, a “Dyn” transformer has the phases “abc” on the primary side and “abcn” on the secondary side, so the primary side values for current, power, and potential for phase “n” will be nan.

property res_lines: DataFrame

The load flow results of the network lines.

This is similar to the res_branches property but provides more information that only apply to lines. This includes currents and complex power losses in the series components of the lines.

The results are returned as a dataframe with the following index:

  • line_id: The id of the line.

  • phase: The phase of the line (in {'a', 'b', 'c', 'n'}).

and the following columns:
  • current1: The complex current of the line (in Amps) for the given phase at the

    first bus.

  • current2: The complex current of the line (in Amps) for the given phase at the

    second bus.

  • power1: The complex power of the line (in VoltAmps) for the given phase at the

    first bus.

  • power2: The complex power of the line (in VoltAmps) for the given phase at the

    second bus.

  • potential1: The complex potential of the first bus (in Volts) for the given phase.

  • potential2: The complex potential of the second bus (in Volts) for the given phase.

  • series_losses: The complex power losses of the line (in VoltAmps) for the given

    phase due to the series and mutual impedances.

  • series_current: The complex current in the series impedance of the line (in Amps)

    for the given phase.

Additional information can be easily computed from this dataframe. For example:

  • To get the active power losses, use the real part of the complex power losses

  • To get the total power losses, add the columns powers1 + powers2

  • To get the power losses in the shunt components of the line, subtract the series losses from the total power losses computed in the previous step: (powers1 + powers2) - series_losses

  • To get the currents in the shunt components of the line: - For the first bus, subtract the columns current1 - series_current - For the second bus, add the columns series_current + current2

property res_switches: DataFrame

The load flow results of the network switches.

This is similar to the res_branches property but only apply to switches.

The results are returned as a dataframe with the following index:

  • switch_id: The id of the switch.

  • phase: The phase of the switch (in {'a', 'b', 'c', 'n'}).

and the following columns:
  • current1: The complex current of the switch (in Amps) for the given phase at the

    first bus.

  • current2: The complex current of the switch (in Amps) for the given phase at the

    second bus.

  • power1: The complex power of the switch (in VoltAmps) for the given phase at the

    first bus.

  • power2: The complex power of the switch (in VoltAmps) for the given phase at the

    second bus.

  • potential1: The complex potential of the first bus (in Volts) for the given phase.

  • potential2: The complex potential of the second bus (in Volts) for the given phase.

property res_loads: DataFrame

The load flow results of the network loads.

The results are returned as a dataframe with the following index:

  • load_id: The id of the load.

  • phase: The phase of the load (in {'a', 'b', 'c', 'n'}).

and the following columns:

  • type: The type of the load, can be {'power', 'current', 'impedance'}.

  • current: The complex current of the load (in Amps) for the given phase.

  • power: The complex power of the load (in VoltAmps) for the given phase.

  • potential: The complex potential of the load (in Volts) for the given phase.

property res_loads_voltages: DataFrame

The load flow results of the complex voltages of the loads (V).

The results are returned as a dataframe with the following index:

  • load_id: The id of the load.

  • phase: The phase of the load (in {'an', 'bn', 'cn'} for wye loads and in

    {'ab', 'bc', 'ca'} for delta loads.).

and the following columns:

  • type: The type of the load, can be {'power', 'current', 'impedance'}.s

  • voltage: The complex voltage of the load (in Volts) for the given phase.

property res_loads_flexible_powers: DataFrame

The load flow results of the flexible powers of the “flexible” loads.

The results are returned as a dataframe with the following index:

  • load_id: The id of the load.

  • phase: The element phases of the load (in {'an', 'bn', 'cn', 'ab', 'bc', 'ca'}).

and the following columns:

  • power: The complex flexible power of the load (in VoltAmps) for the given phase.

Note that the flexible powers are the powers that flow in the load elements and not in the lines. These are only different in case of delta loads. To access the powers that flow in the lines, use the power column from the res_loads property instead.

property res_sources: DataFrame

The load flow results of the network sources.

The results are returned as a dataframe with the following index:

  • source_id: The id of the source.

  • phase: The phase of the source (in {'a', 'b', 'c', 'n'}).

and the following columns:

  • current: The complex current of the source (in Amps) for the given phase.

  • power: The complex power of the source (in VoltAmps) for the given phase.

  • potential: The complex potential of the source (in Volts) for the given phase.

property res_grounds: DataFrame

The load flow results of the network grounds.

The results are returned as a dataframe with the following index:

  • ground_id: The id of the ground.

and the following columns:

  • potential: The complex potential of the ground (in Volts).

property res_potential_refs: DataFrame

The load flow results of the network potential references.

The results are returned as a dataframe with the following index:

  • potential_ref_id: The id of the potential reference.

and the following columns:
  • current: The complex current of the potential reference (in Amps). If the load flow

    converged, this should be zero.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) → typing_extensions.Self

Construct an electrical network from a dict created with to_dict().

Parameters:

  • data – The dictionary containing the network data.

  • include_results – If True (default) and the results of the load flow are included in the dictionary, the results are also loaded into the element.

Returns:

The constructed network.

classmethod dgs_export_definition_folder_path() → Path

Returns the path to the DGS pfd file to use as “Export Definition Folder”.

classmethod from_dgs(path: StrPath) → typing_extensions.Self

Construct an electrical network from json DGS file (PowerFactory).

Only JSON format of DGS is currently supported. See the Data Exchange page for more information.

Parameters:

path – The path to the network DGS data file.

Returns:

The constructed network.

classmethod catalogue_path() → Path

Get the path to the catalogue.

classmethod catalogue_data() → JsonDict

Get the catalogue data.

classmethod from_catalogue(name: str | Pattern[str], load_point_name: str | Pattern[str]) → typing_extensions.Self

Build a network from one in the catalogue.

Parameters:

  • name – The name of the network to get from the catalogue. It can be a regular expression.

  • load_point_name – The name of the load point to get. For each network, several load points may be available. It can be a regular expression.

Returns:

The selected network

classmethod get_catalogue(name: str | Pattern[str] | None = None, load_point_name: str | Pattern[str] | None = None) → DataFrame

Read a network dictionary from the catalogue.

Parameters:

  • name – The name of the network to get from the catalogue. It can be a regular expression.

  • load_point_name – The name of the load point to get. For each network, several load points may be available. It can be a regular expression.

Returns:

The dictionary containing the network data.