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¶
Exceptions¶
Base exception for Roseau Load Flow. 
Classes¶
Error codes used by Roseau Load Flow. 

A class to access the main data of the License. 

Base class of all the branches (lines, switches and transformers) of the network. 

An abstract class of an electric load. 

A multiphase 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. 

Parameters that define electrical models 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. 

Parameters that define electrical models of transformers. 

A voltage source. 

Electrical network class. 

The type of the material of the conductor. 

The type of the insulator for a wire. 

The type of a line. 
Functions¶

Activate a license in the current process. 

Deactivate the currently active license. 

Get the currently active license or 

Print system and python environment information. 
Package Contents¶
 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¶
Bases:
roseau.load_flow._compat.StrEnum
Error codes used by Roseau Load Flow.
Initialize self. See help(type(self)) for accurate signature.
 class License(cy_license: roseau.load_flow_engine.cy_engine.CyLicense)¶
A class to access the main data of the License.
Constructor for a License
 Parameters:
cy_license – The Cython license object
 property expiry_datetime: datetime  None¶
The expiry date of the license or
None
if the license has no expiry date.
 activate_license(key: str  None = None) None ¶
Activate a license in the current process.
 Parameters:
key – The key of the license to activate. If
None
is provided (default), the environment variable ROSEAU_LOAD_FLOW_LICENSE_KEY is used. If this variable is not set, an error is raised.
 class AbstractBranch(id: Id, bus1: roseau.load_flow.models.buses.Bus, bus2: roseau.load_flow.models.buses.Bus, *, phases1: str, phases2: str, geometry: shapely.geometry.base.BaseGeometry  None = None)¶
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 bus1: roseau.load_flow.models.buses.Bus¶
The first bus of the branch.
 property bus2: roseau.load_flow.models.buses.Bus¶
The second bus of the branch.
 property res_currents: tuple[Q_[ComplexArray], Q_[ComplexArray]]¶
The load flow result of the branch currents (A).
 property res_powers: tuple[Q_[ComplexArray], Q_[ComplexArray]]¶
The load flow result of the branch powers (VA).
 property res_potentials: tuple[Q_[ComplexArray], Q_[ComplexArray]]¶
The load flow result of the branch potentials (V).
 property res_voltages: tuple[Q_[ComplexArray], Q_[ComplexArray]]¶
The load flow result of the branch voltages (V).
 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.
 class AbstractLoad(id: Id, bus: roseau.load_flow.models.buses.Bus, *, phases: str  None = None)¶
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:
starconnected loads using a phases constructor argument containing “n”
deltaconnected loads using a phases constructor argument not containing “n”
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 bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the load must be present in the phases of the connected bus. Multiphase loads are allowed to have a floating neutral (i.e. they can be connected to buses that don’t have a neutral).
 property bus: roseau.load_flow.models.buses.Bus¶
The bus of the load.
 property res_currents: Q_[ComplexArray]¶
The load flow result of the load currents (A).
 property res_potentials: Q_[ComplexArray]¶
The load flow result of the load potentials (V).
 property res_voltages: Q_[ComplexArray]¶
The load flow result of the load voltages (V).
 property res_powers: Q_[ComplexArray]¶
The load flow result of the “line powers” flowing into the load (VA).
 classmethod from_dict(data: JsonDict, *, include_results: bool = True) AbstractLoad ¶
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.
 class Bus(id: Id, *, phases: str, geometry: shapely.geometry.base.BaseGeometry  None = None, potentials: ComplexArrayLike1D  None = None, min_voltage: float  None = None, max_voltage: float  None = None)¶
Bases:
roseau.load_flow.models.core.Element
A multiphase 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 xy coordinates of the bus.potentials – An optional arraylike 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 phaseneutral voltage if the bus has a neutral, phasephase 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 phaseneutral voltage if the bus has a neutral, phasephase otherwise. Either a float (V) or a
Quantity
of float.
 allowed_phases: Final¶
The allowed phases for a bus are:
PPP or PPPN:
"abc"
,"abcn"
PP or PPN:
"ab"
,"bc"
,"ca"
,"abn"
,"bcn"
,"can"
PN:
"an"
,"bn"
,"cn"
 property potentials: Q_[ComplexArray]¶
An array of initial potentials of the bus (V).
 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 phaseneutral voltages for existing phases in the order
[Van, Vbn, Vcn]
. If the bus does not have a neutral, phasephase voltages are returned in the order[Vab, Vbc, Vca]
.
 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 = \frac{V_n}{V_p} * 100 (\%)\)
Where \(V_n\) is the negativesequence voltage and \(V_p\) is the positivesequence 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.
 class Control(type: ControlType, u_min: float  Q_[float], u_down: float  Q_[float], u_up: float  Q_[float], u_max: float  Q_[float], alpha: float = _DEFAULT_ALPHA, epsilon: float = _DEFAULT_EPSILON)¶
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)\).
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 nondifferentiable function.
epsilon – This value is used to make a smooth inverse function. It is only useful for P control.
 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 nondifferentiable function.
 classmethod constant() typing_extensions.Self ¶
Create a constant control i.e no control.
 classmethod p_max_u_production(u_up: float  Q_[float], u_max: float  Q_[float], alpha: float = _DEFAULT_ALPHA, epsilon: float = _DEFAULT_EPSILON) 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 nondifferentiable function. This parameter is noted \(\alpha\) on the figure.
epsilon – This value is used to make a smooth inverse function.
 Returns:
The
"p_max_u_production"
control using the provided parameters.
 classmethod p_max_u_consumption(u_min: float  Q_[float], u_down: float  Q_[float], alpha: float = _DEFAULT_ALPHA, epsilon: float = _DEFAULT_EPSILON) 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 nondifferentiable function. This parameter is noted \(\alpha\) on the figure.
epsilon – This value is used to make a smooth inverse function.
 Returns:
The
"p_max_u_consumption"
control using the provided parameters.
 classmethod q_u(u_min: float  Q_[float], u_down: float  Q_[float], u_up: float  Q_[float], u_max: float  Q_[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 nondifferentiable function. This parameter is noted \(\alpha\) on the figure.
 Returns:
The
"q_u"
control using the provided parameters.
 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.
 The control for a
 class CurrentLoad(id: Id, bus: roseau.load_flow.models.buses.Bus, *, currents: ComplexArrayLike1D, phases: str  None = None)¶
Bases:
AbstractLoad
A constant current load.
CurrentLoad constructor.
 Parameters:
id – A unique ID of the load in the network loads.
bus – The bus to connect the load to.
currents – An arraylike of the currents for each phase component. Either complex values (A) or a
Quantity
of complex values.phases – The phases of the load. A string like
"abc"
or"an"
etc. The bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the load must be present in the phases of the connected bus.
 property currents: Q_[ComplexArray]¶
The currents of the load (Amps).
 class Element(id: Id)¶
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.
 allowed_phases: ClassVar[frozenset[str]]¶
The allowed phases for this element type.
It is a frozen set of strings like
"abc"
or"an"
etc. The order of the phases is important. For a full list of supported phases, useprint(<Element class>.allowed_phases)
.
 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  Q_[float], q_min: float  Q_[float]  None = None, q_max: float  Q_[float]  None = None)¶
Bases:
roseau.load_flow.utils.JsonMixin
Flexible parameters of a flexible load.
This class encapsulate singlephase 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 multiphase loads, you need to use a FlexibleParameter instance per phase.
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.
q_min – The minimum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.
q_max – The maximum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.
 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  Q_[float], u_max: float  Q_[float], s_max: float  Q_[float], alpha_control: float = Control._DEFAULT_ALPHA, epsilon_control: float = Control._DEFAULT_EPSILON, type_proj: ProjectionType = Projection._DEFAULT_TYPE, 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 nondifferentiable function.
epsilon_control – This value is used to make a smooth inverse function for the control.
type_proj – The type of the projection to use.
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  Q_[float], u_down: float  Q_[float], s_max: float  Q_[float], alpha_control: float = Control._DEFAULT_ALPHA, epsilon_control: float = Control._DEFAULT_EPSILON, type_proj: ProjectionType = Projection._DEFAULT_TYPE, 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 nondifferentiable function.
epsilon_control – This value is used to make a smooth inverse function for the control.
type_proj – The type of the projection to use.
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  Q_[float], u_down: float  Q_[float], u_up: float  Q_[float], u_max: float  Q_[float], s_max: float  Q_[float], q_min: float  Q_[float]  None = None, q_max: float  Q_[float]  None = None, alpha_control: float = Control._DEFAULT_ALPHA, type_proj: ProjectionType = Projection._DEFAULT_TYPE, 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.
q_min – The minimum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.
q_max – The maximum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the nondifferentiable function.
type_proj – The type of the projection to use.
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  Q_[float], up_max: float  Q_[float], uq_min: float  Q_[float], uq_down: float  Q_[float], uq_up: float  Q_[float], uq_max: float  Q_[float], s_max: float  Q_[float], q_min: float  Q_[float]  None = None, q_max: float  Q_[float]  None = None, alpha_control=Control._DEFAULT_ALPHA, epsilon_control: float = Control._DEFAULT_EPSILON, type_proj: ProjectionType = Projection._DEFAULT_TYPE, 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.
q_min – The minimum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.
q_max – The maximum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the nondifferentiable function.
epsilon_control – This value is used to make a smooth inverse function for the control.
type_proj – The type of the projection to use.
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  Q_[float], up_down: float  Q_[float], uq_min: float  Q_[float], uq_down: float  Q_[float], uq_up: float  Q_[float], uq_max: float  Q_[float], s_max: float  Q_[float], q_min: float  Q_[float]  None = None, q_max: float  Q_[float]  None = None, alpha_control: float  Q_[float] = Control._DEFAULT_ALPHA, epsilon_control: float = Control._DEFAULT_EPSILON, type_proj: ProjectionType = Projection._DEFAULT_TYPE, 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.
q_min – The minimum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.
q_max – The maximum reactive power of the flexible load (VAr). By default it is equal to s_max, but it can be further constrained.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the nondifferentiable function.
epsilon_control – This value is used to make a smooth inverse function for the control.
type_proj – The type of the projection to use.
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.
 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.
 compute_powers(voltages: ComplexArrayLike1D, power: complex  Q_[complex]) Q_[ComplexArray] ¶
Compute the flexible powers for different voltages (norms)
 Parameters:
voltages – The array of voltage norms to test with this flexible parameter.
power – The input theoretical power of the load.
 Returns:
The flexible powers really consumed taking into account the control. One value per provided voltage norm.
 plot_pq(voltages: FloatArrayLike1D, power: complex  Q_[complex], ax: Axes  None = None, voltages_labels_mask: numpy.typing.NDArray[numpy.bool_]  None = None) tuple[Axes, ComplexArray] ¶
Plot the “trajectory” of the flexible powers (in the (P, Q) plane) for the provided voltages and theoretical power.
 Parameters:
voltages – Arraylike of voltage norms to test with this flexible parameter.
power – The input theoretical power of the load.
ax – The optional axis to use for the plot. The current axis is used by default.
voltages_labels_mask – A mask to activate the plot of voltages labels. By default, no voltages annotations.
 Returns:
The axis on which the plot has been drawn and the resulting flexible powers (the input if not None else the computed values).
 plot_control_p(voltages: FloatArrayLike1D, power: complex  Q_[complex], ax: Axes  None = None) tuple[Axes, ComplexArray] ¶
Plot the flexible active power consumed (or produced) for the provided voltages and theoretical power.
 Parameters:
voltages – Arraylike of voltage norms to test with this flexible parameter.
power – The input theoretical power of the load.
ax – The optional axis to use for the plot. The current axis is used by default.
 Returns:
The axis on which the plot has been drawn and the resulting flexible powers (the input if not None else the computed values).
 plot_control_q(voltages: FloatArrayLike1D, power: complex  Q_[complex], ax: Axes  None = None) tuple[Axes, ComplexArray] ¶
Plot the flexible reactive power consumed (or produced) for the provided voltages and theoretical power.
 Parameters:
voltages – Arraylike of voltage norms to test with this flexible parameter.
power – The input theoretical power of the load.
ax – The optional axis to use for the plot. The current axis is used by default.
 Returns:
The axis on which the plot has been drawn and the resulting flexible powers (the input if not None else the computed values).
 class Ground(id: Id)¶
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.
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: roseau.load_flow.models.buses.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"
.
 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.
 class ImpedanceLoad(id: Id, bus: roseau.load_flow.models.buses.Bus, *, impedances: ComplexArrayLike1D, phases: str  None = None)¶
Bases:
AbstractLoad
A constant impedance load.
ImpedanceLoad constructor.
 Parameters:
id – A unique ID of the load in the network loads.
bus – The bus to connect the load to.
impedances – An arraylike of the impedances for each phase component. Either complex values (Ohms) or a
Quantity
of complex values.phases – The phases of the load. A string like
"abc"
or"an"
etc. The bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the load must be present in the phases of the connected bus. Multiphase loads are allowed to have a floating neutral (i.e. they can be connected to buses that don’t have a neutral).
 property impedances: Q_[ComplexArray]¶
The impedances of the load (Ohms).
 class Line(id: Id, bus1: roseau.load_flow.models.buses.Bus, bus2: roseau.load_flow.models.buses.Bus, *, parameters: roseau.load_flow.models.lines.parameters.LineParameters, length: float  Q_[float], phases: str  None = None, ground: roseau.load_flow.models.grounds.Ground  None = None, geometry: shapely.geometry.base.BaseGeometry  None = None)¶
Bases:
roseau.load_flow.models.branches.AbstractBranch
An electrical line PI model with series impedance and optional shunt admittance.
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 – Parameters defining the electric model of the line using its impedance and shunt admittance matrices. This is an instance of the
LineParameters
class and can be used by multiple lines.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.
 allowed_phases: Final¶
The allowed phases for a line are:
PPP or PPPN:
"abc"
,"abcn"
PP or PPN:
"ab"
,"bc"
,"ca"
,"abn"
,"bcn"
,"can"
P or PN:
"a"
,"b"
,"c"
,"an"
,"bn"
,"cn"
N:
"n"
 property parameters: roseau.load_flow.models.lines.parameters.LineParameters¶
The parameters defining the impedance and shunt admittance matrices of line model.
 property z_line: Q_[ComplexArray]¶
Impedance of the line (in Ohm).
 property y_shunt: Q_[ComplexArray]¶
Shunt admittance of the line (in Siemens).
 property res_series_currents: Q_[ComplexArray]¶
Get the current in the series elements of the line (in A).
 property res_series_power_losses: Q_[ComplexArray]¶
Get the power losses in the series elements of the line (in VA).
 property res_shunt_currents: tuple[Q_[ComplexArray], Q_[ComplexArray]]¶
Get the currents in the shunt elements of the line (in A).
 property res_shunt_power_losses: Q_[ComplexArray]¶
Get the power losses in the shunt elements of the line (in VA).
 property res_power_losses: Q_[ComplexArray]¶
Get the power losses in the line (in VA).
 class LineParameters(id: Id, z_line: ComplexArrayLike2D, y_shunt: ComplexArrayLike2D  None = None, max_current: float  None = None, line_type: LineType  None = None, conductor_type: ConductorType  None = None, insulator_type: InsulatorType  None = None, section: float  Q_[float]  None = None)¶
Bases:
roseau.load_flow.utils.Identifiable
,roseau.load_flow.utils.JsonMixin
,roseau.load_flow.utils.CatalogueMixin
[pandas.DataFrame
]Parameters that define electrical models of lines.
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.
max_current – The maximum current loading of the line (A). The maximum current is optional, it is not used in the load flow but can be used to check for overloading. See also
Line.res_violated
.line_type – The type of the line (overhead, underground, twisted). The line type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.
conductor_type – The type of the conductor material (Aluminum, Copper, …). The conductor type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.
insulator_type – The type of the cable insulator (PVC, XLPE, …). The insulator type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.
 property line_type: LineType  None¶
The type of the line. Informative only, it has no impact on the load flow.
 property conductor_type: ConductorType  None¶
The type of the conductor material. Informative only, it has no impact on the load flow.
 property insulator_type: InsulatorType  None¶
The type of the cable insulator. Informative only, it has no impact on the load flow.
 property section: Q_[float]  None¶
The crosssection area of the cable (in mm²). Informative only, it has no impact on the load flow.
 classmethod from_sym(id: Id, z0: complex  Q_[complex], z1: complex  Q_[complex], y0: complex  Q_[complex], y1: complex  Q_[complex], zn: complex  Q_[complex]  None = None, xpn: float  Q_[float]  None = None, bn: float  Q_[float]  None = None, bpn: float  Q_[float]  None = None, max_current: float  Q_[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)
max_current – An optional maximum current loading of the line (A). It is not used in the load flow.
 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  None = None, insulator_type: InsulatorType  None = None, section: float  Q_[float], section_neutral: float  Q_[float]  None = None, height: float  Q_[float], external_diameter: float  Q_[float], max_current: float  Q_[float]  None = None) typing_extensions.Self ¶
Create line parameters from its geometry.
 Parameters:
id – The id of the line parameters type.
line_type – Overhead or underground. See also
LineType
.conductor_type – Type of the conductor. If
None
,ACSR
is used for overhead lines andAL
for underground or twisted lines. See alsoConductorType
.insulator_type – Type of insulator. If
None
,XLPE
is used for twisted lines andPVC
for underground lines. See alsoInsulatorType
.section – Crosssection surface area of the phases (mm²).
section_neutral – Crosssection surface area of the neutral (mm²). If None it will be the same as the section of the other phases.
height – Height of the line (m). It must be positive for overhead lines and negative for underground lines.
external_diameter – External diameter of the cable (m).
max_current – An optional maximum current loading of the line (A). It is not used in the load flow.
 Returns:
The created line parameters.
 classmethod from_name_lv(name: str, section_neutral: float  Q_[float]  None = None, height: float  Q_[float]  None = None, external_diameter: float  Q_[float]  None = None, max_current: float  Q_[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 predefined, 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.
max_current – An optional maximum current loading of the line (A). It is not used in the load flow.
 Returns:
The corresponding line parameters.
Deprecated since version 0.6.0: Use
LineParameters.from_geometry()
instead.
 classmethod from_name_mv(name: str, max_current: float  Q_[float]  None = None) typing_extensions.Self ¶
Get the electrical parameters of a MV line from its canonical name (France specific model)
 Parameters:
name – The canonical name of the line parameters. It must be in the format lineType_conductorType_crossSection. E.g. “U_AL_150”.
max_current – An optional maximum current loading of the line (A). It is not used in the load flow.
 Returns:
The corresponding line parameters.
 classmethod from_power_factory(id: Id, *, r0: float  Q_[float], r1: float  Q_[float], x0: float  Q_[float], x1: float  Q_[float], b0: float  Q_[float], b1: float  Q_[float], rn: float  Q_[float]  None = None, xn: float  Q_[float]  None = None, bn: float  Q_[float]  None = None, rpn: float  Q_[float]  None = None, xpn: float  Q_[float]  None = None, bpn: float  Q_[float]  None = None, nphase: int = 3, nneutral: int = 0, inom: float  Q_[float]  None = None, cohl: Literal[0, 'Cable', 1, 'OHL'] = 'Cable', conductor: Literal['Al', 'Cu', 'Ad', 'As', 'Ds']  None = None, insulation: Literal[0, 'PVC', 1, 'XLPE', 2, 'Mineral', 3, 'Paper', 4, 'EPR']  None = None, section: float  Q_[float]  None = None) typing_extensions.Self ¶
Create a line parameters object from PowerFactory “TypLne” data.
 Parameters:
id – A unique ID of the line parameters.
r0 – PwF parameter rline0 (ACResistance R0’). Zero sequence resistance in (ohms/km).
r1 – PwF parameter rline (ACResistance R1’). Direct sequence resistance in (ohms/km).
x0 – PwF parameter xline0 (Reactance X0’). Zero sequence reactance in (ohms/km).
x1 – PwF parameter xline (Reactance X1’). Direct sequence reactance in (ohms/km).
b0 – PwF parameter bline0 (Susceptance B0’). Zero sequence susceptance in (µS/km).
b1 – PwF parameter bline (Susceptance B’). Direct sequence susceptance in (µS/km).
rn – PwF parameter rnline (ACResistance Rn’). Neutral resistance in (ohms/km).
xn – PwF parameter xnline (Reactance Xn’). Neutral reactance in (ohms/km).
bn – PwF parameter bnline (Susceptance Bn’). Neutral susceptance in (µS/km).
rpn – PwF parameter rnpline (ACResistance Rpn’). PhaseNeutral coupling resistance in (ohms/km).
xpn – PwF parameter xnpline (Reactance Xpn’). PhaseNeutral coupling reactance in (ohms/km).
bpn – PwF parameter bnpline (Susceptance Bpn’). PhaseNeutral coupling susceptance in (µS/km).
nphase – PwF parameter nlnph (Phases). The number of phases of the line between 1 and 3. This should not count the neutral conductor.
nneutral – PwF parameter nneutral (Number of Neutrals). The number of neutrals of the line. It can be either 0 or 1.
cohl – PwF parameter cohl_ (Cable/OHL). The type of the line; ‘Cable’ or 0 mean an underground cable and ‘OHL’ or 1 mean an overhead line.
inom – PwF parameter sline or InomAir (Rated Current in ground or in air). The rated current in (kA) of the line. It is used as the maximum current for analysis of network constraint violations. Pass the sline parameter if the line is an underground cable (cohl=’Cable’) or the InomAir parameter if the line is an overhead line (cohl=’OHL’).
conductor – PwF parameter mlei (Conductor Material). The material used for the conductors. It can be one of: ‘Al’ (Aluminium), ‘Cu’ (Copper), ‘Ad’ (Aldrey AlMgSi), ‘As’ (AluminiumSteel), ‘Ds’ (AldreySteel).
insulation – PwF parameter imiso (Insulation Material). The material used for the conductor’s insulation. It can be one of ‘PVC’ (0), ‘XLPE’ (1), ‘Mineral’ (2), ‘Paper’ (3) or ‘EPR’ (4).
section – PwF parameter qurs (Nominal Cross Section). The nominal crosssectional area of the conductors in (mm²).
 Returns:
The created line parameters.
 classmethod from_open_dss(id: Id, *, nphases: int, r1: float  Q_[float], r0: float  Q_[float], x1: float  Q_[float], x0: float  Q_[float], c1: float  Q_[float] = 3.4, c0: float  Q_[float] = 1.6, basefreq: float  Q_[float] = F, normamps: float  Q_[float]  None = None, linetype: str  None = None) typing_extensions.Self ¶
Create a line parameters object from OpenDSS “LineCode” data.
 Parameters:
id – The unique ID of the line parameters.
nphases – OpenDSS parameter: NPhases. Number of phases in the line this line code represents. To create singlephase lines with a neutral pass nphases=2, for threephase lines with a neutral nphases=4, etc.
r1 – OpenDSS parameter: R1. Positivesequence resistance in (ohm/km).
r0 – OpenDSS parameter: R0. Positivesequence resistance in (ohm/km).
x1 – OpenDSS parameter: X1. Positivesequence reactance in (ohm/km).
x0 – OpenDSS parameter: X0. Positivesequence reactance in (ohm/km).
c1 – OpenDSS parameter: C1. Positivesequence capacitance in (nF/km).
c0 – OpenDSS parameter: C0. Positivesequence capacitance in (nF/km).
basefreq – OpenDSS parameter: BaseFreq. Frequency at which impedances are specified (Hz). Defaults to 50 Hz.
normamps – OpenDSS parameter: NormAmps. Normal ampere limit on line (A). This is the socalled Planning Limit. It may also be the value above which load will have to be dropped in a contingency. Usually about 75%  80% of the emergency (onehour) rating. This value is passed to max_current and used for violation checks.
linetype – OpenDSS parameter: LineType. Code designating the type of line. Only
"OH"
(overhead) and"UG"
(underground) are currently supported.
 Returns:
The corresponding line parameters object.
Example usage:
# DSS command: `New linecode.240sq nphases=3 R1=0.127 X1=0.072 R0=0.342 X0=0.089 units=km` lp = LineParameters.from_open_dss( id="linecode240sq", nphases=3, # creates 3x3 Z,Y matrices r1=Q_(0.127, "ohm/km"), x1=Q_(0.072, "ohm/km"), r0=Q_(0.342, "ohm/km"), x0=Q_(0.089, "ohm/km"), c1=Q_(3.4, "nF/km"), # default value used in OpenDSS code c0=Q_(1.6, "nF/km"), # default value used in OpenDSS code ) # DSS command: `New LineCode.16sq NPhases=1 R1=0.350, X1=0.025, R0=0.366, X0=0.025, C1=1.036, C0=0.488 Units=kft NormAmps=400` lp = LineParameters.from_open_dss( id="linecode16sq", nphases=1, # creates 1x1 Z,Y matrices r1=Q_(0.350, "ohm/kft"), x1=Q_(0.025, "ohm/kft"), r0=Q_(0.366, "ohm/kft"), x0=Q_(0.025, "ohm/kft"), c1=Q_(1.036, "nF/kft"), c0=Q_(0.488, "nF/kft"), normamps=Q_(400, "A"), )
 classmethod from_catalogue(name: str  Pattern[str]  None = None, line_type: str  None = None, conductor_type: str  None = None, insulator_type: str  None = None, section: float  Q_[float]  None = None, id: Id  None = None, nb_phases: int = 3) typing_extensions.Self ¶
Create line parameters from a catalogue.
 Parameters:
name – The name of the line parameters to get from the catalogue. It can be a regular expression.
line_type – The type of the line parameters to get. It can be
"overhead"
,"twisted"
, or"underground"
. See alsoLineType
.conductor_type – The type of the conductor material (Al, Cu, …). See also
ConductorType
.insulator_type – The type of insulator. See also
InsulatorType
.section – The crosssection surface area of the phases (mm²).
id – A unique ID for the created line parameters object (optional). If
None
(default), the id of the created object will be its name in the catalogue. Note that this parameter is not used in the data filtering.nb_phases – The number of phases of the line between 1 and 4, defaults to 3. It represents the size of the
z_line
andy_shunt
matrices.
 Returns:
The created line parameters.
 classmethod get_catalogue(name: str  Pattern[str]  None = None, line_type: str  None = None, conductor_type: str  None = None, insulator_type: str  None = None, section: float  Q_[float]  None = None) DataFrame ¶
Get the catalogue of available lines.
You can use the parameters below to filter the catalogue. If you do not specify any parameter, all the catalogue will be returned.
 Parameters:
name – The name of the line parameters to get from the catalogue. It can be a regular expression.
line_type – The type of the line parameters to get. It can be
"overhead"
,"twisted"
, or"underground"
. See alsoLineType
.conductor_type – The type of the conductor material (Al, Cu, …). See also
ConductorType
.insulator_type – The type of insulator. See also
InsulatorType
.section – The crosssection surface area of the phases (mm²).
 Returns:
The catalogue data as a dataframe.
 class PotentialRef(id: Id, element: roseau.load_flow.models.buses.Bus  roseau.load_flow.models.grounds.Ground, *, phase: str  None = None)¶
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.
 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.
 class PowerLoad(id: Id, bus: roseau.load_flow.models.buses.Bus, *, powers: ComplexArrayLike1D, phases: str  None = None, flexible_params: list[roseau.load_flow.models.loads.flexible_parameters.FlexibleParameter]  None = None)¶
Bases:
AbstractLoad
A constant power load.
PowerLoad constructor.
 Parameters:
id – A unique ID of the load in the network loads.
bus – The bus to connect the load to.
powers – An arraylike of the powers for each phase component. Either complex values (VA) or a
Quantity
of complex values.phases – The phases of the load. A string like
"abc"
or"an"
etc. The bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the load must be present in the phases of the connected bus. Multiphase loads are allowed to have a floating neutral (i.e. they can be connected to buses that don’t have a neutral).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.
 property powers: Q_[ComplexArray]¶
The powers of the load (VA).
 property res_flexible_powers: Q_[ComplexArray]¶
The load flow result of the load flexible powers (VA).
This property is only available for flexible loads.
It returns the powers actually consumed or produced by each component of the load instead of the “line powers” flowing into the load connection points (as the
res_powers()
property does). The two properties are the same for Wyeconnected loads but are different for Deltaconnected loads.
 classmethod from_dict(data: JsonDict, *, include_results: bool = True) AbstractLoad ¶
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.
 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 a Euclidean projection on the feasible space;"keep_p"
: for maintaining a constant P;"keep_q"
: for maintaining a constant Q.
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.
 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.
 class Switch(id: Id, bus1: roseau.load_flow.models.buses.Bus, bus2: roseau.load_flow.models.buses.Bus, *, phases: str  None = None, geometry: shapely.geometry.base.BaseGeometry  None = None)¶
Bases:
roseau.load_flow.models.branches.AbstractBranch
A general purpose switch branch.
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: Final¶
The allowed phases for a switch are:
PPP or PPPN:
"abc"
,"abcn"
PP or PPN:
"ab"
,"bc"
,"ca"
,"abn"
,"bcn"
,"can"
P or PN:
"a"
,"b"
,"c"
,"an"
,"bn"
,"cn"
N:
"n"
 class Transformer(id: Id, bus1: roseau.load_flow.models.buses.Bus, bus2: roseau.load_flow.models.buses.Bus, *, parameters: roseau.load_flow.models.transformers.parameters.TransformerParameters, tap: float = 1.0, phases1: str  None = None, phases2: str  None = None, geometry: shapely.geometry.base.BaseGeometry  None = None)¶
Bases:
roseau.load_flow.models.branches.AbstractBranch
A generic transformer model.
The model parameters are defined using the
parameters
argument.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 – Parameters defining the electrical model of the transformer. This is an instance of the
TransformerParameters
class and can be used by multiple transformers.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.
 allowed_phases: Final¶
The allowed phases for a transformer are:
PPP or PPPN:
"abc"
,"abcn"
(threephase transformer)PP or PN:
"ab"
,"bc"
,"ca"
,"an"
,"bn"
,"cn"
(singlephase transformer or primary of centertapped transformer)PPN:
"abn"
,"bcn"
,"can"
(secondary of centertapped transformer)
 property parameters: roseau.load_flow.models.transformers.parameters.TransformerParameters¶
The parameters of the transformer.
 class TransformerParameters(id: Id, type: str, uhv: float  Q_[float], ulv: float  Q_[float], sn: float  Q_[float], z2: complex  Q_[complex], ym: complex  Q_[complex], max_power: float  Q_[float]  None = None)¶
Bases:
roseau.load_flow.utils.Identifiable
,roseau.load_flow.utils.JsonMixin
,roseau.load_flow.utils.CatalogueMixin
[pandas.DataFrame
]Parameters that define electrical models of transformers.
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 singlephase transformers, “center” for centertapped transformers, or the name of the windings such as “Dyn11” for threephase transformers. Allowed windings are “D” for delta, “Y” for wye (star), and “Z” for zigzag.
uhv – Phasetophase nominal voltages of the high voltages side (V)
ulv – Phasetophase nominal voltages of the low voltages side (V)
sn – The nominal power of the transformer (VA)
z2 – The series impedance located at the secondary side of the transformer.
ym – The magnetizing admittance located at the primary side of the transformer.
max_power – The maximum power loading of the transformer (VA). It is not used in the load flow.
 property orientation: float¶
1 for direct windings or 1 for reverse windings.
 Type:
The orientation of the transformer
 property max_power: Q_[float]  None¶
The maximum power loading of the transformer (VA) if it is set.
 to_zyk() tuple[Q_[complex], Q_[complex], Q_[float], float] ¶
Get 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
).
 classmethod from_power_factory(id: Id, *, tech: Literal[2, 'singlephase', 3, 'threephase'], sn: float  Q_[float], uhv: float  Q_[float], ulv: float  Q_[float], vg_hv: str, vg_lv: str, phase_shift: int, uk: float  Q_[float], pc: float  Q_[float], curmg: float  Q_[float], pfe: float  Q_[float], maxload: float  Q_[float]  None = 100) typing_extensions.Self ¶
Create a transformer parameters object from PowerFactory “TypTr2” data.
Note that only twowinding threephase transformers are currently supported.
 Parameters:
id – A unique ID of the transformer parameters.
tech – PwF parameter nt2ph (Technology). The technology of the transformer; either ‘singlephase’ or 2 for singlephase transformers or ‘threephase’ or 3 for threephase transformers.
sn – PwF parameter strn (Rated Power). The rated power of the transformer in (MVA).
uhv – PwF parameter utrn_h (Rated Voltage HVSide). The rated phase to phase voltage of the transformer on the high voltage side.
ulv – PwF parameter utrn_l (Rated Voltage LVSide). The rated phase to phase voltage of the transformer on the low voltage side.
vg_hv – PwF parameter tr2cn_h (Vector Group HVSide). The vector group of the high voltage side. It can be one of ‘D’, ‘Y’, ‘Yn’, ‘Z’, ‘Zn’.
vg_lv – PwF parameter tr2cn_l (Vector Group LVSide). The vector group of the low voltage side. It can be one of ‘d’, ‘y’, ‘yn’, ‘z’, ‘zn’.
phase_shift – PwF parameter nt2ag (Vector Group Phase Shift). The phase shift of the vector group in (degrees).
uk – PwF parameter uktr (Positive Sequence Impedance ShortCircuit Voltage). The positive sequence impedance i.e the voltage in (%) obtained from the shortcircuit test.
pc – PwF parameter pcutr (Positive Sequence Impedance Copper Losses). The positive sequence impedance copper losses i.e the power in (kW) obtained from the short circuit test.
curmg – PwF parameter curmg (Magnetizing Impedance  No Load Current). The magnetizing current i.e the current in (%) obtained from the noload (opencircuit) test.
pfe – PwF parameter pfe (Magnetizing Impedance  No Load Losses). The magnetizing impedance i.e the power losses in (kW) obtained from the noload test.
maxload – PwF parameter maxload (Max. Thermal Loading Limit). The maximum loading of the transformer in (%) of the nominal power. This parameter is defined on the transformer element (ElmTr2) in PwF instead of the transformer type (TypTr2). This is used to compute max_current and is used for violation checks.
 Returns:
The corresponding transformer parameters object.
 classmethod from_open_dss(id: Id, *, conns: tuple[str, str], kvs: tuple[float, float]  FloatArrayLike1D, kvas: float  Q_[float]  tuple[float, float]  FloatArrayLike1D, leadlag: str, xhl: float, loadloss: float  Q_[float]  None = None, noloadloss: float  Q_[float] = 0, imag: float  Q_[float] = 0, rs: float  Q_[float]  tuple[float, float]  FloatArrayLike1D  None = None, normhkva: float  Q_[float]  None = None) typing_extensions.Self ¶
Create a transformer parameters object from OpenDSS “Transformer” data.
Note that only twowinding threephase transformers are currently supported.
 Parameters:
id – The unique ID of the transformer parameters.
conns – OpenDSS parameter: Conns. Connection of the windings. One of {wye  ln} for wye connected banks or {delta  ll} for delta (lineline) connected banks.
kvs – OpenDSS parameter: KVs. Rated phasetophase voltage of the windings, kV. This is a sequence of two values equivalent to (Uhv, Ulv).
kvas – OpenDSS parameter: KVAs. Base kVA rating (OA rating) of the windings. Note that only one value is accepted as only twowinding transformers are accepted.
xhl – OpenDSS parameter: XHL. Percent reactance hightolow (winding 1 to winding 2).
loadloss – OpenDSS parameter: %Loadloss. Percent Losses at rated load. Causes the %r values (cf. the %Rs parameter) to be set for windings 1 and 2.
noloadloss – OpenDSS parameter: %Noloadloss. Percent No load losses at nominal voltage. Default is 0. Causes a resistive branch to be added in parallel with the magnetizing inductance.
imag – OpenDSS parameter: %Imag. Percent magnetizing current. Default is 0. An inductance is used to represent the magnetizing current. This is embedded within the transformer model as the primitive Y matrix is being computed.
leadlag – OpenDSS parameter: LeadLag. {Lead  Lag  ANSI  Euro} Designation in mixed Deltawye connections signifying the relationship between HV to LV winding. Default is ANSI 30 deg lag, e.g., Dy1 of Yd1 vector group. To get typical European Dy11 connection, specify either “lead” or “Euro”.
rs – OpenDSS parameter: %Rs. [OPTIONAL] Percent resistance of the windings on the rated kVA base. Only required if loadloss is not passed. Note that if rs is used along with loadloss, they have to have equivalent values. For a twowinding transformer, %rs=[0.1, 0.1] is equivalent to %loadloss=0.2.
normhkva – OpenDSS parameter: NormHKVA. Normal maximum kVA rating for H winding (1). Usually 100  110% of maximum nameplate rating. This value is passed to max_current and used for violation checks.
 Returns:
The corresponding transformer parameters object.
Example usage:
# DSS command: `DSSText.Command = "New transformer.LVTR Buses=[sourcebus, A.1.2.3] Conns=[delta wye] KVs=[11, 0.4] KVAs=[250 250] %Rs=0.00 xhl=2.5 %loadloss=0 "` tp = rlf.TransformerParameters.from_open_dss( id="dsstp", conns=("delta", "wye"), kvs=(11, 0.4), kvas=(250, 250), # alternatively pass a scalar `kvas=250` leadlag="euro", # THE ONLY OPENDSS MODEL WE CURRENTLY SUPPORT xhl=2.5, loadloss=0, noloadloss=0, # default value used in OpenDSS imag=0, # default value used in OpenDSS rs=0, # redundant with `loadloss=0` )
 classmethod from_open_and_short_circuit_tests(id: Id, type: str, uhv: float  Q_[float], ulv: float  Q_[float], sn: float  Q_[float], p0: float  Q_[float], i0: float  Q_[float], psc: float  Q_[float], vsc: float  Q_[float], max_power: float  Q_[float]  None = None) typing_extensions.Self ¶
Create a TransformerParameters object using the results of opencircuit and shortcircuit tests.
 Parameters:
id – A unique ID of the transformer parameters, typically its canonical name.
type – The type of transformer parameters. It can be “single” for singlephase transformers, “center” for centertapped transformers, or the name of the windings such as “Dyn11” for threephase transformers. Allowed windings are “D” for delta, “Y” for wye (star), and “Z” for zigzag.
uhv – Phasetophase nominal voltages of the high voltages side (V)
ulv – Phasetophase nominal voltages of the low voltages side (V)
sn – The nominal power of the transformer (VA)
p0 – Losses during opencircuit test (W)
i0 – Current during opencircuit test (%)
psc – Losses during shortcircuit test (W)
vsc – Voltages on LV side during shortcircuit test (%)
max_power – The maximum power loading of the transformer (VA). It is not used in the load flow.
 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.
 classmethod from_catalogue(name: 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  Q_[float]  None = None, uhv: float  Q_[float]  None = None, ulv: float  Q_[float]  None = None, id: Id  None = None) typing_extensions.Self ¶
Build a transformer parameters from one in the catalogue.
 Parameters:
name – The name 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.
id – A unique ID for the created line parameters object (optional). If
None
(default), the id of the created object will be its name in the catalogue. Note that this parameter is not used in the data filtering.
 Returns:
The selected transformer. If several transformers fitting the filters are in the catalogue, an error is raised.
 classmethod get_catalogue(name: 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  Q_[float]  None = None, uhv: float  Q_[float]  None = None, ulv: float  Q_[float]  None = None) DataFrame ¶
Get the catalogue of available transformers.
You can use the parameters below to filter the catalogue. If you do not specify any parameter, all the catalogue will be returned.
 Parameters:
name – An optional name 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.
 Returns:
The catalogue data as a dataframe.
 class VoltageSource(id: Id, bus: roseau.load_flow.models.buses.Bus, *, voltages: ComplexArrayLike1D, phases: str  None = None)¶
Bases:
roseau.load_flow.models.core.Element
A voltage source.
Voltage source constructor.
 Parameters:
id – A unique ID of the voltage source in the network sources.
bus – The bus of the voltage source.
voltages – An arraylike of the voltages of the source. They will be set on the connected bus. If the source has a neutral connection, the voltages are considered phasetoneutral voltages, otherwise they are the phasetophase voltages. Either complex values (V) or a
Quantity
of complex values.phases – The phases of the source. A string like
"abc"
or"an"
etc. The bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the source must be present in the phases of the connected bus. Multiphase sources are allowed to have a floating neutral (i.e. they can be connected to buses that don’t have a neutral).
 property bus: roseau.load_flow.models.buses.Bus¶
The bus of the source.
 property voltages: Q_[ComplexArray]¶
The voltages of the source (V).
 property res_currents: Q_[ComplexArray]¶
The load flow result of the source currents (A).
 property res_potentials: Q_[ComplexArray]¶
The load flow result of the source potentials (V).
 property res_powers: Q_[ComplexArray]¶
The load flow result of the source powers (VA).
 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.
 class ElectricalNetwork(buses: MapOrSeq[Bus], branches: MapOrSeq[AbstractBranch], loads: MapOrSeq[AbstractLoad], sources: MapOrSeq[VoltageSource], grounds: MapOrSeq[Ground], potential_refs: MapOrSeq[PotentialRef], crs: str  pyproj.CRS  None = None)¶
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.
crs – An optional Coordinate Reference System to use with geo data frames. If not provided, the
EPSG:4326
CRS will be used.
 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:
 classmethod from_element(initial_bus: Bus) typing_extensions.Self ¶
Construct the network from only one element (bus) and add the others automatically.
 Parameters:
initial_bus – Any bus of the network. The network is constructed from this bus and all the elements connected to it. This is usually the main source bus of the network.
 Returns:
The network constructed from the given bus and all the elements connected to it.
 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 transformers_frame: GeoDataFrame¶
The transformers of the network as a geo dataframe.
This is similar to
branches_frame
but only contains the transformers. It has a max_power column that contains the maximum power loading (VA) of the transformers.
 property lines_frame: GeoDataFrame¶
The lines of the network as a geo dataframe.
This is similar to
branches_frame
but only contains the lines. It has a max_current column that contains the maximum current loading (A) of the lines.
 property switches_frame: GeoDataFrame¶
The switches of the network as a geo dataframe.
This is similar to
branches_frame
but only contains the switches.
 property potential_refs_frame: DataFrame¶
The
potential references
of the network as a dataframe.
 property buses_clusters: list[set[Id]]¶
Sets of galvanically connected buses, i.e buses connected by lines or a switches.
This can be useful to isolate parts of the network for localized analysis. For example, to study a LV subnetwork of a MV feeder.
See also
Bus.get_connected_buses()
: Get the buses in the same galvanically isolated section as a certain bus.
 to_graph() Graph ¶
Create a networkx graph from this electrical network.
The graph contains the geometries of the buses in the nodes data and the geometries and branch types in the edges data.
Note
This method requires networkx to be installed. You can install it with the
"graph"
extra if you are using pip:pip install "roseauloadflow[graph]"
.
 solve_load_flow(max_iterations: int = 20, tolerance: float = 1e06, warm_start: bool = True, solver: Solver = _DEFAULT_SOLVER, solver_params: JsonDict  None = None) tuple[int, float] ¶
Solve the load flow for this network.
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)
.You need to activate the license before calling this method. Alternatively you may set the environment variable
ROSEAU_LOAD_FLOW_LICENSE_KEY
to your license key and it will be picked automatically when calling this method. See the License page for more information. Parameters:
max_iterations – The maximum number of allowed iterations.
tolerance – Tolerance needed for the convergence.
warm_start – If true (the default), the solver is initialized with the potentials of the last successful load flow result (if any). Otherwise, the potentials are reset to their initial values.
solver –
 The name of the solver to use for the load flow. The options are:
'newton'
: the classical NewtonRaphson solver.'newton_goldstein'
: the NewtonRaphson 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 General information page.
 Returns:
The number of iterations performed and the residual error at the last iteration.
 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 linetoneutral voltage. Otherwise, the voltage is the linetoline 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.
min_voltage: The minimum voltage of the bus (in Volts).
max_voltage: The maximum voltage of the bus (in Volts).
 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:
type: The type of the branch, can be
{'line', 'transformer', 'switch'}
. 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_transformers: DataFrame¶
The load flow results of the network transformers.
This is similar to the
res_branches
property but provides more information that only apply to transformers. The results are returned as a dataframe with the following index:
transformer_id: The id of the transformer.
phase: The phase of the transformer (in
{'a', 'b', 'c', 'n'}
).
 and the following columns:
 current1: The complex current of the transformer (in Amps) for the given phase at the
first bus.
 current2: The complex current of the transformer (in Amps) for the given phase at the
second bus.
 power1: The complex power of the transformer (in VoltAmps) for the given phase at the
first bus.
 power2: The complex power of the transformer (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.
max_power: The maximum power loading (in VoltAmps) of the transformer.
Note that values for missing phases are set to
nan
. For example, a “Dyn” transformer has the phases “abc” on the primary side and “abcn” on the secondary side, so the primary side values for current, power, and potential for phase “n” will benan
.
 property res_lines: DataFrame¶
The load flow results of 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_switches: DataFrame¶
The load flow results of the network switches.
This is similar to the
res_branches
property but only apply to switches. The results are returned as a dataframe with the following index:
switch_id: The id of the switch.
phase: The phase of the switch (in
{'a', 'b', 'c', 'n'}
).
 and the following columns:
 current1: The complex current of the switch (in Amps) for the given phase at the
first bus.
 current2: The complex current of the switch (in Amps) for the given phase at the
second bus.
 power1: The complex power of the switch (in VoltAmps) for the given phase at the
first bus.
 power2: The complex power of the switch (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_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:
type: The type of the load, can be
{'power', 'current', 'impedance'}
.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:
type: The type of the load, can be
{'power', 'current', 'impedance'}
.svoltage: 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_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self ¶
Construct an electrical network from a dict created with
to_dict()
. Parameters:
data – The dictionary containing the network 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 network.
 classmethod dgs_export_definition_folder_path() Path ¶
Returns the path to the DGS pfd file to use as “Export Definition Folder”.
 classmethod from_dgs(path: StrPath) typing_extensions.Self ¶
Construct an electrical network from json DGS file (PowerFactory).
Only JSON format of DGS is currently supported. See the Data Exchange page for more information.
 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 get_catalogue(name: str  Pattern[str]  None = None, load_point_name: str  Pattern[str]  None = None) DataFrame ¶
Read a network dictionary from 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 dictionary containing the network data.
 class ConductorType¶
Bases:
roseau.load_flow._compat.StrEnum
The type of the material of the conductor.
Initialize self. See help(type(self)) for accurate signature.
 CU¶
Copper – Fr = Cuivre.
 AL¶
All Aluminum Conductor (AAC) – Fr = Aluminium.
 AM¶
All Aluminum Alloy Conductor (AAAC) – Fr = Almélec.
 AA¶
Aluminum Conductor Steel Reinforced (ACSR) – Fr = AluAcier.
 LA¶
Aluminum Alloy Conductor Steel Reinforced (AACSR) – Fr = AlmélecAcier.
 AAC¶
All Aluminum Conductor (AAC) – Fr = Aluminium.
 AAAC¶
All Aluminum Alloy Conductor (AAAC) – Fr = Almélec.
 ACSR¶
Aluminum Conductor Steel Reinforced (ACSR) – Fr = AluAcier.
 AACSR¶
Aluminum Alloy Conductor Steel Reinforced (AACSR) – Fr = AlmélecAcier.
 class InsulatorType¶
Bases:
roseau.load_flow._compat.StrEnum
The type of the insulator for a wire.
Initialize self. See help(type(self)) for accurate signature.
 UNKNOWN¶
The material of the insulator is unknown.
 HDPE¶
HighDensity PolyEthylene (HDPE) insulation.
 MDPE¶
MediumDensity PolyEthylene (MDPE) insulation.
 LDPE¶
LowDensity PolyEthylene (LDPE) insulation.
 XLPE¶
Crosslinked polyethylene (XLPE) insulation.
 EPR¶
EthylenePropylene Rubber (EPR) insulation.
 PVC¶
PolyVinyl Chloride (PVC) insulation.
 IP¶
Impregnated Paper (IP) insulation.
 PEX¶
Alias – Crosslinked polyethylene (XLPE) insulation.
 PE¶
Alias – MediumDensity PolyEthylene (MDPE) insulation.
 class LineType¶
Bases:
roseau.load_flow._compat.StrEnum
The type of a line.
Initialize self. See help(type(self)) for accurate signature.
 OVERHEAD¶
An overhead line that can be vertically or horizontally configured – Fr = Aérien.
 UNDERGROUND¶
An underground or a submarine cable – Fr = Souterrain/SousMarin.
 TWISTED¶
A twisted line commonly known as Aerial Cable or Aerial Bundled Conductor (ABC) – Fr = Torsadé.