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):

\[\begin{split}\left\{ \begin{aligned} \underline{I_{\mathrm{abc}}} &= \left(\frac{ \underline{S_{\mathrm{abc}}}(\underline{V_{\mathrm{abc}}}-\underline{V_{\mathrm{n}}}) }{\underline{V_{\mathrm{abc}}}-\underline{V_{\mathrm{n}}}}\right)^{\star} \\ \underline{I_{\mathrm{n}}} &= -\sum_{p\in\{\mathrm{a},\mathrm{b},\mathrm{c}\}}\underline{I_{p}} \end{aligned} \right.\end{split}\]

And the following (delta loads):

\[\begin{split}\left\{ \begin{aligned} \underline{I_{\mathrm{ab}}} &= \left(\frac{\underline{S_{\mathrm{ab}}}(\underline{V_{\mathrm{a}}}-\underline {V_{\mathrm{b}}})}{\underline{V_{\mathrm{a}}}-\underline{V_{\mathrm{b}}}}\right)^{\star} \\ \underline{I_{\mathrm{bc}}} &= \left(\frac{\underline{S_{\mathrm{bc}}}(\underline{V_{\mathrm{b}}}-\underline {V_{\mathrm{c}}})}{\underline{V_{\mathrm{b}}}-\underline{V_{\mathrm{c}}}}\right)^{\star} \\ \underline{I_{\mathrm{ca}}} &= \left(\frac{\underline{S_{\mathrm{ca}}}(\underline{V_{\mathrm{c}}}-\underline {V_{\mathrm{a}}})}{\underline{V_{\mathrm{c}}}-\underline{V_{\mathrm{a}}}}\right)^{\star} \end{aligned} \right.\end{split}\]

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:

Flexible loads

API Reference¶

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 simple PowerLoad 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 type: The type of the control.

property u_min: The minimum voltage i.e. the one the control reached the maximum action.

property u_down: The voltage which starts to trigger the control (lower value).

property u_up: TThe voltage which starts to trigger the control (upper value).

property u_max: The maximum voltage i.e. the one the control reached its maximum action.

property alpha: An approximation factor used by the family function (soft clip). The bigger the factor is the closer the function is to the non-differentiable function.

property epsilon: This value is used to make a smooth inverse function.

classmethod constant(): 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)

Create a control of the type "p_max_u_production".

See also

$P(U)$ control documentation

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 | Q_[float], u_down: float | Q_[float], alpha: float = _DEFAULT_ALPHA, epsilon: float = _DEFAULT_EPSILON)

Create a control of the type "p_max_u_consumption".

See also

$P(U)$ control documentation

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 | Q_[float], u_down: float | Q_[float], u_up: float | Q_[float], u_max: float | Q_[float], alpha: float = _DEFAULT_ALPHA)

Create a control of the type "q_u".

See also

$Q(U)$ control documentation

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: JsonDict, *, include_results: bool = True)

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.

type

property alpha: This value is used to make soft sign function and to build a soft projection function.

property epsilon: 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)

Create an element from a dictionary created with to_dict().

Note

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.

Bases: roseau.load_flow.utils.JsonMixin

Flexible parameters of a flexible load.

This class encapsulate single-phase flexibility information of a flexible load:

The active power roseau.load_flow.models.Control to apply;
The reactive power roseau.load_flow.models.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.

control_p

control_q

projection

property s_max: The apparent power of the flexible load (VA). It is the radius of the feasible circle.

property q_min: The minimum reactive power of the flexible load (VAr).

property q_max: The maximum reactive power of the flexible load (VAr).

classmethod constant()

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)

Build flexible parameters for production P(U) control with a Euclidean projection.

See also

$P(U)$ control documentation

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 | 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)

Build flexible parameters for consumption P(U) control with a Euclidean projection.

See also

$P(U)$ control documentation

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 | 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)

Build flexible parameters for Q(U) control with a Euclidean projection.

See also

$Q(U)$ control documentation

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 | 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: 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)

Build flexible parameters for production P(U) control and Q(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() and q_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 = 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)

Build flexible parameters for consumption P(U) control and Q(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() and q_u() for more details.

classmethod from_dict(data: JsonDict, *, include_results: bool = True)

Create an element from a dictionary created with to_dict().

Note

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])

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)

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: FloatArrayLike1D, power: complex | Q_[complex], ax: Axes | None = None)

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: FloatArrayLike1D, power: complex | Q_[complex], ax: Axes | None = None)

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).