Loads¶

Definition¶

The load element can be used to model consumption loads (with positive active power) as well as generation loads (with negative active power).

Connections¶

A load can be either star-connected or delta-connected depending on whether its phases include a neutral or not.

Star (wye) connection¶

Here is the diagram of a star-connected three-phase load:

European standards

American standards

In Roseau Load Flow, the phases argument of the constructor must contain "n" for star loads.

Note

You can create star connected constant-power or constant-impedance loads even on buses that don’t have a neutral. In this case, the load’s neutral will be floating and its potential can be accessed similar to normal star loads.

Delta connection¶

Here is the diagram of a delta-connected three-phase load:

European standards

American standards

In Roseau Load Flow, the phases argument of the constructor must not contain "n" for delta loads.

Available Results¶

The following results are available for all loads:

Result Accessor	Default Unit	Type	Description
`res_potentials`	\(V\)	complex array	The potentials of each phase of the load
`res_currents`	\(A\)	complex array	The line currents flowing into each phase of the load
`res_powers`	\(V\!A\)	complex array	The line powers flowing into each phase of the load
`res_voltages`	\(V\)	complex array	The phase-to-neutral voltages if the load has a neutral, the phase-to-phase voltages otherwise
`res_inner_currents`	\(A\)	complex array	The currents flowing in each component (dipole) of the load.
`res_inner_powers`	\(V\!A\)	complex array	The powers dissipated by each component (dipole) of the load.

Additionally, the following results are available for loads with a neutral:

Result Accessor	Default Unit	Type	Description
`res_voltages_pn`	\(V\)	complex array	The phase-to-neutral voltages of the load

And the following results are available for loads with more than one phase:

Result Accessor	Default Unit	Type	Description
`res_voltages_pp`	\(V\)	complex array	The phase-to-phase voltages of the load

And the following results are available for three-phase loads:

Result Accessor	Default Unit	Type	Description
`res_voltage_unbalance()`	\(\%\)	number	The voltage unbalance of the load according to the IEC, IEEE or NEMA definition
`res_current_unbalance()`	\(\%\)	number	The Current Unbalance Factor (CUF) of the load

Available models¶

The ZIP model is commonly used to represent electric loads in static grid analysis. This model considers the voltage dependency of loads. ZIP stands for the three load types:

Z = constant impedance load
I = constant current load
P = constant power load

The following load models are available in Roseau Load Flow:

API Reference¶

class AbstractLoad(id, bus, *, phases=None, connect_neutral=None)

An abstract class of an electric load.

The subclasses of this class can be used to model:

star-connected loads using a phases constructor argument containing “n”
delta-connected loads using a phases constructor argument not containing “n”

AbstractLoad constructor.

Parameters:

id (Id) – A unique ID of the load in the network loads.
bus (Bus) – The bus to connect the load to.
phases (str | None) – The phases of the load. A string like "abc" or "an" etc. The bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the load must be present in the phases of the connected bus. Multiphase loads are allowed to be connected to buses that don’t have a neutral if connect_neutral is not set to True.
connect_neutral (bool | None) – Specifies whether the load’s neutral should be connected to the bus’s neutral or left floating. By default, the load’s neutral is connected when the bus has a neutral. If the bus does not have a neutral, the load’s neutral is left floating by default. To override the default behavior, pass an explicit True or False.

element_type: Final = 'load': The type of the element. It is a string like "load" or "line" etc.

property is_flexible: bool

Whether the load is flexible or not. Only PowerLoad can be flexible.

Return type:: bool

property res_inner_currents: Q_[ComplexArray]

The load flow result of the currents that flow in the inner components of the load (A).

Return type:: Q_[ComplexArray]

property res_inner_powers: Q_[ComplexArray]

The load flow result of the powers that flow in the inner components of the load (VA).

Unlike res_powers, the inner powers do not depend on the reference of potentials. They are the physical powers consumed by each of the load dipoles.

Return type:: Q_[ComplexArray]

type: ClassVar[str]

property is_disconnected: bool

Is this element disconnected from the network?

Return type:: bool

disconnect()

Disconnect this element from the network. It cannot be used afterwards.

Return type:: None

property bus: Bus

The bus of the element.

Return type:: Bus

property has_floating_neutral: bool

Does this element have a floating neutral?

Return type:: bool

property res_currents: Q_[ComplexArray]

The load flow result of the element currents (A).

Return type:: Q_[ComplexArray]

property res_powers: Q_[ComplexArray]

The load flow result of the “line powers” flowing into the element (VA).

Return type:: Q_[ComplexArray]

res_current_unbalance()

Calculate the current unbalance (CU) on this element.

The calculation depends on the definition of current unbalance:

Current Unbalance Factor (CUF):

\(CUF = \dfrac{I_\mathrm{2}}{I_\mathrm{1}} \times 100 \, (\%)\)

Where \(I_{\mathrm{2}}\) is the magnitude of the negative-sequence (inverse) current and \(I_{\mathrm{1}}\) is the magnitude of the positive-sequence (direct) current.

Return type:: Q_[float]

allowed_phases: Final

The allowed phases for a terminal element are:

P-P-P or P-P-P-N: "abc", "abcn"
P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"
P-N: "an", "bn", "cn"

property phases: str

The phases of the element.

Return type:: str

property voltage_phases: list[str]

The phases of the voltages of the element.

Return type:: list[str]

property voltage_phases_pp: list[str]

The phases of the phase-to-phase voltages of the element.

Return type:: list[str]

property voltage_phases_pn: list[str]

The phases of the phase-to-neutral voltages of the element.

Return type:: list[str]

property res_potentials: Q_[ComplexArray]

The load flow result of the element potentials (V).

Return type:: Q_[ComplexArray]

property res_voltages: Q_[ComplexArray]

The load flow result of the element voltages (V).

If the element has a neutral, the voltages are phase-to-neutral voltages for existing phases in the order [Van, Vbn, Vcn]. If the element does not have a neutral, the voltages are phase-to-phase for existing phases in the order [Vab, Vbc, Vca].

See also

res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pp: Q_[ComplexArray]

The load flow result of the element’s phase-to-phase voltages (V).

Raises an error if the element has only one phase.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pn: Q_[ComplexArray]

The load flow result of the element’s phase-to-neutral voltages (V).

Raises an error if the element does not have a neutral.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.

Return type:: Q_[ComplexArray]

res_voltage_unbalance(definition='VUF')

Calculate the voltage unbalance (VU) on this element.

Parameters:

definition (Literal['VUF', 'LVUR', 'PVUR']) –

The definition of the voltage unbalance, one of the following:

VUF: The Voltage Unbalance Factor defined by the IEC, also called the “True Definition” (default):

\(VUF = \dfrac{V_\mathrm{2}}{V_\mathrm{1}} \times 100 \, (\%)\)

Where \(V_{\mathrm{1}}\) and \(V_{\mathrm{2}}\) are the magnitudes of the positive-sequence and negative-sequence voltages, respectively.
LVUR: The Line Voltage Unbalance Rate defined by NEMA:

\(LVUR = \dfrac{\Delta V_\mathrm{Line,Max}}{\Delta V_\mathrm{Line,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Line,Mean}\) is the arithmetic mean of the line voltages and \(\Delta V_\mathrm{Line,Max}\) is the maximum deviation between the measured line voltages and \(\Delta V_\mathrm{Line,Mean}\).
PVUR: The Phase Voltage Unbalance Rate defined by IEEE:

\(PVUR = \dfrac{\Delta V_\mathrm{Phase,Max}}{\Delta V_\mathrm{Phase,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Phase,Mean}\) is the arithmetic mean of the phase voltages and \(\Delta V_\mathrm{Phase,Max}\) is the maximum deviation between the measured phase voltages and \(\Delta V_\mathrm{Phase,Mean}\).

Returns:

The voltage unbalance in percent.

Return type:

Q_[float]

is_multi_phase: Final = True: Is the object multi-phase?

property network: _N_co | None

Return the network the element belong to (if any).

Return type:: _N_co | None

id

to_dict(*, include_results=True)

Convert the element to a dictionary.

Parameters:: include_results (bool) – 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.
Return type:: JsonDict

to_json(path, *, include_results=True, indent=True)

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 (StrPath) – The path to the output file to write the network to.
include_results (bool) – 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 (bool) – 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.

Return type:

Path

results_to_dict(full=False)

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 (bool) – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.
Return type:: JsonDict

results_to_json(path, *, full=False, indent=True)

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 (StrPath) – The path to the output file to write the results to.
full (bool) – 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 (bool) – 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.

Return type:

Path

class ImpedanceLoad(id, bus, *, impedances, phases=None, connect_neutral=None)

A constant impedance load.

ImpedanceLoad constructor.

Parameters:

id (Id) – A unique ID of the load in the network loads.
bus (Bus) – The bus to connect the load to.
impedances (ComplexScalarOrArrayLike1D) –
A single impedance value or an array-like of impedance values for each phase component. Either complex values (Ohms) or a Quantity of complex values.

When a scalar value is provided, it creates a balanced load with the same impedance for each phase. To create an unbalanced load, provide a vector of impedance values with the same length as the number of components of the load.
phases (str | None) – The phases of the load. A string like "abc" or "an" etc. The bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the load must be present in the phases of the connected bus. Multiphase loads are allowed to be connected to buses that don’t have a neutral if connect_neutral is not set to True.
connect_neutral (bool | None) – Specifies whether the load’s neutral should be connected to the bus’s neutral or left floating. By default, the load’s neutral is connected when the bus has a neutral. If the bus does not have a neutral, the load’s neutral is left floating by default. To override the default behavior, pass an explicit True or False.

type: Final = 'impedance'

property impedances: Q_[ComplexArray]

The impedances of the load (Ohms).

Return type:: Q_[ComplexArray]

element_type: Final = 'load': The type of the element. It is a string like "load" or "line" etc.

property is_flexible: bool

Whether the load is flexible or not. Only PowerLoad can be flexible.

Return type:: bool

property res_inner_currents: Q_[ComplexArray]

The load flow result of the currents that flow in the inner components of the load (A).

Return type:: Q_[ComplexArray]

property res_inner_powers: Q_[ComplexArray]

The load flow result of the powers that flow in the inner components of the load (VA).

Unlike res_powers, the inner powers do not depend on the reference of potentials. They are the physical powers consumed by each of the load dipoles.

Return type:: Q_[ComplexArray]

property is_disconnected: bool

Is this element disconnected from the network?

Return type:: bool

disconnect()

Disconnect this element from the network. It cannot be used afterwards.

Return type:: None

property bus: Bus

The bus of the element.

Return type:: Bus

property has_floating_neutral: bool

Does this element have a floating neutral?

Return type:: bool

property res_currents: Q_[ComplexArray]

The load flow result of the element currents (A).

Return type:: Q_[ComplexArray]

property res_powers: Q_[ComplexArray]

The load flow result of the “line powers” flowing into the element (VA).

Return type:: Q_[ComplexArray]

res_current_unbalance()

Calculate the current unbalance (CU) on this element.

The calculation depends on the definition of current unbalance:

Current Unbalance Factor (CUF):

\(CUF = \dfrac{I_\mathrm{2}}{I_\mathrm{1}} \times 100 \, (\%)\)

Where \(I_{\mathrm{2}}\) is the magnitude of the negative-sequence (inverse) current and \(I_{\mathrm{1}}\) is the magnitude of the positive-sequence (direct) current.

Return type:: Q_[float]

allowed_phases: Final

The allowed phases for a terminal element are:

P-P-P or P-P-P-N: "abc", "abcn"
P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"
P-N: "an", "bn", "cn"

property phases: str

The phases of the element.

Return type:: str

property voltage_phases: list[str]

The phases of the voltages of the element.

Return type:: list[str]

property voltage_phases_pp: list[str]

The phases of the phase-to-phase voltages of the element.

Return type:: list[str]

property voltage_phases_pn: list[str]

The phases of the phase-to-neutral voltages of the element.

Return type:: list[str]

property res_potentials: Q_[ComplexArray]

The load flow result of the element potentials (V).

Return type:: Q_[ComplexArray]

property res_voltages: Q_[ComplexArray]

The load flow result of the element voltages (V).

See also

res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pp: Q_[ComplexArray]

The load flow result of the element’s phase-to-phase voltages (V).

Raises an error if the element has only one phase.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pn: Q_[ComplexArray]

The load flow result of the element’s phase-to-neutral voltages (V).

Raises an error if the element does not have a neutral.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.

Return type:: Q_[ComplexArray]

res_voltage_unbalance(definition='VUF')

Calculate the voltage unbalance (VU) on this element.

Parameters:

definition (Literal['VUF', 'LVUR', 'PVUR']) –

The definition of the voltage unbalance, one of the following:

VUF: The Voltage Unbalance Factor defined by the IEC, also called the “True Definition” (default):

\(VUF = \dfrac{V_\mathrm{2}}{V_\mathrm{1}} \times 100 \, (\%)\)

Where \(V_{\mathrm{1}}\) and \(V_{\mathrm{2}}\) are the magnitudes of the positive-sequence and negative-sequence voltages, respectively.
LVUR: The Line Voltage Unbalance Rate defined by NEMA:

\(LVUR = \dfrac{\Delta V_\mathrm{Line,Max}}{\Delta V_\mathrm{Line,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Line,Mean}\) is the arithmetic mean of the line voltages and \(\Delta V_\mathrm{Line,Max}\) is the maximum deviation between the measured line voltages and \(\Delta V_\mathrm{Line,Mean}\).
PVUR: The Phase Voltage Unbalance Rate defined by IEEE:

\(PVUR = \dfrac{\Delta V_\mathrm{Phase,Max}}{\Delta V_\mathrm{Phase,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Phase,Mean}\) is the arithmetic mean of the phase voltages and \(\Delta V_\mathrm{Phase,Max}\) is the maximum deviation between the measured phase voltages and \(\Delta V_\mathrm{Phase,Mean}\).

Returns:

The voltage unbalance in percent.

Return type:

Q_[float]

is_multi_phase: Final = True: Is the object multi-phase?

property network: _N_co | None

Return the network the element belong to (if any).

Return type:: _N_co | None

id

to_dict(*, include_results=True)

Convert the element to a dictionary.

Parameters:: include_results (bool) – 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.
Return type:: JsonDict

to_json(path, *, include_results=True, indent=True)

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 (StrPath) – The path to the output file to write the network to.
include_results (bool) – 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 (bool) – 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.

Return type:

Path

results_to_dict(full=False)

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 (bool) – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.
Return type:: JsonDict

results_to_json(path, *, full=False, indent=True)

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 (StrPath) – The path to the output file to write the results to.
full (bool) – 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 (bool) – 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.

Return type:

Path

class CurrentLoad(id, bus, *, currents, phases=None)

A constant current load.

CurrentLoad constructor.

Parameters:

id (Id) – A unique ID of the load in the network loads.
bus (Bus) – The bus to connect the load to.
currents (ComplexScalarOrArrayLike1D) –
A single current value or an array-like of current values for each phase component. Either complex values (A) or a Quantity of complex values. The complex currents provided define the currents magnitudes and their phase shift from the voltages of the load. For example, a current of 10*exp(-90°j) represents an inductive constant current of 10 A.

When a scalar value is provided, it creates a balanced load with the same current for each phase. To create an unbalanced load, provide a vector of current values with the same length as the number of components of the load.
phases (str | None) – The phases of the load. A string like "abc" or "an" etc. The bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the load must be present in the phases of the connected bus.

type: Final = 'current'

property currents: Q_[ComplexArray]

The currents of the load (Amps).

Setting the currents will update the load’s currents and invalidate the network results.

Return type:: Q_[ComplexArray]

element_type: Final = 'load': The type of the element. It is a string like "load" or "line" etc.

property is_flexible: bool

Whether the load is flexible or not. Only PowerLoad can be flexible.

Return type:: bool

property res_inner_currents: Q_[ComplexArray]

The load flow result of the currents that flow in the inner components of the load (A).

Return type:: Q_[ComplexArray]

property res_inner_powers: Q_[ComplexArray]

The load flow result of the powers that flow in the inner components of the load (VA).

Unlike res_powers, the inner powers do not depend on the reference of potentials. They are the physical powers consumed by each of the load dipoles.

Return type:: Q_[ComplexArray]

property is_disconnected: bool

Is this element disconnected from the network?

Return type:: bool

disconnect()

Disconnect this element from the network. It cannot be used afterwards.

Return type:: None

property bus: Bus

The bus of the element.

Return type:: Bus

property has_floating_neutral: bool

Does this element have a floating neutral?

Return type:: bool

property res_currents: Q_[ComplexArray]

The load flow result of the element currents (A).

Return type:: Q_[ComplexArray]

property res_powers: Q_[ComplexArray]

The load flow result of the “line powers” flowing into the element (VA).

Return type:: Q_[ComplexArray]

res_current_unbalance()

Calculate the current unbalance (CU) on this element.

The calculation depends on the definition of current unbalance:

Current Unbalance Factor (CUF):

\(CUF = \dfrac{I_\mathrm{2}}{I_\mathrm{1}} \times 100 \, (\%)\)

Where \(I_{\mathrm{2}}\) is the magnitude of the negative-sequence (inverse) current and \(I_{\mathrm{1}}\) is the magnitude of the positive-sequence (direct) current.

Return type:: Q_[float]

allowed_phases: Final

The allowed phases for a terminal element are:

P-P-P or P-P-P-N: "abc", "abcn"
P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"
P-N: "an", "bn", "cn"

property phases: str

The phases of the element.

Return type:: str

property voltage_phases: list[str]

The phases of the voltages of the element.

Return type:: list[str]

property voltage_phases_pp: list[str]

The phases of the phase-to-phase voltages of the element.

Return type:: list[str]

property voltage_phases_pn: list[str]

The phases of the phase-to-neutral voltages of the element.

Return type:: list[str]

property res_potentials: Q_[ComplexArray]

The load flow result of the element potentials (V).

Return type:: Q_[ComplexArray]

property res_voltages: Q_[ComplexArray]

The load flow result of the element voltages (V).

See also

res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pp: Q_[ComplexArray]

The load flow result of the element’s phase-to-phase voltages (V).

Raises an error if the element has only one phase.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pn: Q_[ComplexArray]

The load flow result of the element’s phase-to-neutral voltages (V).

Raises an error if the element does not have a neutral.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.

Return type:: Q_[ComplexArray]

res_voltage_unbalance(definition='VUF')

Calculate the voltage unbalance (VU) on this element.

Parameters:

definition (Literal['VUF', 'LVUR', 'PVUR']) –

The definition of the voltage unbalance, one of the following:

VUF: The Voltage Unbalance Factor defined by the IEC, also called the “True Definition” (default):

\(VUF = \dfrac{V_\mathrm{2}}{V_\mathrm{1}} \times 100 \, (\%)\)

Where \(V_{\mathrm{1}}\) and \(V_{\mathrm{2}}\) are the magnitudes of the positive-sequence and negative-sequence voltages, respectively.
LVUR: The Line Voltage Unbalance Rate defined by NEMA:

\(LVUR = \dfrac{\Delta V_\mathrm{Line,Max}}{\Delta V_\mathrm{Line,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Line,Mean}\) is the arithmetic mean of the line voltages and \(\Delta V_\mathrm{Line,Max}\) is the maximum deviation between the measured line voltages and \(\Delta V_\mathrm{Line,Mean}\).
PVUR: The Phase Voltage Unbalance Rate defined by IEEE:

\(PVUR = \dfrac{\Delta V_\mathrm{Phase,Max}}{\Delta V_\mathrm{Phase,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Phase,Mean}\) is the arithmetic mean of the phase voltages and \(\Delta V_\mathrm{Phase,Max}\) is the maximum deviation between the measured phase voltages and \(\Delta V_\mathrm{Phase,Mean}\).

Returns:

The voltage unbalance in percent.

Return type:

Q_[float]

is_multi_phase: Final = True: Is the object multi-phase?

property network: _N_co | None

Return the network the element belong to (if any).

Return type:: _N_co | None

id

to_dict(*, include_results=True)

Convert the element to a dictionary.

Parameters:: include_results (bool) – 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.
Return type:: JsonDict

to_json(path, *, include_results=True, indent=True)

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 (StrPath) – The path to the output file to write the network to.
include_results (bool) – 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 (bool) – 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.

Return type:

Path

results_to_dict(full=False)

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 (bool) – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.
Return type:: JsonDict

results_to_json(path, *, full=False, indent=True)

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 (StrPath) – The path to the output file to write the results to.
full (bool) – 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 (bool) – 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.

Return type:

Path

class PowerLoad(id, bus, *, powers, phases=None, flexible_params=None, connect_neutral=None)

A constant power load.

PowerLoad constructor.

Parameters:

id (Id) – A unique ID of the load in the network loads.
bus (Bus) – The bus to connect the load to.
powers (ComplexScalarOrArrayLike1D) –
A single power value or an array-like of power values for each phase component. Either complex values (VA) or a Quantity of complex values.

When a scalar value is provided, it creates a balanced load with the same power for each phase. The scalar value passed is assumed to be the power of each component of the load, not the total multi-phase power. To create an unbalanced load, provide a vector of power values with the same length as the number of components of the load.
phases (str | None) – The phases of the load. A string like "abc" or "an" etc. The bus phases are used by default. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the load must be present in the phases of the connected bus. Multiphase loads are allowed to be connected to buses that don’t have a neutral if connect_neutral is not set to True.
flexible_params (FlexibleParameter | Iterable[FlexibleParameter] | None) –
A FlexibleParameters object to make the load flexible, i.e., controllable based on the voltage using the commonly known P(U) and Q(U) controls. These parameters are used to compute the flexible powers of the load which could be different from the input powers.

It is also possible to pass an iterable of FlexibleParameter objects to create unbalanced control settings, one for each phase of the load.
connect_neutral (bool | None) – Specifies whether the load’s neutral should be connected to the bus’s neutral or left floating. By default, the load’s neutral is connected when the bus has a neutral. If the bus does not have a neutral, the load’s neutral is left floating by default. To override the default behavior, pass an explicit True or False.

type: Final = 'power'

property powers: Q_[ComplexArray]

The powers of the load (VA).

Setting the powers will update the load’s power values and invalidate the network results.

Return type:: Q_[ComplexArray]

property flexible_params: list[FlexibleParameter] | None

The flexible parameters of the load or None if the load is not flexible.

If the load is flexible, this property returns a list of FlexibleParameter objects that define the control settings of each phase of the load.

Return type:: list[FlexibleParameter] | None

property is_flexible: bool

Whether the load is flexible or not. Only PowerLoad can be flexible.

Return type:: bool

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 “inner powers” of the load instead of the “line powers” flowing into the load connection points. This property is equivalent to the res_inner_powers property, not to the res_powers property. Prefer using res_inner_powers because it is available for all loads.

Return type:: Q_[ComplexArray]

element_type: Final = 'load': The type of the element. It is a string like "load" or "line" etc.

property res_inner_currents: Q_[ComplexArray]

The load flow result of the currents that flow in the inner components of the load (A).

Return type:: Q_[ComplexArray]

property res_inner_powers: Q_[ComplexArray]

The load flow result of the powers that flow in the inner components of the load (VA).

Unlike res_powers, the inner powers do not depend on the reference of potentials. They are the physical powers consumed by each of the load dipoles.

Return type:: Q_[ComplexArray]

property is_disconnected: bool

Is this element disconnected from the network?

Return type:: bool

disconnect()

Disconnect this element from the network. It cannot be used afterwards.

Return type:: None

property bus: Bus

The bus of the element.

Return type:: Bus

property has_floating_neutral: bool

Does this element have a floating neutral?

Return type:: bool

property res_currents: Q_[ComplexArray]

The load flow result of the element currents (A).

Return type:: Q_[ComplexArray]

property res_powers: Q_[ComplexArray]

The load flow result of the “line powers” flowing into the element (VA).

Return type:: Q_[ComplexArray]

res_current_unbalance()

Calculate the current unbalance (CU) on this element.

The calculation depends on the definition of current unbalance:

Current Unbalance Factor (CUF):

\(CUF = \dfrac{I_\mathrm{2}}{I_\mathrm{1}} \times 100 \, (\%)\)

Where \(I_{\mathrm{2}}\) is the magnitude of the negative-sequence (inverse) current and \(I_{\mathrm{1}}\) is the magnitude of the positive-sequence (direct) current.

Return type:: Q_[float]

allowed_phases: Final

The allowed phases for a terminal element are:

P-P-P or P-P-P-N: "abc", "abcn"
P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"
P-N: "an", "bn", "cn"

property phases: str

The phases of the element.

Return type:: str

property voltage_phases: list[str]

The phases of the voltages of the element.

Return type:: list[str]

property voltage_phases_pp: list[str]

The phases of the phase-to-phase voltages of the element.

Return type:: list[str]

property voltage_phases_pn: list[str]

The phases of the phase-to-neutral voltages of the element.

Return type:: list[str]

property res_potentials: Q_[ComplexArray]

The load flow result of the element potentials (V).

Return type:: Q_[ComplexArray]

property res_voltages: Q_[ComplexArray]

The load flow result of the element voltages (V).

See also

res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pp: Q_[ComplexArray]

The load flow result of the element’s phase-to-phase voltages (V).

Raises an error if the element has only one phase.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pn: The phase-to-neutral voltages of the element. Raises if the element does not have a neutral.

Return type:: Q_[ComplexArray]

property res_voltages_pn: Q_[ComplexArray]

The load flow result of the element’s phase-to-neutral voltages (V).

Raises an error if the element does not have a neutral.

See also

res_voltages: Get the voltages in the natural representation of the element (phase-to-neutral if it has a neutral, phase-to-phase otherwise).
res_voltages_pp: The phase-to-phase voltages of the element. Raises if the element has only one phase.

Return type:: Q_[ComplexArray]

res_voltage_unbalance(definition='VUF')

Calculate the voltage unbalance (VU) on this element.

Parameters:

definition (Literal['VUF', 'LVUR', 'PVUR']) –

The definition of the voltage unbalance, one of the following:

VUF: The Voltage Unbalance Factor defined by the IEC, also called the “True Definition” (default):

\(VUF = \dfrac{V_\mathrm{2}}{V_\mathrm{1}} \times 100 \, (\%)\)

Where \(V_{\mathrm{1}}\) and \(V_{\mathrm{2}}\) are the magnitudes of the positive-sequence and negative-sequence voltages, respectively.
LVUR: The Line Voltage Unbalance Rate defined by NEMA:

\(LVUR = \dfrac{\Delta V_\mathrm{Line,Max}}{\Delta V_\mathrm{Line,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Line,Mean}\) is the arithmetic mean of the line voltages and \(\Delta V_\mathrm{Line,Max}\) is the maximum deviation between the measured line voltages and \(\Delta V_\mathrm{Line,Mean}\).
PVUR: The Phase Voltage Unbalance Rate defined by IEEE:

\(PVUR = \dfrac{\Delta V_\mathrm{Phase,Max}}{\Delta V_\mathrm{Phase,Mean}} \times 100 (\%)\).

Where \(\Delta V_\mathrm{Phase,Mean}\) is the arithmetic mean of the phase voltages and \(\Delta V_\mathrm{Phase,Max}\) is the maximum deviation between the measured phase voltages and \(\Delta V_\mathrm{Phase,Mean}\).

Returns:

The voltage unbalance in percent.

Return type:

Q_[float]

is_multi_phase: Final = True: Is the object multi-phase?

property network: _N_co | None

Return the network the element belong to (if any).

Return type:: _N_co | None

id

to_dict(*, include_results=True)

Convert the element to a dictionary.

Parameters:: include_results (bool) – 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.
Return type:: JsonDict

to_json(path, *, include_results=True, indent=True)

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 (StrPath) – The path to the output file to write the network to.
include_results (bool) – 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 (bool) – 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.

Return type:

Path

results_to_dict(full=False)

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 (bool) – If True, all the results are added in the resulting dictionary. False by default.
Returns:: The dictionary of results.
Return type:: JsonDict

results_to_json(path, *, full=False, indent=True)

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 (StrPath) – The path to the output file to write the results to.
full (bool) – 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 (bool) – 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.

Return type:

Path