Lines#

Definition#

Lines are modeled using passive components lumped in a PI section. The lumped parameters are defined using the series impedance matrix \(\underline{Z}\) and the shunt admittance matrix \(\underline{Y}\).

Matrices definition#

Before diving into the different line models, lets define the series impedance matrix \(\underline{Z}\), and the shunt admittance matrix \(\underline{Y}\) used to model the lines.

Series impedance matrix#

The series impedance matrix \(\underline{Z}\), in \(\Omega\), consists of the series resistance of the conductors (\(R\in{\mathbb{R}^+}^4\)), the self-inductances (\(L\in\mathbb{R}^4\)) and the mutual inductances (\(M\in\mathbb{R}^{12}\)).

\[\begin{split}\begin{aligned} \underline{Z} &= R + j \cdot X \\ \underline{Z} &= \begin{pmatrix} \underline{Z_{\mathrm{aa}}} & \underline{Z_{\mathrm{ab}}} & \underline{Z_{\mathrm{ac}}} & \underline{Z_{\mathrm{an}}}\\ \underline{Z_{\mathrm{ba}}} & \underline{Z_{\mathrm{bb}}} & \underline{Z_{\mathrm{bc}}} & \underline{Z_{\mathrm{bn}}}\\ \underline{Z_{\mathrm{ca}}} & \underline{Z_{\mathrm{cb}}} & \underline{Z_{\mathrm{cc}}} & \underline{Z_{\mathrm{cn}}}\\ \underline{Z_{\mathrm{na}}} & \underline{Z_{\mathrm{nb}}} & \underline{Z_{\mathrm{nc}}} & \underline{Z_{\mathrm{nn}}}\\ \end{pmatrix}\\ \underline{Z} &= \underbrace{ \begin{pmatrix} R_{\mathrm{a}} & 0 & 0 & 0\\ 0 & R_{\mathrm{b}} & 0 & 0\\ 0 & 0 & R_{\mathrm{c}} & 0\\ 0 & 0 & 0 & R_{\mathrm{n}}\\ \end{pmatrix} }_{R} + j \cdot \underbrace{ \omega \cdot \begin{pmatrix} L_{\mathrm{a}} & M_{\mathrm{ab}} & M_{\mathrm{ac}} & M_{\mathrm{an}}\\ M_{\mathrm{ba}} & L_{\mathrm{b}} & M_{\mathrm{bc}} & M_{\mathrm{bn}}\\ M_{\mathrm{ca}} & M_{\mathrm{cb}} & L_{\mathrm{c}} & M_{\mathrm{cn}}\\ M_{\mathrm{na}} & M_{\mathrm{nb}} & M_{\mathrm{nc}} & L_{\mathrm{n}}\\ \end{pmatrix} }_{X} \end{aligned}\end{split}\]

Admittance matrix#

Warning

The admittance matrix \(\underline{y}\) shouldn’t be confused with the shunt admittance matrix \(\underline{Y}\) defined below.

\(\underline{y}\) represents the admittances between each node, while \(\underline{Y}\) is used to compute the currents and voltages.

\[\begin{split}\begin{aligned} \underline{y} &= G + j \cdot B \\ \underline{y} &= \begin{pmatrix} \underline{y_{\mathrm{ag}}} & \underline{y_{\mathrm{ab}}} & \underline{y_{\mathrm{ac}}} & \underline{y_{\mathrm{an}}}\\ \underline{y_{\mathrm{ab}}} & \underline{y_{\mathrm{bg}}} & \underline{y_{\mathrm{bc}}} & \underline{y_{\mathrm{bn}}}\\ \underline{y_{\mathrm{ac}}} & \underline{y_{\mathrm{bc}}} & \underline{y_{\mathrm{cg}}} & \underline{y_{\mathrm{cn}}}\\ \underline{y_{\mathrm{an}}} & \underline{y_{\mathrm{bn}}} & \underline{y_{\mathrm{cn}}} & \underline{y_{\mathrm{ng}}} \end{pmatrix}\\ \underline{y} &= \underbrace{ \begin{pmatrix} G_{\mathrm{a}} & 0 & 0 & 0\\ 0 & G_{\mathrm{b}} & 0 & 0\\ 0 & 0 & G_{\mathrm{c}} & 0\\ 0 & 0 & 0 & G_{\mathrm{n}} \end{pmatrix} }_{G} + j \cdot \underbrace{ \omega \cdot \begin{pmatrix} C_{\mathrm{a}} & C_{\mathrm{ab}} & C_{\mathrm{ac}} & C_{\mathrm{an}}\\ C_{\mathrm{ab}} & C_{\mathrm{b}} & C_{\mathrm{bc}} & C_{\mathrm{bn}}\\ C_{\mathrm{ac}} & C_{\mathrm{bc}} & C_{\mathrm{c}} & C_{\mathrm{cn}}\\ C_{\mathrm{an}} & C_{\mathrm{bn}} & C_{\mathrm{cn}} & C_{\mathrm{n}} \end{pmatrix} }_{B} \end{aligned}\end{split}\]

with \(G\in\mathbb{R}^4\) the conductance of the line, \(B\in\mathbb{R}^4\) the susceptance of the line and \(C\in\mathbb{R}^{16}\) the transverse susceptances of the line.

Shunt admittance matrix#

The shunt admittance matrix \(\underline{Y}\) is defined from the admittance matrix \(\underline{y}\) as:

\[\begin{split}\underline{Y} = \begin{pmatrix} \underline{Y_{\mathrm{aa}}} & \underline{Y_{\mathrm{ab}}} & \underline{Y_{\mathrm{ac}}} & \underline{Y_{\mathrm{an}}}\\ \underline{Y_{\mathrm{ba}}} & \underline{Y_{\mathrm{bb}}} & \underline{Y_{\mathrm{bc}}} & \underline{Y_{\mathrm{bn}}}\\ \underline{Y_{\mathrm{ca}}} & \underline{Y_{\mathrm{cb}}} & \underline{Y_{\mathrm{cc}}} & \underline{Y_{\mathrm{cn}}}\\ \underline{Y_{\mathrm{na}}} & \underline{Y_{\mathrm{nb}}} & \underline{Y_{\mathrm{nc}}} & \underline{Y_{\mathrm{nn}}}\\ \end{pmatrix} \quad \text{with} \quad \left\{ \begin{aligned} \underline{Y_{ii}} &= \sum_{k\in\{\mathrm{a},\mathrm{b},\mathrm{c},\mathrm{n},\mathrm{g}\}}{\underline{y_{ik}}}\\ \underline{Y_{ij}} &= -\underline{y_{ij}}\\ \end{aligned} \right.\text{, }\forall(i,j)\in\{\mathrm{a},\mathrm{b},\mathrm{c},\mathrm{n}\}^2\end{split}\]

Line parameters#

The parameters of the lines are defined using the LineParameters class. It takes the series impedance matrix \(\underline{Z}\) and optionally, the shunt admittance matrix \(\underline{Y}\). The first one must be given in \(\Omega\)/km (or an equivalent unit) and the second must be given in \(S/km\) (or an equivalent unit).

import numpy as np

from roseau.load_flow import LineParameters, Q_

# An impedance matrix
z_line = Q_(
    np.array(
        [
            [0.3 + 0.35j, 0.25j, 0.25j, 0.25j],
            [0.25j, 0.3 + 0.35j, 0.25j, 0.25j],
            [0.25j, 0.25j, 0.3 + 0.35j, 0.25j],
            [0.25j, 0.25j, 0.25j, 0.3 + 0.35j],
        ]
    ),
    "ohm/km",
)

# A shunt admittance matrix
y_shunt = Q_(
    np.array(
        [
            [20 + 475j, -68j, -10j, -68j],
            [-68j, 20 + 475j, -68j, -10j],
            [-10j, -68j, 20 + 475j, -68j],
            [-68j, -10j, -68j, 20 + 475j],
        ]
    ),
    "uS/km",  # micro Siemens per kilometer
)

# The line parameter for a simple line (no shunt)
simple_line_parameters = LineParameters(id="simple_line_parameters", z_line=z_line)

# The line parameter for a line with a shunt
shunt_line_parameters = LineParameters(
    id="shunt_line_parameters", z_line=z_line, y_shunt=y_shunt
)

Tip

The Line instance itself has the z_line and y_shunt properties. They retrieve the line impedance in \(\Omega\) and the line shunt admittance in Siemens (taking into account the length of the line).

There are several alternative constructors for LineParameters objects. The description of them can be found in the dedicated Line parameters page.

Available models#

The following line models are available in Roseau Load Flow. Please also have a look at the parameters page to define the parameters of lines.

API Reference#

class LineParameters(id: int | str, z_line: ndarray[Any, dtype[complex128]] | Quantity[ndarray[Any, dtype[complex128]]] | Quantity[Sequence[Sequence[complex]]] | Sequence[Sequence[complex | Quantity[complex]]], y_shunt: ndarray[Any, dtype[complex128]] | Quantity[ndarray[Any, dtype[complex128]]] | Quantity[Sequence[Sequence[complex]]] | Sequence[Sequence[complex | Quantity[complex]]] | None = None, max_current: float | None = None, line_type: LineType | None = None, conductor_type: ConductorType | None = None, insulator_type: InsulatorType | None = None, section: float | Quantity[float] | None = None)

Bases: Identifiable, JsonMixin, CatalogueMixin[DataFrame]

Parameters that define electrical models of lines.

LineParameters constructor.

Parameters:
  • id – A unique ID of the line parameters, typically its canonical name.

  • z_line – The Z matrix of the line (Ohm/km).

  • y_shunt – The Y matrix of the line (Siemens/km). This field is optional if the line has no shunt part.

  • max_current – The maximum current loading of the line (A). The maximum current is optional, it is not used in the load flow but can be used to check for overloading. See also Line.res_violated.

  • line_type – The type of the line (overhead, underground, twisted). The line type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.

  • conductor_type – The type of the conductor material (Aluminum, Copper, …). The conductor type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.

  • insulator_type – The type of the cable insulator (PVC, XLPE, …). The insulator type is optional, it is informative only and is not used in the load flow. This field gets automatically filled when the line parameters are created from a geometric model or from the catalogue.

property line_type: LineType | None

The type of the line. Informative only, it has no impact on the load flow.

property conductor_type: ConductorType | None

The type of the conductor material. Informative only, it has no impact on the load flow.

property insulator_type: InsulatorType | None

The type of the cable insulator. Informative only, it has no impact on the load flow.

property section: Quantity[float] | None

The cross section area of the cable (in mm²). Informative only, it has no impact on the load flow.

property max_current: Quantity[float] | None

The maximum current loading of the line (A) if it is set.

classmethod from_sym(id: int | str, z0: complex | Quantity[complex], z1: complex | Quantity[complex], y0: complex | Quantity[complex], y1: complex | Quantity[complex], zn: complex | Quantity[complex] | None = None, xpn: float | Quantity[float] | None = None, bn: float | Quantity[float] | None = None, bpn: float | Quantity[float] | None = None, max_current: float | Quantity[float] | None = None) Self

Create line parameters from a symmetric model.

Parameters:
  • id – A unique ID of the line parameters, typically its canonical name.

  • z0 – Impedance - zero sequence - \(r_0+x_0\cdot j\) (ohms/km)

  • z1 – Impedance - direct sequence - \(r_1+x_1\cdot j\) (ohms/km)

  • y0 – Admittance - zero sequence - \(g_0+b_0\cdot j\) (Siemens/km)

  • y1 – Conductance - direct sequence - \(g_1+b_1\cdot j\) (Siemens/km)

  • zn – Neutral impedance - \(r_{\mathrm{n}}+x_{\mathrm{n}}\cdot j\) (ohms/km)

  • xpn – Phase to neutral reactance (ohms/km)

  • bn – Neutral susceptance (siemens/km)

  • bpn – Phase to neutral susceptance (siemens/km)

  • max_current – An optional maximum current loading of the line (A). It is not used in the load flow.

Returns:

The created line parameters.

Notes

As explained in the Line parameters alternative constructor documentation, the model may be “degraded” if the computed impedance matrix is not invertible.

classmethod from_geometry(id: int | str, *, line_type: LineType, conductor_type: ConductorType | None = None, insulator_type: InsulatorType | None = None, section: float | Quantity[float], section_neutral: float | Quantity[float] | None = None, height: float | Quantity[float], external_diameter: float | Quantity[float], max_current: float | Quantity[float] | None = None) Self

Create line parameters from its geometry.

Parameters:
  • id – The id of the line parameters type.

  • line_type – Overhead or underground. See also LineType.

  • conductor_type – Type of the conductor. If None, ACSR is used for overhead lines and AL for underground or twisted lines. See also ConductorType.

  • insulator_type – Type of insulator. If None, XLPE is used for twisted lines and PVC for underground lines. See also InsulatorType.

  • section – Cross-section surface area of the phases (mm²).

  • section_neutral – Cross-section surface area of the neutral (mm²). If None it will be the same as the section of the other phases.

  • height – Height of the line (m). It must be positive for overhead lines and negative for underground lines.

  • external_diameter – External diameter of the cable (m).

  • max_current – An optional maximum current loading of the line (A). It is not used in the load flow.

Returns:

The created line parameters.

classmethod from_name_lv(name: str, section_neutral: float | Quantity[float] | None = None, height: float | Quantity[float] | None = None, external_diameter: float | Quantity[float] | None = None, max_current: float | Quantity[float] | None = None) Self

Method to get the electrical parameters of a LV line from its canonical name. Some hypothesis will be made: the section of the neutral is the same as the other sections, the height and external diameter are pre-defined, and the insulator is PVC.

Parameters:
  • name – The name of the line the parameters must be computed. E.g. “U_AL_150”.

  • section_neutral – Surface of the neutral (mm²). If None it will be the same as the section of the other phases.

  • height – Height of the line (m). If None a default value will be used.

  • external_diameter – External diameter of the wire (mm). If None a default value will be used.

  • max_current – An optional maximum current loading of the line (A). It is not used in the load flow.

Returns:

The corresponding line parameters.

Deprecated since version 0.6.0: Use LineParameters.from_geometry() instead.

classmethod from_name_mv(name: str, max_current: float | Quantity[float] | None = None) Self

Get the electrical parameters of a MV line from its canonical name (France specific model)

Parameters:
  • name – The canonical name of the line parameters. It must be in the format lineType_conductorType_crossSection. E.g. “U_AL_150”.

  • max_current – An optional maximum current loading of the line (A). It is not used in the load flow.

Returns:

The corresponding line parameters.

classmethod catalogue_path() Path

Get the path to the catalogue.

classmethod catalogue_data() DataFrame

Get the catalogue data.

classmethod from_catalogue(name: str | Pattern[str] | None = None, line_type: str | None = None, conductor_type: str | None = None, insulator_type: str | None = None, section: float | Quantity[float] | None = None, id: int | str | None = None) Self

Create line parameters from a catalogue.

Parameters:
  • name – The name of the line parameters to get from the catalogue. It can be a regular expression.

  • line_type – The type of the line parameters to get. It can be "overhead", "twisted", or "underground". See also LineType.

  • conductor_type – The type of the conductor material (Al, Cu, …). See also ConductorType.

  • insulator_type – The type of insulator. See also InsulatorType.

  • section – The cross-section surface area of the phases (mm²).

  • id – A unique ID for the created line parameters object (optional). If None (default), the id of the created object will be its name in the catalogue.

Returns:

The created line parameters.

classmethod get_catalogue(name: str | Pattern[str] | None = None, line_type: str | None = None, conductor_type: str | None = None, insulator_type: str | None = None, section: float | Quantity[float] | None = None) DataFrame

Get the catalogue of available lines.

You can use the parameters below to filter the catalogue. If you do not specify any parameter, all the catalogue will be returned.

Parameters:
  • name – The name of the line parameters to get from the catalogue. It can be a regular expression.

  • line_type – The type of the line parameters to get. It can be "overhead", "twisted", or "underground". See also LineType.

  • conductor_type – The type of the conductor material (Al, Cu, …). See also ConductorType.

  • insulator_type – The type of insulator. See also InsulatorType.

  • section – The cross-section surface area of the phases (mm²).

Returns:

The catalogue data as a dataframe.

classmethod from_dict(data: dict[str, Any], *, include_results: bool = True) Self

Line parameters constructor from dict.

Parameters:

data – The dictionary data of the line parameters.

Returns:

The created line parameters.

class Line(id: int | str, bus1: Bus, bus2: Bus, *, parameters: LineParameters, length: float | Quantity[float], phases: str | None = None, ground: Ground | None = None, geometry: BaseGeometry | None = None)

Bases: AbstractBranch

An electrical line PI model with series impedance and optional shunt admittance.

Line constructor.

Parameters:
  • id – A unique ID of the line in the network branches.

  • bus1 – The first bus (aka “from_bus”) to connect to the line.

  • bus2 – The second bus (aka “to_bus”) to connect to the line.

  • parameters – Parameters defining the electric model of the line using its impedance and shunt admittance matrices. This is an instance of the LineParameters class and can be used by multiple lines.

  • length – The length of the line (in km).

  • phases – The phases of the line. A string like "abc" or "an" etc. The order of the phases is important. For a full list of supported phases, see the class attribute allowed_phases. All phases of the line must be present in the phases of both connected buses. By default, the phases common to both buses are used.

  • ground – The ground element attached to the line if it has shunt admittance.

  • geometry – The geometry of the line i.e. the linestring.

allowed_phases: Final = frozenset({'a', 'ab', 'abc', 'abcn', 'abn', 'an', 'b', 'bc', 'bcn', 'bn', 'c', 'ca', 'can', 'cn', 'n'})

The allowed phases for a line are:

  • P-P-P or P-P-P-N: "abc", "abcn"

  • P-P or P-P-N: "ab", "bc", "ca", "abn", "bcn", "can"

  • P or P-N: "a", "b", "c", "an", "bn", "cn"

  • N: "n"

property phases: str

The phases of the line. This is an alias for phases1 and phases2.

property length: Quantity[float]

The length of the line (in km).

property parameters: LineParameters

The parameters defining the impedance and shunt admittance matrices of line model.

property z_line: Quantity[ndarray[Any, dtype[complex128]]]

Impedance of the line (in Ohm).

property y_shunt: Quantity[ndarray[Any, dtype[complex128]]]

Shunt admittance of the line (in Siemens).

property max_current: Quantity[float] | None

The maximum current loading of the line (in A).

property res_series_currents: Quantity[ndarray[Any, dtype[complex128]]]

Get the current in the series elements of the line (in A).

property res_series_power_losses: Quantity[ndarray[Any, dtype[complex128]]]

Get the power losses in the series elements of the line (in VA).

property res_shunt_currents: tuple[Quantity[ndarray[Any, dtype[complex128]]], Quantity[ndarray[Any, dtype[complex128]]]]

Get the currents in the shunt elements of the line (in A).

property res_shunt_power_losses: Quantity[ndarray[Any, dtype[complex128]]]

Get the power losses in the shunt elements of the line (in VA).

property res_power_losses: Quantity[ndarray[Any, dtype[complex128]]]

Get the power losses in the line (in VA).

property res_violated: bool | None

Whether the line current exceeds the maximum current (loading > 100%).

Returns None if the maximum current is not set.