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.

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

Addionally, 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 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¶

Bases: roseau.load_flow.models.terminals.AbstractTerminal[roseau.load_flow_engine.cy_engine.CyBus]

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.
initial_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.
nominal_voltage – 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 – 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 – 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'

property initial_potentials: Q_[ComplexArray]: An array of initial potentials of the bus (V).

geometry = None

property potentials: Q_[ComplexArray]: Deprecated alias to initial_potentials.

property nominal_voltage: Q_[float] | None: The phase-to-phase nominal voltage of the bus (V) if it is set.

property min_voltage_level: Q_[float] | None: The minimal voltage level of the bus if it is set.

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

property max_voltage_level: Q_[float] | None: The maximal voltage level of the bus if it is set.

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

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

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.

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[Id]

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.

property res_voltage_levels: Q_[FloatArray] | None: The load flow result of the bus voltage levels (p.u.).

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.

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.

property res_violated: BoolArray | None

Whether the bus has voltage limits violations.

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

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