Flexible loads¶
They are a special type of power loads: instead of being constant, the power will depend on the voltage measured at the load and the control applied to the load.
Equations¶
The equations are the following (star loads):
And the following (delta loads):
The expression \(\underline{S}(U)\) depends on four parameters:
The theoretical power \(\underline{S^{\mathrm{th.}}}\) that the load would have if no control is applied.
The maximal power \(S^{\max}\) that can be injected/consumed by the load. For a PV installation, this is usually the rated power of the inverter.
The type of control (see here).
The type of projection (see here).
Detailed pages¶
All these elements are detailed in the following sections:
API Reference¶
- class Control(type: Literal['constant', 'p_max_u_production', 'p_max_u_consumption', 'q_u'], u_min: float | Quantity[float], u_down: float | Quantity[float], u_up: float | Quantity[float], u_max: float | Quantity[float], alpha: float = 1000.0, epsilon: float = 1e-08)
Bases:
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 non-differentiable function.
epsilon – This value is used to make a smooth inverse function. It is only useful for P control.
- property u_min: Quantity[float]
The minimum voltage i.e. the one the control reached the maximum action.
- property u_max: Quantity[float]
The maximum voltage i.e. the one the control reached its maximum action.
- property alpha: float
An approximation factor used by the family function (soft clip). The bigger the factor is the closer the function is to the non-differentiable function.
- property epsilon: float
This value is used to make a smooth inverse function.
- classmethod constant() Self
Create a constant control i.e no control.
- classmethod p_max_u_production(u_up: float | Quantity[float], u_max: float | Quantity[float], alpha: float = 1000.0, epsilon: float = 1e-08) Self
Create a control of the type
"p_max_u_production"
.See also
- Parameters:
u_up – The voltage norm that triggers the control. A voltage higher than this value signals to the controller to start to reduce the production active power. On the figure, a normalised version \(U^{\mathrm{up}\,\mathrm{norm.}}\) is used.
u_max – The maximum norm voltage i.e. the one the control reached its maximum action. A voltage higher than this value signals to the controller to set the production active power to its minimal value. On the figure, a normalised version \(U^{\max\,\mathrm{norm.}}\) is used.
alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.
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 | Quantity[float], u_down: float | Quantity[float], alpha: float = 1000.0, epsilon: float = 1e-08) Self
Create a control of the type
"p_max_u_consumption"
.See also
- Parameters:
u_min – The minimum voltage norm i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the consumption active power to its minimal value. On the figure, a normalised version \(U^{\min\,\mathrm{norm.}}\) is used.
u_down – The voltage norm that triggers the control. A voltage lower than this value signals to the controller to start to reduce the consumption active power. On the figure, a normalised version \(U^{\mathrm{down}\,\mathrm{norm.}}\) is used.
alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.
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 | Quantity[float], u_down: float | Quantity[float], u_up: float | Quantity[float], u_max: float | Quantity[float], alpha: float = 1000.0) Self
Create a control of the type
"q_u"
.See also
- Parameters:
u_min – The minimum voltage norm i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the reactive power to its maximal capacitive value. On the figure, a normalised version \(U^{\min\,\mathrm{norm.}}\) is used.
u_down – The voltage that triggers the capacitive reactive power control. A voltage lower than this value signals to the controller to start to increase the capacitive reactive power. On the figure, a normalised version \(U^{\mathrm{down}\,\mathrm{norm.}}\) is used.
u_up – The voltage that triggers the inductive reactive power control. A voltage higher than this value signals to the controller to start to increase the inductive reactive power. On the figure, a normalised version \(U^{\mathrm{up}\,\mathrm{norm.}}\) is used.
u_max – The minimum voltage i.e. the one the control reached its maximum action. A voltage lower than this value signals to the controller to set the reactive power to its maximal inductive value. On the figure, a normalised version \(U^{\max\,\mathrm{norm.}}\) is used.
alpha – A factor used to soften the control function (soft clip) to make it more differentiable. The bigger alpha is, the closer the function is to the non-differentiable function. This parameter is noted \(\alpha\) on the figure.
- Returns:
The
"q_u"
control using the provided parameters.
- classmethod from_dict(data: dict[str, Any], *, include_results: bool = True) 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 Projection(type: Literal['euclidean', 'keep_p', 'keep_q'], alpha: float = 1000.0, epsilon: float = 1e-08)
Bases:
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: dict[str, Any], *, include_results: bool = True) 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 FlexibleParameter(control_p: Control, control_q: Control, projection: Projection, s_max: float | Quantity[float], q_min: float | Quantity[float] | None = None, q_max: float | Quantity[float] | None = None)
Bases:
JsonMixin
Flexible parameters of a flexible load.
This class encapsulate single-phase flexibility information of a flexible load:
The active power
Control
to apply;The reactive power
Control
to apply;The
Projection
to use when dealing with voltage violations;- The apparent power of the flexible load (VA). This is the maximum power the load can consume/produce. It is
the radius of the feasible circle used by the projection
For multi-phase loads, you need to use a FlexibleParameter instance per phase.
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: Quantity[float]
The apparent power of the flexible load (VA). It is the radius of the feasible circle.
- classmethod constant() 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 | Quantity[float], u_max: float | Quantity[float], s_max: float | Quantity[float], alpha_control: float = 1000.0, epsilon_control: float = 1e-08, type_proj: Literal['euclidean', 'keep_p', 'keep_q'] = 'euclidean', alpha_proj: float = 1000.0, epsilon_proj: float = 1e-08) Self
Build flexible parameters for production
P(U)
control with a Euclidean projection.See also
- Parameters:
u_up – The voltage upper limit value that triggers the control. If the voltage is greater than this value, the production active power is reduced.
u_max – The maximum voltage i.e. the one the control reached its maximum action. If the voltage is greater than this value, the production active power is reduced to zero.
s_max – The apparent power of the flexible inverter (VA). It is the radius of the feasible circle.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.
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 | Quantity[float], u_down: float | Quantity[float], s_max: float | Quantity[float], alpha_control: float = 1000.0, epsilon_control: float = 1e-08, type_proj: Literal['euclidean', 'keep_p', 'keep_q'] = 'euclidean', alpha_proj: float = 1000.0, epsilon_proj: float = 1e-08) Self
Build flexible parameters for consumption
P(U)
control with a Euclidean projection.See also
- Parameters:
u_min – The minimum voltage i.e. the one the control reached the maximum action.
u_down – The voltage which starts to trigger the control (lower value).
s_max – The apparent power of the flexible load (VA). It is the radius of the feasible circle.
alpha_control – An approximation factor used by the family function (soft clip). The greater, the closer the function are from the non-differentiable function.
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 | Quantity[float], u_down: float | Quantity[float], u_up: float | Quantity[float], u_max: float | Quantity[float], s_max: float | Quantity[float], q_min: float | Quantity[float] | None = None, q_max: float | Quantity[float] | None = None, alpha_control: float = 1000.0, type_proj: Literal['euclidean', 'keep_p', 'keep_q'] = 'euclidean', alpha_proj: float = 1000.0, epsilon_proj: float = 1e-08) 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 non-differentiable 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 | Quantity[float], up_max: float | Quantity[float], uq_min: float | Quantity[float], uq_down: float | Quantity[float], uq_up: float | Quantity[float], uq_max: float | Quantity[float], s_max: float | Quantity[float], q_min: float | Quantity[float] | None = None, q_max: float | Quantity[float] | None = None, alpha_control=1000.0, epsilon_control: float = 1e-08, type_proj: Literal['euclidean', 'keep_p', 'keep_q'] = 'euclidean', alpha_proj=1000.0, epsilon_proj=1e-08) 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 non-differentiable 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 | Quantity[float], up_down: float | Quantity[float], uq_min: float | Quantity[float], uq_down: float | Quantity[float], uq_up: float | Quantity[float], uq_max: float | Quantity[float], s_max: float | Quantity[float], q_min: float | Quantity[float] | None = None, q_max: float | Quantity[float] | None = None, alpha_control: float | Quantity[float] = 1000.0, epsilon_control: float = 1e-08, type_proj: Literal['euclidean', 'keep_p', 'keep_q'] = 'euclidean', alpha_proj: float = 1000.0, epsilon_proj: float = 1e-08) 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 non-differentiable 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: dict[str, Any], *, include_results: bool = True) 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: ndarray[Any, dtype[complex128]] | Quantity[ndarray[Any, dtype[complex128]]] | Quantity[Sequence[complex]] | Sequence[complex | Quantity[complex]], power: complex | Quantity[complex]) Quantity[ndarray[Any, dtype[complex128]]]
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: ndarray[Any, dtype[float64]] | Quantity[ndarray[Any, dtype[float64]]] | Quantity[Sequence[float]] | Sequence[float | Quantity[float]], power: complex | Quantity[complex], ax: Axes | None = None, voltages_labels_mask: ndarray[Any, dtype[bool]] | None = None) tuple[Axes, ndarray[Any, dtype[complex128]]]
Plot the “trajectory” of the flexible powers (in the (P, Q) plane) for the provided voltages and theoretical power.
- Parameters:
voltages – Array-like 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: ndarray[Any, dtype[float64]] | Quantity[ndarray[Any, dtype[float64]]] | Quantity[Sequence[float]] | Sequence[float | Quantity[float]], power: complex | Quantity[complex], ax: Axes | None = None) tuple[Axes, ndarray[Any, dtype[complex128]]]
Plot the flexible active power consumed (or produced) for the provided voltages and theoretical power.
- Parameters:
voltages – Array-like 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: ndarray[Any, dtype[float64]] | Quantity[ndarray[Any, dtype[float64]]] | Quantity[Sequence[float]] | Sequence[float | Quantity[float]], power: complex | Quantity[complex], ax: Axes | None = None) tuple[Axes, ndarray[Any, dtype[complex128]]]
Plot the flexible reactive power consumed (or produced) for the provided voltages and theoretical power.
- Parameters:
voltages – Array-like 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).