Bus¶

Definition¶

It represents a multiphase node in the network that other elements (loads, lines, transformers, voltage sources…) can connect to. A bus is a node where the voltage is computed during the load flow analysis.

No equation is added for a bus.

Available Results¶

The following results are available for all buses:

Result Accessor	Default Unit	Type	Description
`res_potentials`	\(V\)	complex array	The potentials of each phase of the bus
`res_voltages`	\(V\)	complex array	The phase-to-neutral voltages if the bus has a neutral, the phase-to-phase voltages otherwise
`res_voltage_levels`	\(\mathrm{pu}\)	number array	The per-unit voltage levels: (\(\sqrt{3} V_{pn} / V_\mathrm{nom}\)) if the bus has a neutral, (\(V_{pp} / V_\mathrm{nom}\)) otherwise
`res_violated`	-	boolean array	Indicates if the voltage levels violate the limits

Additionally, the following results are available for buses with a neutral:

Result Accessor	Default Unit	Type	Description
`res_voltages_pn`	\(V\)	complex array	The phase-to-neutral voltages of the bus
`res_voltage_levels_pn`	\(\mathrm{pu}\)	number array	The voltage levels of each phase of the bus (\(\sqrt{3} V_{pn} / V_\mathrm{nom}\))

And the following results are available for buses with more than one phase:

Result Accessor	Default Unit	Type	Description
`res_voltages_pp`	\(V\)	complex array	The phase-to-phase voltages of the bus
`res_voltage_levels_pp`	\(\mathrm{pu}\)	number array	The voltage levels of each phase of the bus (\(V_{pp} / V_\mathrm{nom}\))

And the following results are available for three-phase buses:

Result Accessor	Default Unit	Type	Description
`res_voltage_unbalance()`	\(\%\)	number	The voltage unbalance of the bus according to the IEC, IEEE or NEMA definition

Usage¶

A bus is identified by its unique id and must define the phases it is connected to. A bus must have all the phases of the elements connected to it.

import roseau.load_flow as rlf

bus1 = rlf.Bus(id="bus1", phases="abcn")  # A three-phase bus with a neutral
bus2 = rlf.Bus(id="bus2", phases="abc")  # A three-phase bus without a neutral
bus3 = rlf.Bus(id="bus3", phases="an")  # A single-phase bus

rlf.PowerLoad(id="load1", bus=bus1, powers=1000, phases="abcn")  # OK
rlf.PowerLoad(id="load2", bus=bus1, powers=1000, phases="abc")  # OK
rlf.PowerLoad(id="load3", bus=bus2, powers=1000, phases="ab")  # OK
rlf.PowerLoad(
    id="load4", bus=bus3, powers=1000, phases="ab"
)  # Error: bus3 does not have phase "b"

Since a bus represents a point in the network, it is possible to define the coordinates of this point:

import roseau.load_flow as rlf
from shapely import Point

bus = rlf.Bus(id="bus", phases="abc", geometry=Point(1.0, -2.5))

This information is not used by the load flow solver but could be used to generate geographical plots of the results.

Short-circuit¶

The bus element can also be used to create a short-circuit in the network to perform short-circuit analysis.

Here is an example of a simple short-circuit between two phases:

import functools as ft
import numpy as np
import roseau.load_flow as rlf

# Two buses
bus1 = rlf.Bus(id="bus1", phases="abcn")
bus2 = rlf.Bus(id="bus2", phases="abcn")

# A line
lp = rlf.LineParameters(id="lp", z_line=rlf.Q_((0.3 + 0.35j) * np.eye(4), "ohm/km"))
line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))

# A voltage source on the first bus
un = 400 / rlf.SQRT3
vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))

# The neutral of bus1 is fixed at potential 0
pref = rlf.PotentialRef(id="pref", element=bus1)

# Create a short-circuit on bus2 between phases "a" and "b"
bus2.add_short_circuit("a", "b")

# Create a network and solve a load flow
en = rlf.ElectricalNetwork.from_element(bus1)
en.solve_load_flow()

# Get the currents flowing to the line from bus1
# Notice the extremely high currents in phases "a" and "b"
en.res_lines[["current1"]].transform([np.abs, ft.partial(np.angle, deg=True)])
# |               |   ('current1', 'absolute') |   ('current1', 'angle') |
# |:--------------|---------------------------:|------------------------:|
# | ('line', 'a') |                    433.861 |                -19.3987 |
# | ('line', 'b') |                    433.861 |                160.601  |
# | ('line', 'c') |                      0     |                  0      |
# | ('line', 'n') |                      0     |                  0      |

API Reference¶

class Bus(id, *, phases, geometry=None, initial_potentials=None, nominal_voltage=None, min_voltage_level=None, max_voltage_level=None)

A multi-phase electrical bus.

Bus constructor.

Parameters:

id (Id) – A unique ID of the bus in the network buses.
phases (str) – The phases of the bus. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases.
geometry (shapely.geometry.base.BaseGeometry | None) – An optional geometry of the bus; a Geometry that represents the x-y coordinates of the bus.
initial_potentials (ComplexArrayLike1D | None) – An optional array-like of initial potentials of each phase of the bus. If given, these potentials are used as the starting point of the load flow computation. Either complex values (V) or a Quantity of complex values.
nominal_voltage (float | Q_[float] | None) – An optional nominal phase-to-phase voltage for the bus (V). It is not used in the load flow. It can be a float (V) or a Quantity of float. It must be provided if either min_voltage_level or max_voltage_level is provided.
min_voltage_level (float | Q_[float] | None) – An optional minimal voltage level of the bus (%). It is not used in the load flow. It must be a percentage of the nominal_voltage between 0 and 1. Either a float (unitless) or a Quantity of float.
max_voltage_level (float | Q_[float] | None) – An optional maximal voltage level of the bus (%). It is not used in the load flow. It must be a percentage of the nominal_voltage between 0 and 1. Either a float (unitless) or a Quantity of float.

element_type: Final = 'bus': The type of the element. It is a string like "load" or "line" etc.

property initial_potentials: Q_[ComplexArray]

An array of initial potentials of the bus (V).

Return type:: Q_[ComplexArray]

geometry = None

property nominal_voltage: Q_[float] | None

The phase-to-phase nominal voltage of the bus (V) if it is set.

Return type:: Q_[float] | None

property min_voltage_level: Q_[float] | None

The minimal voltage level of the bus if it is set.

Return type:: Q_[float] | None

property min_voltage: Q_[float] | None

The minimal voltage of the bus (V) if it is set.

Return type:: Q_[float] | None

property max_voltage_level: Q_[float] | None

The maximal voltage level of the bus if it is set.

Return type:: Q_[float] | None

property max_voltage: Q_[float] | None

The maximal voltage of the bus (V) if it is set.

Return type:: Q_[float] | None

property short_circuits: list[dict[str, Any]]

Return the list of short-circuits of this bus.

Return type:: list[dict[str, Any]]

add_short_circuit(*phases, ground=None)

Add a short-circuit by connecting multiple phases together optionally with a ground.

Parameters:

phases (str) – The phases to connect.
ground (Ground | None) – If a ground is given, the phases will also be connected to the ground.

Return type:

None

propagate_limits(force=False)

Propagate the voltage limits to galvanically connected buses.

Galvanically connected buses are buses connected to this bus through lines or switches. This ensures that these voltage limits are only applied to buses with the same voltage level. If a bus is connected to this bus through a transformer, the voltage limits are not propagated to that bus.

If this bus does not define any voltage limits, calling this method will unset the limits of the connected buses.

Parameters:: force (bool) – If False (default), an exception is raised if connected buses already have limits different from this bus. If True, the limits are propagated even if connected buses have different limits.
Return type:: None

get_connected_buses()

Get IDs of all the buses galvanically connected to this bus.

These are all the buses connected via one or more lines or switches to this bus.

Return type:: Iterator[Id]

property res_voltage_levels: Q_[FloatArray] | None

The load flow result of the bus voltage levels (p.u.).

See also

res_voltage_levels_pp: The phase-to-phase voltage levels of the bus. Raises if the bus has only one phase.
res_voltage_levels_pn: The phase-to-neutral voltage levels of the bus. Raises if the bus does not have a neutral.

Return type:: Q_[FloatArray] | None

property res_voltage_levels_pp: Q_[FloatArray] | None

The load flow result of the bus’s phase-to-phase voltage levels (p.u.).

Raises an error if the element has only one phase.

See also

res_voltage_levels: The voltage levels of the bus in the natural representation (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltage_levels_pn: The phase-to-neutral voltage levels of the bus. Raises if the bus does not have a neutral.

Return type:: Q_[FloatArray] | None

property res_voltage_levels_pn: Q_[FloatArray] | None

The load flow result of the bus’s phase-to-neutral voltage levels (p.u.).

Raises an error if the element does not have a neutral.

See also

res_voltage_levels: The voltage levels of the bus in the natural representation (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltage_levels_pp: The phase-to-phase voltage levels of the bus. Raises if the bus has only one phase.

Return type:: Q_[FloatArray] | None

property res_violated: BoolArray | None

Whether the bus has voltage limits violations.

Returns None if the bus has no voltage limits are not set.

Return type:: BoolArray | None

allowed_phases: Final

The allowed phases for a terminal element are:

P-P-P or P-P-P-N: "abc", "abcn"
P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"
P-N: "an", "bn", "cn"

property phases: str

The phases of the element.

Return type:: str

property voltage_phases: list[str]

The phases of the voltages of the element.

Return type:: list[str]

property voltage_phases_pp: list[str]

The phases of the phase-to-phase voltages of the element.

Return type:: list[str]

property voltage_phases_pn: list[str]

The phases of the phase-to-neutral voltages of the element.

Return type:: list[str]

property res_potentials: Q_[ComplexArray]

The load flow result of the element potentials (V).

Return type:: Q_[ComplexArray]

property res_voltages: Q_[ComplexArray]

The load flow result of the element voltages (V).

If the element has a neutral, the voltages are phase-to-neutral voltages for existing phases in the order [Van, Vbn, Vcn]. If the element does not have a neutral, the voltages are phase-to-phase for existing phases in the order [Vab, Vbc, Vca].

See also

res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pp: Q_[ComplexArray]

The load flow result of the element’s phase-to-phase voltages (V).

Raises an error if the element has only one phase.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pn: Q_[ComplexArray]

The load flow result of the element’s phase-to-neutral voltages (V).

Raises an error if the element does not have a neutral.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.

Return type:: Q_[ComplexArray]

res_voltage_unbalance(definition='VUF')

Calculate the voltage unbalance (VU) on this element.

Parameters:

definition (Literal['VUF', 'LVUR', 'PVUR']) –

The definition of the voltage unbalance, one of the following:

VUF: The Voltage Unbalance Factor defined by the IEC, also called the “True Definition” (default):

\(VUF = \dfrac{V_\mathrm{2}}{V_\mathrm{1}} \times 100 \, (\%)\)

Where \(V_{\mathrm{1}}\) and \(V_{\mathrm{2}}\) are the magnitudes of the positive-sequence and negative-sequence voltages, respectively.
LVUR: The Line Voltage Unbalance Rate defined by NEMA:

\(LVUR = \dfrac{\Delta V_\mathrm{Line,Max}}{\Delta V_\mathrm{Line,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Line,Mean}\) is the arithmetic mean of the line voltages and \(\Delta V_\mathrm{Line,Max}\) is the maximum deviation between the measured line voltages and \(\Delta V_\mathrm{Line,Mean}\).
PVUR: The Phase Voltage Unbalance Rate defined by IEEE:

\(PVUR = \dfrac{\Delta V_\mathrm{Phase,Max}}{\Delta V_\mathrm{Phase,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Phase,Mean}\) is the arithmetic mean of the phase voltages and \(\Delta V_\mathrm{Phase,Max}\) is the maximum deviation between the measured phase voltages and \(\Delta V_\mathrm{Phase,Mean}\).

Returns:

The voltage unbalance in percent.

Return type:

Q_[float]

is_multi_phase: Final = True: Is the object multi-phase?

property network: _N_co | None

Return the network the element belong to (if any).

Return type:: _N_co | None

id

to_dict(*, include_results=True)

Convert the element to a dictionary.

Parameters:: include_results (bool) – If True (default), the results of the load flow are included in the dictionary. If no results are available, this option is ignored.
Returns:: A JSON serializable dictionary with the element’s data.
Return type:: JsonDict

to_json(path, *, include_results=True, indent=True)

Save this element to a JSON file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

path (StrPath) – The path to the output file to write the network to.
include_results (bool) – If True (default), the results of the load flow are included in the JSON file. If no results are available, this option is ignored.
indent (bool) – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

Return type:

Path

results_to_dict(full=False)

Return the results of the element as a dictionary.

The results dictionary of an element contains the ID of the element, its phases, and the result. For example, bus.results_to_dict() returns a dictionary with the form:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]]}

Note that complex values (like potentials in the example above) are stored as list of [real part, imaginary part] so that it is JSON-serializable

Using the full argument, bus.results_to_dict(full=True) leads to the following results:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]], "voltages": [[230.0, 0.0]]}

The results dictionary of the network contains the results of all of its elements grouped by the element type. It has the form:

{
    "buses": [bus1_dict, bus2_dict, ...],
    "lines": [line1_dict, line2_dict, ...],
    "transformers": [transformer1_dict, transformer2_dict, ...],
    "switches": [switch1_dict, switch2_dict, ...],
    "loads": [load1_dict, load2_dict, ...],
    "sources": [source1_dict, source2_dict, ...],
    "grounds": [ground1_dict, ground2_dict, ...],
    "potential_refs": [p_ref1_dict, p_ref2_dict, ...],
}

where each dict is produced by the element’s results_to_dict() method.

Parameters:: full (bool) – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.
Return type:: JsonDict

results_to_json(path, *, full=False, indent=True)

Write the results of the load flow to a json file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

path (StrPath) – The path to the output file to write the results to.
full (bool) – If True, all the results are added in the resulting dictionary, including results computed from other results (such as voltages that could be computed from potentials). False by default.
indent (bool) – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

Return type:

Path