roseau.load_flow.models.loads
#
Package Contents#
Classes#
Control class for flexible loads. 

Flexible parameters of a flexible load. 

This class defines the projection on the feasible circle for a flexible load. 

An abstract class of an electric load. 

A constant current load. 

A constant impedance load. 

A constant power load. 
 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 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[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 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 AbstractLoad(id: Id, bus: 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 order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the load, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.
 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).
 allowed_phases: Final#
The allowed phases for a load are the same as for a
bus
.
 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 CurrentLoad(id: Id, bus: 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 order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the load, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.
 property currents: Q_[ComplexArray]#
The currents of the load (Amps).
 class ImpedanceLoad(id: Id, bus: 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 order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the load, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.
 property impedances: Q_[ComplexArray]#
The impedances of the load (Ohms).
 class PowerLoad(id: Id, bus: Bus, *, powers: ComplexArrayLike1D, phases: str  None = None, flexible_params: list[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 order of the phases is important. For a full list of supported phases, see the class attributeallowed_phases
. All phases of the load, except"n"
, must be present in the phases of the connected bus. By default, the phases of the bus are used.flexible_params – A list of
FlexibleParameters
object, one for each phase. When provided, the load is considered as flexible (or controllable) and the parameters are used to compute the flexible power of the load.
 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.