roseau.load_flow.utils

This module contains utility classes and functions for Roseau Load Flow.

Attributes

ALPHA

Phasor rotation operator \(\alpha\), which rotates a phasor vector counterclockwise

ALPHA2

Phasor rotation operator \(\alpha^2\), which rotates a phasor vector clockwise by

DELTA_P

Skin depth of common conductor materials \(\sqrt{\dfrac{\rho}{\pi f \mu_r \mu_0}}\) (mm).

EPSILON_0

Vacuum permittivity \(\varepsilon_0 = 8.8541878128 \times 10^{-12}\) (F/m).

EPSILON_R

Relative permittivity of common insulator materials according to the IEC 60287 standard.

MU_0

Magnetic permeability of the vacuum \(\mu_0 = 4 \pi \times 10^{-7}\) (H/m).

MU_R

Relative magnetic permeability of common conductor materials.

OMEGA

Angular frequency \(\omega = 2 \pi f\) (rad/s).

PI

The famous mathematical constant \(\pi = 3.141592\ldots\).

RHO

Resistivity of common conductor materials (Ohm.m).

TAN_D

Loss angles of common insulator materials according to the IEC 60287 standard.

F

Network frequency \(f = 50\) (Hz).

NegativeSequence

Unit negative sequence components of a three-phase system.

PositiveSequence

Unit positive sequence components of a three-phase system.

ZeroSequence

Unit zero sequence components of a three-phase system.

BranchTypeDtype

Categorical data type used for branch types.

LoadTypeDtype

Categorical data type used for load types.

PhaseDtype

Categorical data type used for the phase of potentials, currents, powers, etc.

SequenceDtype

Categorical data type used for symmetrical components.

VoltagePhaseDtype

Categorical data type used for the phase of voltages and flexible powers only.

Classes

CatalogueMixin

A mixin class for objects which can be built from a catalogue. It adds the from_catalogue class method.

Identifiable

An identifiable object.

JsonMixin

Mixin for classes that can be serialized to and from JSON.

ConductorType

The type of the material of the conductor.

InsulatorType

The type of the insulator for a wire.

LineType

The type of a line.

Package Contents

ALPHA: complex

Phasor rotation operator \(\alpha\), which rotates a phasor vector counterclockwise by 120 degrees when multiplied by it.

Type:

complex

ALPHA2: complex

Phasor rotation operator \(\alpha^2\), which rotates a phasor vector clockwise by 120 degrees when multiplied by it.

Type:

complex

DELTA_P: dict[roseau.load_flow.utils.types.ConductorType, Q_[float]]

Skin depth of common conductor materials \(\sqrt{\dfrac{\rho}{\pi f \mu_r \mu_0}}\) (mm).

EPSILON_0: Q_[float]

Vacuum permittivity \(\varepsilon_0 = 8.8541878128 \times 10^{-12}\) (F/m).

EPSILON_R: dict[roseau.load_flow.utils.types.InsulatorType, Q_[float]]

Relative permittivity of common insulator materials according to the IEC 60287 standard.

MU_0: Q_[float]

Magnetic permeability of the vacuum \(\mu_0 = 4 \pi \times 10^{-7}\) (H/m).

MU_R: dict[roseau.load_flow.utils.types.ConductorType, Q_[float]]

Relative magnetic permeability of common conductor materials.

OMEGA: Q_[float]

Angular frequency \(\omega = 2 \pi f\) (rad/s).

PI: float

The famous mathematical constant \(\pi = 3.141592\ldots\).

RHO: dict[roseau.load_flow.utils.types.ConductorType, Q_[float]]

Resistivity of common conductor materials (Ohm.m).

TAN_D: dict[roseau.load_flow.utils.types.InsulatorType, Q_[float]]

Loss angles of common insulator materials according to the IEC 60287 standard.

F: Q_[float]

Network frequency \(f = 50\) (Hz).

NegativeSequence

Unit negative sequence components of a three-phase system.

Type:

ndarray[complex]

PositiveSequence

Unit positive sequence components of a three-phase system.

Type:

ndarray[complex]

ZeroSequence

Unit zero sequence components of a three-phase system.

Type:

ndarray[complex]

class CatalogueMixin

Bases: Generic[_T]

A mixin class for objects which can be built from a catalogue. It adds the from_catalogue class method.

classmethod catalogue_path() Path
Abstractmethod:

Get the path to the catalogue.

classmethod catalogue_data() _T
Abstractmethod:

Get the catalogue data.

classmethod from_catalogue(**kwargs) typing_extensions.Self
Abstractmethod:

Build an instance from the catalogue.

Keyword Arguments:

create. (Arguments that can be used to select the options of the instance to)

Returns:

The instance of the selected object.

class Identifiable(id: Id)

An identifiable object.

class JsonMixin

Mixin for classes that can be serialized to and from JSON.

classmethod from_dict(data: JsonDict, *, include_results: bool = True) typing_extensions.Self
Abstractmethod:

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.

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

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

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:
  • path – The path to the network data file.

  • include_results – If True (default) and the results of the load flow are included in the file, the results are also loaded into the element.

Returns:

The constructed element.

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

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

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]], "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) 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.

Returns:

The expanded and resolved path of the written file.

BranchTypeDtype

Categorical data type used for branch types.

class ConductorType

Bases: roseau.load_flow._compat.StrEnum

The type of the material of the conductor.

Initialize self. See help(type(self)) for accurate signature.

CU

Copper – Fr = Cuivre.

AL

All Aluminum Conductor (AAC) – Fr = Aluminium.

AM

All Aluminum Alloy Conductor (AAAC) – Fr = Almélec.

AA

Aluminum Conductor Steel Reinforced (ACSR) – Fr = Alu-Acier.

LA

Aluminum Alloy Conductor Steel Reinforced (AACSR) – Fr = Almélec-Acier.

AAC

All Aluminum Conductor (AAC) – Fr = Aluminium.

AAAC

All Aluminum Alloy Conductor (AAAC) – Fr = Almélec.

ACSR

Aluminum Conductor Steel Reinforced (ACSR) – Fr = Alu-Acier.

AACSR

Aluminum Alloy Conductor Steel Reinforced (AACSR) – Fr = Almélec-Acier.

code() str

A code that can be used in conductor type names.

class InsulatorType

Bases: roseau.load_flow._compat.StrEnum

The type of the insulator for a wire.

Initialize self. See help(type(self)) for accurate signature.

UNKNOWN

The material of the insulator is unknown.

HDPE

High-Density PolyEthylene (HDPE) insulation.

MDPE

Medium-Density PolyEthylene (MDPE) insulation.

LDPE

Low-Density PolyEthylene (LDPE) insulation.

XLPE

Cross-linked polyethylene (XLPE) insulation.

EPR

Ethylene-Propylene Rubber (EPR) insulation.

PVC

PolyVinyl Chloride (PVC) insulation.

IP

Impregnated Paper (IP) insulation.

PEX

Alias – Cross-linked polyethylene (XLPE) insulation.

PE

Alias – Medium-Density PolyEthylene (MDPE) insulation.

code() str

A code that can be used in insulator type names.

class LineType

Bases: roseau.load_flow._compat.StrEnum

The type of a line.

Initialize self. See help(type(self)) for accurate signature.

OVERHEAD

An overhead line that can be vertically or horizontally configured – Fr = Aérien.

UNDERGROUND

An underground or a submarine cable – Fr = Souterrain/Sous-Marin.

TWISTED

A twisted line commonly known as Aerial Cable or Aerial Bundled Conductor (ABC) – Fr = Torsadé.

code() str

A code that can be used in line type names.

LoadTypeDtype

Categorical data type used for load types.

PhaseDtype

Categorical data type used for the phase of potentials, currents, powers, etc.

SequenceDtype

Categorical data type used for symmetrical components.

VoltagePhaseDtype

Categorical data type used for the phase of voltages and flexible powers only.