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 placeholder point where we want the voltage to be computed during the load flow.

No equation is added for a bus.

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=[100, 0, 50j], phases="abcn")  # OK
rlf.PowerLoad(id="load2", bus=bus1, powers=[100, 0, 50j], phases="abc")  # OK
rlf.PowerLoad(id="load3", bus=bus2, powers=[100], phases="ab")  # OK
rlf.PowerLoad(
    id="load4", bus=bus3, powers=[100], 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 / np.sqrt(3)
voltages = rlf.Q_(un * np.exp([0, -2j * np.pi / 3, 2j * np.pi / 3]), "V")
vs = rlf.VoltageSource(id="source", bus=bus1, voltages=voltages)

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

# 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_branches[["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¶

Bases: Element

A multi-phase electrical bus.

Bus constructor.

Parameters:

id – A unique ID of the bus in the network buses.
phases – 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 – An optional geometry of the bus; a Geometry that represents the x-y coordinates of the bus.
potentials – 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.
min_voltage – An optional minimum voltage of the bus (V). It is not used in the load flow. It must be a phase-neutral voltage if the bus has a neutral, phase-phase otherwise. Either a float (V) or a Quantity of float.
max_voltage – An optional maximum voltage of the bus (V). It is not used in the load flow. It must be a phase-neutral voltage if the bus has a neutral, phase-phase otherwise. Either a float (V) or a Quantity of float.

allowed_phases: Final = frozenset({'ab', 'abc', 'abcn', 'abn', 'an', 'bc', 'bcn', 'bn', 'ca', 'can', 'cn'})

The allowed phases for a bus 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 bus.

property potentials: Quantity[ndarray[Any, dtype[complex128]]]: An array of initial potentials of the bus (V).

property res_potentials: Quantity[ndarray[Any, dtype[complex128]]]: The load flow result of the bus potentials (V).

property res_voltages: Quantity[ndarray[Any, dtype[complex128]]]

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

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

property voltage_phases: list[str]: The phases of the voltages.

property min_voltage: Quantity[float] | None: The minimum voltage of the bus (V) if it is set.

property max_voltage: Quantity[float] | None: The maximum voltage of the bus (V) if it is set.

property res_violated: bool | None

Whether the bus has voltage limits violations.

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

propagate_limits(force: bool = False) → None

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 – 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.

get_connected_buses() → Iterator[int | str]

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.

res_voltage_unbalance() → Quantity[float]

Calculate the voltage unbalance on this bus according to the IEC definition.

Voltage Unbalance Factor:

\(VUF = \frac{|V_n|}{|V_p|} * 100 (\%)\)

Where \(V_n\) is the negative-sequence voltage and \(V_p\) is the positive-sequence voltage.

classmethod from_dict(data: dict[str, Any], *, include_results: bool = True) → Self

Create an element from a dictionary created with to_dict().

Note

This method does not work on all classes that define it as some of them require additional information to be constructed. It can only be safely used on the ElectricNetwork, LineParameters and TransformerParameters classes.

Parameters:

data – The dictionary containing the element’s 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 element.

add_short_circuit(*phases: str, ground: Ground | None = None) → None

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

Parameters:

phases – The phases to connect.
ground – If a ground is given, the phases will also be connected to the ground.

property short_circuits: list[dict[str, Any]]: Return the list of short-circuits of this bus.