roseau.load_flow
#
Welcome to the API reference of Roseau Load Flow.
For the most part, public classes and functions can be imported directly from this module.
See Package Contents below for a list of available classes and functions.
Subpackages#
Submodules#
Package Contents#
Classes#
Error codes used by Roseau Load Flow. |
|
Base class of all the branches (lines, switches and transformers) of the network. |
|
An abstract class of an electric load. |
|
An electrical bus. |
|
Control class for flexible loads. |
|
A constant current load. |
|
An abstract class of an element in an Electrical network. |
|
Flexible parameters of a flexible load. |
|
This element defines the ground. |
|
A constant impedance load. |
|
An electrical line PI model with series impedance and optional shunt admittance. |
|
A class to store the line parameters of lines |
|
A potential reference. |
|
A constant power load. |
|
This class defines the projection on the feasible circle for a flexible load. |
|
A general purpose switch branch. |
|
A generic transformer model. |
|
A class to store the parameters of the transformers. |
|
A voltage source. |
|
Electrical network class. |
|
The type of conductor. |
|
The type of the insulator for a wire. |
|
The type of a line. |
Functions#
|
Print system and python environment information. |
Attributes#
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- exception RoseauLoadFlowException(msg: str, code: RoseauLoadFlowExceptionCode, *args: object)#
Bases:
Exception
Base exception for Roseau Load Flow.
Constructor of RoseauLoadFlowException.
- Parameters:
msg – A text description that provides the reason of the exception and potential solution.
code – The code that identifies the reason of the exception.
- class RoseauLoadFlowExceptionCode(*args, **kwds)#
Bases:
enum.Enum
Error codes used by Roseau Load Flow.
- classmethod from_string(string: str | RoseauLoadFlowExceptionCode) typing_extensions.Self #
A method to convert a string into an error code enumerated type.
- Parameters:
string – The string depicted the error code. If a good element is given
- Returns:
The enumerated type value corresponding with string.
- class AbstractBranch(id: Id, bus1: Bus, bus2: Bus, *, phases1: str, phases2: str, geometry: Point | LineString | None = None, **kwargs: Any)#
Bases:
roseau.load_flow.models.core.Element
Base class of all the branches (lines, switches and transformers) of the network.
AbstractBranch constructor.
- Parameters:
id – A unique ID of the branch in the network branches.
phases1 – The phases of the first extremity of the branch.
phases2 – The phases of the second extremity of the branch.
bus1 – The bus to connect the first extremity of the branch to.
bus2 – The bus to connect the second extremity of the branch to.
geometry – The geometry of the branch.
- property res_currents: tuple[Q_[ndarray], Q_[ndarray]]#
The load flow result of the branch currents (A).
- property res_powers: tuple[Q_[ndarray], Q_[ndarray]]#
The load flow result of the branch powers (VA).
- property res_potentials: tuple[Q_[ndarray], Q_[ndarray]]#
The load flow result of the branch potentials (V).
- property res_voltages: tuple[Q_[ndarray], Q_[ndarray]]#
The load flow result of the branch voltages (V).
- class AbstractLoad(id: Id, bus: Bus, *, phases: str | None = None, **kwargs: Any)#
Bases:
roseau.load_flow.models.core.Element
,abc.ABC
An abstract class of an electric load.
- The subclasses of this class can be used to depict:
star-connected loads using a phases constructor argument containing a “n”
delta-connected loads using a phases constructor argument which doesn’t contain “n”
See also
AbstractLoad constructor.
- Parameters:
id – A unique ID of the load in the network loads.
bus – The bus to connect the load to.
phases – The phases of the load. 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
. All phases of the load, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.
- classmethod from_dict(data: JsonDict) AbstractLoad #
Create an element from a dictionary.
- class Bus(id: Id, *, phases: str, geometry: Point | None = None, potentials: Sequence[complex] | None = None, **kwargs: Any)#
Bases:
roseau.load_flow.models.core.Element
An electrical bus.
See also
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 attributeBus.allowed_phases
.geometry – An optional geometry of the bus; a
Point
that represents the x-y coordinates of the bus.potentials – An optional list of initial potentials of each phase of the bus.
ground – The ground of the bus.
- property res_voltages: Q_[ndarray]#
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]
.
- allowed_phases#
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"
- to_dict(include_geometry: bool = True) JsonDict #
Return the element information as a dictionary format.
- Parameters:
include_geometry – If False, the geometry will not be added to the result dictionary.
- 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.
- clear_short_circuits()#
Remove the short-circuits.
- class Control(type: ControlType, u_min: float, u_down: float, u_up: float, u_max: float, alpha: float = DEFAULT_ALPHA)#
Bases:
roseau.load_flow.utils.JsonMixin
Control class for flexible loads.
This class contains the information needed to formulate the control equations. This includes the control type, control limits, and other factors.
- The control for a
PowerLoad
instance can be of four possible types: "constant"
: no control is applied. In this case, a simplePowerLoad
without flexible_params could have been used instead."p_max_u_production"
: control the maximum production active power of the load (inverter) based on the voltage \(P^{\max}_{\mathrm{prod}}(U)\)."p_max_u_consumption"
: control the maximum consumption active power of the load based on the voltage \(P^{\max}_{\mathrm{cons}}(U)\)."q_u"
: control the reactive power based on the voltage \(Q(U)\).
See also
Control constructor.
- Parameters:
type –
- The type of the control:
"constant"
: no control is applied;"p_max_u_production"
: control the maximum production active power of the load (inverter) based on the voltage \(P^{\max}_{\mathrm{prod}}(U)\);"p_max_u_consumption"
: control the maximum consumption active power of the load based on the voltage \(P^{\max}_{\mathrm{cons}}(U)\);"q_u"
: control the reactive power based on the voltage \(Q(U)\).
u_min – The minimum voltage i.e. the one the control reached the maximum action.
u_down – The voltage which starts to trigger the control (lower value).
u_up – The voltage which starts to trigger the control (upper value).
u_max – The maximum voltage i.e. the one the control reached its maximum action.
alpha – An approximation factor used by the family function (soft clip). The bigger the factor is the closer the function is to the non-differentiable function.
- property alpha: float#
An approximation factor used by the family function (soft clip). The bigger the factor is the closer the function is to the non-differentiable function.
- classmethod constant() typing_extensions.Self #
Create a constant control i.e no control.
- classmethod p_max_u_production(u_up: float, u_max: float, alpha: float = DEFAULT_ALPHA) typing_extensions.Self #
Create a control of the type
"p_max_u_production"
.See also
- Parameters:
u_up – The voltage norm that triggers the control. A voltage higher than this value signals to the controller to start to reduce the production active power. On the figure, a normalised version \(U^{\mathrm{up}\,\mathrm{norm.}}\) is used.
u_max – The maximum norm voltage i.e. the one the control reached its maximum action. A voltage higher than this value signals to the controller to set the production active power to its minimal value. On the figure, a normalised version \(U^{\max\,\mathrm{norm.}}\) is used.
alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.
- Returns:
The
"p_max_u_production"
control using the provided parameters.
- classmethod p_max_u_consumption(u_min: float, u_down: float, alpha: float = DEFAULT_ALPHA) typing_extensions.Self #
Create a control of the type
"p_max_u_consumption"
.See also
- Parameters:
u_min – The minimum voltage norm i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the consumption active power to its minimal value. On the figure, a normalised version \(U^{\min\,\mathrm{norm.}}\) is used.
u_down – The voltage norm that triggers the control. A voltage lower than this value signals to the controller to start to reduce the consumption active power. On the figure, a normalised version \(U^{\mathrm{down}\,\mathrm{norm.}}\) is used.
alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.
- Returns:
The
"p_max_u_consumption"
control using the provided parameters.
- classmethod q_u(u_min: float, u_down: float, u_up: float, u_max: float, alpha: float = DEFAULT_ALPHA) typing_extensions.Self #
Create a control of the type
"q_u"
.See also
- Parameters:
u_min – The minimum voltage norm i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the reactive power to its maximal capacitive value. On the figure, a normalised version \(U^{\min\,\mathrm{norm.}}\) is used.
u_down – The voltage that triggers the capacitive reactive power control. A voltage lower than this value signals to the controller to start to increase the capacitive reactive power. On the figure, a normalised version \(U^{\mathrm{down}\,\mathrm{norm.}}\) is used.
u_up – The voltage that triggers the inductive reactive power control. A voltage higher than this value signals to the controller to start to increase the inductive reactive power. On the figure, a normalised version \(U^{\mathrm{up}\,\mathrm{norm.}}\) is used.
u_max – The minimum voltage i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the reactive power to its maximal inductive value. On the figure, a normalised version \(U^{\max\,\mathrm{norm.}}\) is used.
alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.
- Returns:
The
"q_u"
control using the provided parameters.
- The control for a
- class CurrentLoad(id: Id, bus: Bus, *, currents: Sequence[complex], phases: str | None = None, **kwargs: Any)#
Bases:
AbstractLoad
A constant current load.
See also
CurrentLoad constructor.
- Parameters:
id – A unique ID of the load in the network loads.
bus – The bus to connect the load to.
currents – List of currents for each phase (Amps).
phases – The phases of the load. 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
. All phases of the load, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.
- class Element(id: Id, **kwargs: Any)#
Bases:
abc.ABC
,roseau.load_flow.utils.Identifiable
,roseau.load_flow.utils.JsonMixin
An abstract class of an element in an Electrical network.
Element constructor.
- Parameters:
id – A unique ID of the element in the network. Two elements of the same type cannot have the same ID.
- property network: ElectricalNetwork | None#
Return the network the element belong to (if any).
- class FlexibleParameter(control_p: Control, control_q: Control, projection: Projection, s_max: float)#
Bases:
roseau.load_flow.utils.JsonMixin
Flexible parameters of a flexible load.
This class encapsulate single-phase flexibility information of a flexible load:
The active power
Control
to apply;The reactive power
Control
to apply;The
Projection
to use when dealing with voltage violations;- The apparent power of the flexible load (VA). This is the maximum power the load can consume/produce. It is
the radius of the feasible circle used by the projection
For multi-phase loads, you need to use a FlexibleParameter instance per phase.
See also
FlexibleParameter constructor.
- Parameters:
control_p – The control to apply on the active power.
control_q – The control to apply on the reactive power.
projection – The projection to use to have a feasible result.
s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.
- property s_max: Q_[float]#
The apparent power of the flexible load (VA). It is the radius of the feasible circle.
- classmethod constant() typing_extensions.Self #
Build flexible parameters for a constant control with a Euclidean projection.
- Returns:
A constant control i.e. no control at all. It is an equivalent of the constant power load.
- classmethod p_max_u_production(u_up: float, u_max: float, s_max: float, alpha_control: float = Control.DEFAULT_ALPHA, alpha_proj: float = Projection.DEFAULT_ALPHA, epsilon_proj: float = Projection.DEFAULT_EPSILON) typing_extensions.Self #
Build flexible parameters for production
P(U)
control with a Euclidean projection.See also
- Parameters:
u_up – The voltage upper limit value that triggers the control. If the voltage is greater than this value, the production active power is reduced.
u_max – The maximum voltage i.e. the one the control reached its maximum action. If the voltage is greater than this value, the production active power is reduced to zero.
s_max – The apparent power of the flexible inverter (VA). It is the radius of the feasible circle.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.
alpha_proj – This value is used to make soft sign function and to build a soft projection function (see the diagram above).
epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.
- Returns:
A flexible parameter which performs “p_max_u_production” control.
- classmethod p_max_u_consumption(u_min: float, u_down: float, s_max: float, alpha_control: float = Control.DEFAULT_ALPHA, alpha_proj: float = Projection.DEFAULT_ALPHA, epsilon_proj: float = Projection.DEFAULT_EPSILON) typing_extensions.Self #
Build flexible parameters for consumption
P(U)
control with a Euclidean projection.See also
- Parameters:
u_min – The minimum voltage i.e. the one the control reached the maximum action.
u_down – The voltage which starts to trigger the control (lower value).
s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.
alpha_proj – This value is used to make soft sign function and to build a soft projection function.
epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.
- Returns:
A flexible parameter which performs “p_max_u_consumption” control.
- classmethod q_u(u_min: float, u_down: float, u_up: float, u_max: float, s_max: float, alpha_control: float = Control.DEFAULT_ALPHA, alpha_proj: float = Projection.DEFAULT_ALPHA, epsilon_proj: float = Projection.DEFAULT_EPSILON) typing_extensions.Self #
Build flexible parameters for
Q(U)
control with a Euclidean projection.See also
- Parameters:
u_min – The minimum voltage i.e. the one the control reached the maximum action.
u_down – The voltage which starts to trigger the control (lower value).
u_up – The voltage which starts to trigger the control (upper value).
u_max – The maximum voltage i.e. the one the control reached its maximum action.
s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.
alpha_proj – This value is used to make soft sign function and to build a soft projection function.
epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.
- Returns:
A flexible parameter which performs “q_u” control.
- classmethod pq_u_production(up_up: float, up_max: float, uq_min: float, uq_down: float, uq_up: float, uq_max: float, s_max: float, alpha_control=Control.DEFAULT_ALPHA, alpha_proj=Projection.DEFAULT_ALPHA, epsilon_proj=Projection.DEFAULT_EPSILON) typing_extensions.Self #
Build flexible parameters for production
P(U)
control andQ(U)
control with a Euclidean projection.- Parameters:
up_up – The voltage which starts to trigger the control on the production (upper value).
up_max – The maximum voltage i.e. the one the control (of production) reached its maximum action.
uq_min – The minimum voltage i.e. the one the control reached the maximum action (reactive power control)
uq_down – The voltage which starts to trigger the reactive power control (lower value).
uq_up – The voltage which starts to trigger the reactive power control (upper value).
uq_max – The maximum voltage i.e. the one the reactive power control reached its maximum action.
s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.
alpha_proj – This value is used to make soft sign function and to build a soft projection function.
epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.
- Returns:
A flexible parameter which performs “p_max_u_production” control and a “q_u” control.
See also
p_max_u_production()
andq_u()
for more details.
- classmethod pq_u_consumption(up_min: float, up_down: float, uq_min: float, uq_down: float, uq_up: float, uq_max: float, s_max: float, alpha_control: float = Control.DEFAULT_ALPHA, alpha_proj: float = Projection.DEFAULT_ALPHA, epsilon_proj: float = Projection.DEFAULT_EPSILON) typing_extensions.Self #
Build flexible parameters for consumption
P(U)
control andQ(U)
control with a Euclidean projection.- Parameters:
up_min – The minimum voltage i.e. the one the active power control reached the maximum action.
up_down – The voltage which starts to trigger the active power control (lower value).
uq_min – The minimum voltage i.e. the one the control reached the maximum action (reactive power control)
uq_down – The voltage which starts to trigger the reactive power control (lower value).
uq_up – The voltage which starts to trigger the reactive power control (upper value).
uq_max – The maximum voltage i.e. the one the reactive power control reached its maximum action.
s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.
alpha_proj – This value is used to make soft sign function and to build a soft projection function.
epsilon_proj – This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.
- Returns:
A flexible parameter which performs “p_max_u_consumption” control and “q_u” control.
See also
p_max_u_consumption()
andq_u()
for more details.
- class Ground(id: Id, **kwargs: Any)#
Bases:
roseau.load_flow.models.core.Element
This element defines the ground.
Only buses and lines that have shunt components can be connected to a ground.
Connecting to a bus:
To connect a ground to a bus on a given phase, use the
Ground.connect()
method. This method lets you specify the bus to connect to as well as the phase of the connection. If the bus has a neutral and the phase is not specified, the ground will be connected to the neutral, otherwise, an error will be raised because the phase is needed.Connecting to a line with shunt components:
To connect a ground to a line with shunt components, pass the ground object to the
Line
constructor. Note that the ground connection is mandatory for shunt lines.
See also
Ground constructor.
- Parameters:
id – A unique ID of the ground in the network grounds.
- property connected_buses: dict[Id, str]#
The bus ID and phase of the buses connected to this ground.
- connect(bus: Bus, phase: str = 'n') None #
Connect the ground to a bus on the given phase.
- Parameters:
bus – The bus to connect to.
phase – The phase of the connection. It must be one of
{"a", "b", "c", "n"}
and must be present in the bus phases. Defaults to"n"
.
- class ImpedanceLoad(id: Id, bus: Bus, *, impedances: Sequence[complex], phases: str | None = None, **kwargs: Any)#
Bases:
AbstractLoad
A constant impedance load.
See also
ImpedanceLoad constructor.
- Parameters:
id – A unique ID of the load in the network loads.
bus – The bus to connect the load to.
impedances – List of impedances for each phase (Ohms).
phases – The phases of the load. 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
. All phases of the load, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.
- class Line(id: Id, bus1: Bus, bus2: Bus, *, parameters: LineParameters, length: float, phases: str | None = None, ground: Ground | None = None, geometry: LineString | None = None, **kwargs: Any)#
Bases:
roseau.load_flow.models.branches.AbstractBranch
An electrical line PI model with series impedance and optional shunt admittance.
See also
Line constructor.
- Parameters:
id – A unique ID of the line in the network branches.
bus1 – The first bus (aka “from_bus”) to connect to the line.
bus2 – The second bus (aka “to_bus”) to connect to the line.
parameters – The parameters of the line, an instance of
LineParameters
.length – The length of the line in km.
phases – The phases of the line. 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
. All phases of the line must be present in the phases of both connected buses. By default, the phases common to both buses are used.ground – The ground element attached to the line if it has shunt admittance.
geometry – The geometry of the line i.e. the linestring.
- property parameters: LineParameters#
The parameters of the line.
- property res_series_power_losses: Q_[ndarray]#
Get the power losses in the series elements of the line (VA).
- property res_shunt_currents: tuple[Q_[ndarray], Q_[ndarray]]#
Get the currents in the shunt elements of the line (A).
- property res_shunt_power_losses: Q_[ndarray]#
Get the power losses in the shunt elements of the line (VA).
- allowed_phases#
The allowed phases for a line are:
P-P-P or P-P-P-N:
"abc"
,"abcn"
P-P or P-P-N:
"ab"
,"bc"
,"ca"
,"abn"
,"bcn"
,"can"
P or P-N:
"a"
,"b"
,"c"
,"an"
,"bn"
,"cn"
N:
"n"
- class LineParameters(id: Id, z_line: ndarray, y_shunt: ndarray | None = None)#
Bases:
roseau.load_flow.utils.Identifiable
,roseau.load_flow.utils.JsonMixin
A class to store the line parameters of lines
See also
LineParameters constructor.
- Parameters:
id – A unique ID of the line parameters, typically its canonical name.
z_line – The Z matrix of the line (Ohm/km).
y_shunt – The Y matrix of the line (Siemens/km). This field is optional if the line has no shunt part.
- classmethod from_sym(id: Id, z0: complex, z1: complex, y0: complex, y1: complex, zn: complex | None = None, xpn: float | None = None, bn: float | None = None, bpn: float | None = None) typing_extensions.Self #
Create line parameters from a symmetric model.
- Parameters:
id – A unique ID of the line parameters, typically its canonical name.
z0 – Impedance - zero sequence - \(r_0+x_0\cdot j\) (ohms/km)
z1 – Impedance - direct sequence - \(r_1+x_1\cdot j\) (ohms/km)
y0 – Admittance - zero sequence - \(g_0+b_0\cdot j\) (Siemens/km)
y1 – Conductance - direct sequence - \(g_1+b_1\cdot j\) (Siemens/km)
zn – Neutral impedance - \(r_{\mathrm{n}}+x_{\mathrm{n}}\cdot j\) (ohms/km)
xpn – Phase to neutral reactance (ohms/km)
bn – Neutral susceptance (siemens/km)
bpn – Phase to neutral susceptance (siemens/km)
- Returns:
The created line parameters.
Notes
As explained in the Line parameters alternative constructor documentation, the model may be “degraded” if the computed impedance matrix is not invertible.
- classmethod from_geometry(id: Id, line_type: LineType, conductor_type: ConductorType, insulator_type: InsulatorType, section: float, section_neutral: float, height: float, external_diameter: float) typing_extensions.Self #
Create line parameters from its geometry.
- Parameters:
id – The id of the line parameters type.
line_type – Overhead or underground.
conductor_type – Type of the conductor
insulator_type – Type of insulator.
section – Surface of the phases (mm²).
section_neutral – Surface of the neutral (mm²).
height – Height of the line (m).
external_diameter – External diameter of the wire (m).
- Returns:
The created line parameters.
- classmethod from_name_lv(name: str, section_neutral: float | None = None, height: float | None = None, external_diameter: float | None = None) typing_extensions.Self #
Method to get the electrical parameters of a LV line from its canonical name. Some hypothesis will be made: the section of the neutral is the same as the other sections, the height and external diameter are pre-defined, and the insulator is PVC.
- Parameters:
name – The name of the line the parameters must be computed. E.g. “U_AL_150”.
section_neutral – Surface of the neutral (mm²). If None it will be the same as the section of the other phases.
height – Height of the line (m). If None a default value will be used.
external_diameter – External diameter of the wire (mm). If None a default value will be used.
- Returns:
The corresponding line parameters.
- classmethod from_name_mv(name: str) typing_extensions.Self #
Method to get the electrical parameters of a MV line from its canonical name.
- Parameters:
name – The name of the line the parameters must be computed. E.g. “U_AL_150”.
- Returns:
The corresponding line parameters.
- classmethod from_dict(data: JsonDict) typing_extensions.Self #
Line parameters constructor from dict.
- Parameters:
data – The dictionary data of the line parameters.
- Returns:
The created line parameters.
- class PotentialRef(id: Id, element: Bus | Ground, *, phase: str | None = None, **kwargs: Any)#
Bases:
roseau.load_flow.models.core.Element
A potential reference.
This element will set the reference of the potentials in a network. Only one potential reference per galvanically isolated section of the network can be set. The potential reference can be set on any bus or ground elements. If set on a bus with no neutral and without specifying the phase, the reference will be set as
Va + Vb + Vc = 0
. For other buses, the default isVn = 0
.PotentialRef constructor.
- Parameters:
id – A unique ID of the potential reference in the network references.
element – The bus or ground element to set as a potential reference.
phase – The phase of the bus to set as a potential reference. Cannot be used with a ground. If the element passed is a bus and the phase is not given, the neutral will be used if the bus has a neutral otherwise the equation
Va + Vb + Vc = 0
of the bus sets the potential reference.
- property res_current: Q_[complex]#
The sum of the currents (A) of the connection associated to the potential reference.
This sum should be equal to 0 after the load flow.
- class PowerLoad(id: Id, bus: Bus, *, powers: Sequence[complex], phases: str | None = None, flexible_params: list[FlexibleParameter] | None = None, **kwargs: Any)#
Bases:
AbstractLoad
A constant power load.
See also
PowerLoad constructor.
- Parameters:
id – A unique ID of the load in the network loads.
bus – The bus to connect the load to.
powers – List of power for each phase (VA).
phases – The phases of the load. 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
. All phases of the load, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.flexible_params – A list of
FlexibleParameters
object, one for each phase. When provided, the load is considered as flexible (or controllable) and the parameters are used to compute the flexible power of the load.
- class Projection(type: ProjectionType, alpha: float = DEFAULT_ALPHA, epsilon: float = DEFAULT_EPSILON)#
Bases:
roseau.load_flow.utils.JsonMixin
This class defines the projection on the feasible circle for a flexible load.
- The three possible projection types are:
"euclidean"
: for an Euclidean projection on the feasible space;"keep_p"
: for maintaining a constant P;"keep_q"
: for maintaining a constant Q.
See also
Projection constructor.
- Parameters:
type –
- The type of the projection. It can be:
"euclidean"
: for an Euclidean projection on the feasible space;"keep_p"
: for maintaining a constant P;"keep_q"
: for maintaining a constant Q.
alpha – This value is used to make soft sign function and to build a soft projection function.
epsilon – This value is used to make a smooth sqrt function.
- property alpha: float#
This value is used to make soft sign function and to build a soft projection function.
- property epsilon: float#
This value is used to make a smooth sqrt function. It is only used in the Euclidean projection.
- class Switch(id: Id, bus1: Bus, bus2: Bus, *, phases: str | None = None, geometry: Point | None = None, **kwargs: Any)#
Bases:
roseau.load_flow.models.branches.AbstractBranch
A general purpose switch branch.
See also
Switch constructor.
- Parameters:
id – A unique ID of the switch in the network branches.
bus1 – Bus to connect to the switch.
bus2 – Bus to connect to the switch.
phases – The phases of the switch. 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
. All phases of the switch must be present in the phases of both connected buses. By default, the phases common to both buses are used.geometry – The geometry of the switch.
- allowed_phases#
The allowed phases for a switch are:
P-P-P or P-P-P-N:
"abc"
,"abcn"
P-P or P-P-N:
"ab"
,"bc"
,"ca"
,"abn"
,"bcn"
,"can"
P or P-N:
"a"
,"b"
,"c"
,"an"
,"bn"
,"cn"
N:
"n"
- class Transformer(id: Id, bus1: Bus, bus2: Bus, *, parameters: TransformerParameters, tap: float = 1.0, phases1: str | None = None, phases2: str | None = None, geometry: Point | None = None, **kwargs: Any)#
Bases:
roseau.load_flow.models.branches.AbstractBranch
A generic transformer model.
The model parameters are defined in the
parameters
.See also
Transformer constructor.
- Parameters:
id – A unique ID of the transformer in the network branches.
bus1 – Bus to connect the first extremity of the transformer.
bus2 – Bus to connect the first extremity of the transformer.
tap – The tap of the transformer, for example 1.02.
parameters – The parameters of the transformer.
phases1 – The phases of the first extremity of the transformer. A string like
"abc"
or"abcn"
etc. The order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases must be present in the connected bus. By default determined from the transformer type.phases2 – The phases of the second extremity of the transformer. See
phases1
.geometry – The geometry of the transformer.
- property parameters: TransformerParameters#
The parameters of the transformer.
- allowed_phases#
The allowed phases for a transformer are:
P-P-P or P-P-P-N:
"abc"
,"abcn"
(three-phase transformer)P-P or P-N:
"ab"
,"bc"
,"ca"
,"an"
,"bn"
,"cn"
(single-phase transformer or primary of center-tapped transformer)P-P-N:
"abn"
,"bcn"
,"can"
(secondary of center-tapped transformer)
- class TransformerParameters(id: Id, type: str, uhv: float, ulv: float, sn: float, p0: float, i0: float, psc: float, vsc: float)#
Bases:
roseau.load_flow.utils.Identifiable
,roseau.load_flow.utils.JsonMixin
,roseau.load_flow.utils.CatalogueMixin
[pandas.DataFrame
]A class to store the parameters of the transformers.
See also
TransformerParameters constructor.
- Parameters:
id – A unique ID of the transformer parameters, typically its canonical name.
type – The type of transformer parameters. It can be “single” for single-phase transformers, “center” for center-tapped transformers, or the name of the windings such as “Dyn11” for three-phase transformers. Allowed windings are “D” for delta, “Y” for wye (star), and “Z” for zigzag.
uhv – Phase-to-phase nominal voltages of the high voltages side (V)
ulv – Phase-to-phase nominal voltages of the low voltages side (V)
sn – The nominal power of the transformer (VA)
p0 – Losses during off-load test (W)
i0 – Current during off-load test (%)
psc – Losses during short-circuit test (W)
vsc – Voltages on LV side during short-circuit test (%)
- to_zyk() tuple[Q_[complex], Q_[complex], Q_[float], float] #
Compute the transformer parameters
z2
,ym
,k
andorientation
mandatory for some models.- Where:
z2
: The series impedance of the transformer (Ohms).ym
: The magnetizing admittance of the transformer (Siemens).k
: The transformation ratio.orientation
: 1 for direct winding, -1 for reverse winding.
- Returns:
The parameters (
z2
,ym
,k
,orientation
).
- to_dict(include_geometry: bool = True) JsonDict #
Return the element information as a dictionary format.
- Parameters:
include_geometry – If False, the geometry will not be added to the result dictionary.
- classmethod from_catalogue(id: str | Pattern[str] | None = None, manufacturer: str | Pattern[str] | None = None, range: str | Pattern[str] | None = None, efficiency: str | Pattern[str] | None = None, type: str | Pattern[str] | None = None, sn: float | None = None, uhv: float | None = None, ulv: float | None = None) typing_extensions.Self #
Build a transformer parameters from one in the catalogue.
- Parameters:
id – The id of the transformer to get from the catalogue. It can be a regular expression.
manufacturer – The name of the manufacturer to get. It can be a regular expression.
range – The name of the product range to get. It can be a regular expression.
efficiency – The efficiency of the transformer get. It can be a regular expression.
type – The type of the transformer to get. It can be a regular expression.
sn – The nominal power of the transformer to get.
uhv – The primary side voltage of the transformer to get.
ulv – The secondary side voltage of the transformer to get.
- Returns:
The selected transformer. If several transformers fitting the filters are in the catalogue, an error is raised.
- classmethod print_catalogue(id: str | Pattern[str] | None = None, manufacturer: str | Pattern[str] | None = None, range: str | Pattern[str] | None = None, efficiency: str | Pattern[str] | None = None, type: str | Pattern[str] | None = None, sn: float | None = None, uhv: float | None = None, ulv: float | None = None) None #
Print the catalogue of available transformers.
- Parameters:
id – An optional manufacturer to filter the output. It can be a regular expression.
manufacturer – An optional manufacturer to filter the output. It can be a regular expression.
range – An optional product range to filter the output. It can be a regular expression.
efficiency – An optional efficiency to filter the output. It can be a regular expression.
type – An optional type of the transformer. It can be a regular expression.
sn – An optional nominal power of the transformer to filter the output.
uhv – An optional primary side voltage to filter the output.
ulv – An optional secondary side voltage to filter the output.
- class VoltageSource(id: Id, bus: Bus, *, voltages: Sequence[complex], phases: str | None = None, **kwargs: Any)#
Bases:
roseau.load_flow.models.core.Element
A voltage source.
See also
Voltage source constructor.
- Parameters:
id – A unique ID of the voltage source in the network sources.
bus – The bus of the voltage source.
voltages – The voltages of the source. They will be fixed on the connected bus. If the source has a neutral connection, the voltages are the phase-to-neutral voltages, otherwise they are the phase-to-phase voltages.
phases – The phases of the source. 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
. All phases of the source, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.
- class ElectricalNetwork(buses: list[Bus] | dict[Id, Bus], branches: list[AbstractBranch] | dict[Id, AbstractBranch], loads: list[AbstractLoad] | dict[Id, AbstractLoad], sources: list[VoltageSource] | dict[Id, VoltageSource], grounds: list[Ground] | dict[Id, Ground], potential_refs: list[PotentialRef] | dict[Id, PotentialRef], **kwargs)#
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.
- DEFAULT_TOLERANCE#
The default tolerance needed for the convergence of the load flow solver. At each iteration, the solver computes the residuals of the equations of the problem. When the maximum of the absolute values of the residuals vector is lower than the provided tolerance, the solver stops. Default is 1e-6.
- Type:
- DEFAULT_MAX_ITERATIONS#
Maximum number of iterations to perform the load flow analysis. The solver stops when this number of iterations is reached. Default is 20.
- Type:
- buses#
Dictionary of buses of the network indexed by their IDs. Also available as a
GeoDataFrame
.
- branches#
Dictionary of branches of the network indexed by their IDs. Also available as a
GeoDataFrame
.- Type:
- loads#
Dictionary of loads of the network indexed by their IDs. Also available as a
DataFrame
.- Type:
- sources#
Dictionary of voltage sources of the network indexed by their IDs. Also available as a
DataFrame
.- Type:
- potential_refs#
Dictionary of potential references of the network indexed by their IDs. Also available as a
DataFrame
.- Type:
- res_info#
Dictionary containing solver information on the last run of the load flow analysis. Empty if the load flow analysis has not been run yet. Example:
{ "solver": "newton", "tolerance": 1e-06, "max_iterations": 20, "warm_start": True, "status": "success", "iterations": 2, "residual": 1.8595619621919468e-07 }
- Type:
- 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 potential_refs_frame: DataFrame#
The
potential references
of the network as a dataframe.
- 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.
- 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:
- 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_lines: DataFrame#
The load flow results of the 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 columnsseries_current + current2
- 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:
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.).
- phase: The phase of the load (in
- and the following columns:
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 theres_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_element(initial_bus: Bus) typing_extensions.Self #
Construct the network from only one element and add the others automatically.
- Parameters:
initial_bus – Any bus of the network.
- solve_load_flow(auth: tuple[str, str] | HTTPBasicAuth, base_url: str = DEFAULT_BASE_URL, max_iterations: int = DEFAULT_MAX_ITERATIONS, tolerance: float = DEFAULT_TOLERANCE, warm_start: bool = DEFAULT_WARM_START, solver: Solver = DEFAULT_SOLVER, solver_params: JsonDict | None = None) int #
Solve the load flow for this network (Requires internet access).
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)
.- Parameters:
auth – The login and password for the roseau load flow api.
base_url – The base url to request the load flow solver.
max_iterations – The maximum number of allowed iterations.
tolerance – Tolerance needed for the convergence.
warm_start – If true, initialize the solver with the potentials of the last successful load flow result (if any).
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 Solvers page.
- Returns:
The number of iterations taken.
- clear_short_circuits()#
Remove the short-circuits of all the buses.
- classmethod from_dict(data: JsonDict) typing_extensions.Self #
Construct an electrical network from a dict created with
to_dict()
.- Parameters:
data – The dictionary containing the network data.
- Returns:
The constructed network.
- to_dict(include_geometry: bool = True) JsonDict #
Convert the electrical network to a dictionary.
- Parameters:
include_geometry – If False, the geometry will not be added to the network dictionary.
- results_from_dict(data: JsonDict) None #
Load the results of a load flow from a dict created by
results_to_dict()
.The results are stored in the network elements.
- Parameters:
data – The dictionary containing the results as returned by the solver.
- classmethod from_dgs(path: StrPath) typing_extensions.Self #
Construct an electrical network from json DGS file (PowerFactory).
- Parameters:
path – The path to the network DGS data file.
- Returns:
The constructed network.
- 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 print_catalogue(name: str | Pattern[str] | None = None, load_point_name: str | Pattern[str] | None = None) None #
Print the catalogue of available networks.
- Parameters:
name – The name of the networks to display. It can be a regular expression. For instance, name=”lv” will match all the network name starting with “lv” (ignoring case).
load_point_name – Only networks having a load point matching this string or regular expression will be displayed.
- class ConductorType(*args, **kwds)#
Bases:
enum.Enum
The type of conductor.
- AL#
The conductor is in Aluminium.
- CU#
The conductor is in Copper.
- AM#
The conductor is in Almélec.
- AA#
The conductor is in Alu-Acier.
- LA#
The conductor is in Almélec-Acier.
- class InsulatorType(*args, **kwds)#
Bases:
enum.Enum
The type of the insulator for a wire.
- UNKNOWN#
The insulator of the conductor is made with unknown material.
- HDPE#
The insulator of the conductor is made with High-Density PolyEthylene.
- LDPE#
The insulator of the conductor is made with Low-Density PolyEthylene.
- PEX#
The insulator of the conductor is made with Cross-linked polyethylene.
- EPR#
The insulator of the conductor is made with Ethylene-Propylene Rubber.
- PVC#
The insulator of the conductor is made with PolyVinyl Chloride.
- class LineType(*args, **kwds)#
Bases:
enum.Enum
The type of a line.
- OVERHEAD#
The line is an overhead line.
- UNDERGROUND#
The line is an underground line.
- TWISTED#
The line is a twisted line.