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=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 / np.sqrt(3)
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: Id, *, phases: str, geometry: shapely.geometry.base.BaseGeometry | None = None, potentials: ComplexArrayLike1D | None = None, nominal_voltage: float | None = None, min_voltage_level: float | None = None, max_voltage_level: float | None = None)
Bases:
roseau.load_flow.models.core.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 attributeallowed_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.nominal_voltage – An optional nominal voltage for the bus (V). It is not used in the load flow. It is always a phase-phase voltage. It can be a float (V) or a
Quantity
of float.min_voltage_level – An optional minimal voltage of the bus (%). It is not used in the load flow. It must be a percentage of the nominal_voltage. If provided, the nominal voltage becomes mandatory. Either a float (unitless) or a
Quantity
of float.max_voltage_level – An optional maximal voltage of the bus (%). It is not used in the load flow. It must be a percentage of the nominal_voltage. If provided, the nominal voltage becomes mandatory. Either a float (unitless) or a
Quantity
of float.
- allowed_phases: Final
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 potentials: Q_[ComplexArray]
An array of initial potentials of the bus (V).
- geometry = None
- property phases: str
The phases of the bus.
- property res_potentials: Q_[ComplexArray]
The load flow result of the bus potentials (V).
- property res_voltages: Q_[ComplexArray]
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 res_voltage_levels: Q_[roseau.load_flow.typing.FloatArray] | None
The load flow result of the bus voltage levels (unitless).
- property nominal_voltage: Q_[float] | None
The phase-phase nominal voltage of the bus 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. IfTrue
, 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.
- res_voltage_unbalance() Q_[float]
Calculate the voltage unbalance on this bus according to the IEC definition.
Voltage Unbalance Factor:
\(VUF = \dfrac{|V_{\mathrm{n}}|}{|V_{\mathrm{p}}|} \times 100 \, (\%)\)
Where \(V_{\mathrm{n}}\) is the negative-sequence voltage and \(V_{\mathrm{p}}\) is the positive-sequence voltage.
- classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.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.