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

Available Results¶

In addition to the results available for all loads, as described here, the following results are available for flexible loads:

Result Accessor	Default Unit	Type	Description
`res_flexible_powers`	$V\!A$	complex array	The powers in the inner components of the load

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

property u_min: Q_[float]: The minimum voltage i.e. the one the control reached the maximum action.

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

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

property u_max: Q_[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 | Q_[Float], u_max: Float | Q_[Float], alpha: Float = _DEFAULT_ALPHA, epsilon: Float = _DEFAULT_EPSILON) → Self

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

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

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, copy: bool = True) → Self

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

Parameters:

data – The dictionary containing the data.
include_results – If True (default) and the results of the load flow are included in the dictionary, the results are also loaded.
copy – If True (default), the input dictionary is deep-copied before processing so the original is never modified. Pass False when the dictionary is a throwaway (e.g. freshly parsed from JSON) to avoid the copy overhead.

Returns:

The constructed instance.

classmethod from_json(path: StrPath, *, include_results: bool = True) → Self

Construct an instance from a JSON file created with to_json().

Parameters:

path – The path to the data file.
include_results – If True (default) and the results of the load flow are included in the file, the results are also loaded.

Returns:

The constructed instance.

to_dict(*, include_results: bool = True) → JsonDict

Convert the element to a dictionary.

Parameters:: include_results – If True (default), the results of the load flow are included in the dictionary. If no results are available, this option is ignored.
Returns:: A JSON serializable dictionary with the element’s data.

to_json(path: StrPath, *, include_results: bool = True, indent: bool = True) → Path

Save this element to a JSON file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

path – The path to the output file to write the network to.
include_results – If True (default), the results of the load flow are included in the JSON file. If no results are available, this option is ignored.
indent – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

results_to_dict(full: bool = False) → JsonDict

Return the results of the element as a dictionary.

The results dictionary of an element contains the ID of the element, its phases, and the result. For example, bus.results_to_dict() returns a dictionary with the form:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]]}

Note that complex values (like potentials in the example above) are stored as list of [real part, imaginary part] so that it is JSON-serializable

Using the full argument, bus.results_to_dict(full=True) leads to the following results:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]], "voltages": [[230.0, 0.0]]}

The results dictionary of the network contains the results of all of its elements grouped by the element type. It has the form:

{
    "buses": [bus1_dict, bus2_dict, ...],
    "lines": [line1_dict, line2_dict, ...],
    "transformers": [transformer1_dict, transformer2_dict, ...],
    "switches": [switch1_dict, switch2_dict, ...],
    "loads": [load1_dict, load2_dict, ...],
    "sources": [source1_dict, source2_dict, ...],
    "grounds": [ground1_dict, ground2_dict, ...],
    "potential_refs": [p_ref1_dict, p_ref2_dict, ...],
}

where each dict is produced by the element’s results_to_dict() method.

Parameters:: full – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.

results_to_json(path: StrPath, *, full: bool = False, indent: bool = True) → Path

Write the results of the load flow to a json file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

path – The path to the output file to write the results to.
full – If True, all the results are added in the resulting dictionary, including results computed from other results (such as voltages that could be computed from potentials). False by default.
indent – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

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

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, copy: bool = True) → Self

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

Parameters:

data – The dictionary containing the data.
include_results – If True (default) and the results of the load flow are included in the dictionary, the results are also loaded.
copy – If True (default), the input dictionary is deep-copied before processing so the original is never modified. Pass False when the dictionary is a throwaway (e.g. freshly parsed from JSON) to avoid the copy overhead.

Returns:

The constructed instance.

classmethod from_json(path: StrPath, *, include_results: bool = True) → Self

Construct an instance from a JSON file created with to_json().

Parameters:

path – The path to the data file.
include_results – If True (default) and the results of the load flow are included in the file, the results are also loaded.

Returns:

The constructed instance.

to_dict(*, include_results: bool = True) → JsonDict

Convert the element to a dictionary.

Parameters:: include_results – If True (default), the results of the load flow are included in the dictionary. If no results are available, this option is ignored.
Returns:: A JSON serializable dictionary with the element’s data.

to_json(path: StrPath, *, include_results: bool = True, indent: bool = True) → Path

Save this element to a JSON file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

path – The path to the output file to write the network to.
include_results – If True (default), the results of the load flow are included in the JSON file. If no results are available, this option is ignored.
indent – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

results_to_dict(full: bool = False) → JsonDict

Return the results of the element as a dictionary.

The results dictionary of an element contains the ID of the element, its phases, and the result. For example, bus.results_to_dict() returns a dictionary with the form:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]]}

Note that complex values (like potentials in the example above) are stored as list of [real part, imaginary part] so that it is JSON-serializable

Using the full argument, bus.results_to_dict(full=True) leads to the following results:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]], "voltages": [[230.0, 0.0]]}

The results dictionary of the network contains the results of all of its elements grouped by the element type. It has the form:

{
    "buses": [bus1_dict, bus2_dict, ...],
    "lines": [line1_dict, line2_dict, ...],
    "transformers": [transformer1_dict, transformer2_dict, ...],
    "switches": [switch1_dict, switch2_dict, ...],
    "loads": [load1_dict, load2_dict, ...],
    "sources": [source1_dict, source2_dict, ...],
    "grounds": [ground1_dict, ground2_dict, ...],
    "potential_refs": [p_ref1_dict, p_ref2_dict, ...],
}

where each dict is produced by the element’s results_to_dict() method.

Parameters:: full – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.

results_to_json(path: StrPath, *, full: bool = False, indent: bool = True) → Path

Write the results of the load flow to a json file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

path – The path to the output file to write the results to.
full – If True, all the results are added in the resulting dictionary, including results computed from other results (such as voltages that could be computed from potentials). False by default.
indent – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

Bases: roseau.load_flow.utils.JsonMixin

Flexible parameters of a flexible load.

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

The active power Control to apply;
The reactive power Control to apply;
The Projection to use when dealing with voltage violations;
The apparent power of the flexible load (VA). This is the maximum power the load can consume/produce. It is the radius of the feasible circle used by the projection

For multi-phase loads, you need to use a FlexibleParameter instance per phase.

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: Q_[float]: The apparent power of the flexible load (VA). It is the radius of the feasible circle.

property q_min: Q_[float]: The minimum reactive power of the flexible load (VAr).

property q_max: Q_[float]: The maximum reactive power of the flexible load (VAr).

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

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

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

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

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

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.

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, Q_[ComplexArray]]

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) → tuple[Axes, Q_[ComplexArray]]

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) → tuple[Axes, Q_[ComplexArray]]

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

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

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

Parameters:

data – The dictionary containing the data.
include_results – If True (default) and the results of the load flow are included in the dictionary, the results are also loaded.
copy – If True (default), the input dictionary is deep-copied before processing so the original is never modified. Pass False when the dictionary is a throwaway (e.g. freshly parsed from JSON) to avoid the copy overhead.

Returns:

The constructed instance.

classmethod from_json(path: StrPath, *, include_results: bool = True) → Self

Construct an instance from a JSON file created with to_json().

Parameters:

path – The path to the data file.
include_results – If True (default) and the results of the load flow are included in the file, the results are also loaded.

Returns:

The constructed instance.

to_dict(*, include_results: bool = True) → JsonDict

Convert the element to a dictionary.

Parameters:: include_results – If True (default), the results of the load flow are included in the dictionary. If no results are available, this option is ignored.
Returns:: A JSON serializable dictionary with the element’s data.

to_json(path: StrPath, *, include_results: bool = True, indent: bool = True) → Path

Save this element to a JSON file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

path – The path to the output file to write the network to.
include_results – If True (default), the results of the load flow are included in the JSON file. If no results are available, this option is ignored.
indent – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.

results_to_dict(full: bool = False) → JsonDict

Return the results of the element as a dictionary.

The results dictionary of an element contains the ID of the element, its phases, and the result. For example, bus.results_to_dict() returns a dictionary with the form:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]]}

Note that complex values (like potentials in the example above) are stored as list of [real part, imaginary part] so that it is JSON-serializable

Using the full argument, bus.results_to_dict(full=True) leads to the following results:

{"id": "bus1", "phases": "an", "potentials": [[230.0, 0.0], [0.0, 0.0]], "voltages": [[230.0, 0.0]]}

The results dictionary of the network contains the results of all of its elements grouped by the element type. It has the form:

{
    "buses": [bus1_dict, bus2_dict, ...],
    "lines": [line1_dict, line2_dict, ...],
    "transformers": [transformer1_dict, transformer2_dict, ...],
    "switches": [switch1_dict, switch2_dict, ...],
    "loads": [load1_dict, load2_dict, ...],
    "sources": [source1_dict, source2_dict, ...],
    "grounds": [ground1_dict, ground2_dict, ...],
    "potential_refs": [p_ref1_dict, p_ref2_dict, ...],
}

where each dict is produced by the element’s results_to_dict() method.

Parameters:: full – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.

results_to_json(path: StrPath, *, full: bool = False, indent: bool = True) → Path

Write the results of the load flow to a json file.

Note

The path is expanded then resolved before writing the file.

Warning

If the file exists, it will be overwritten.

Parameters:

path – The path to the output file to write the results to.
full – If True, all the results are added in the resulting dictionary, including results computed from other results (such as voltages that could be computed from potentials). False by default.
indent – If True (default), the JSON output is pretty-printed with 2-space indentation. Set to False for compact output.

Returns:

The expanded and resolved path of the written file.