Skip to content

Commit

Permalink
Merge pull request #288 from RoseauTechnologies/revert-287-lp-improved
Browse files Browse the repository at this point in the history 
Revert "ENH: LineParameters contains 4x4 matrices"
  • Loading branch information
@alihamdan
alihamdan authored Nov 28, 2024
2 parents 615f6c7 + 58233b1 commit 919be96
Show file tree
Hide file tree
Showing 66 changed files with 2,781 additions and 4,117 deletions.
12 changes: 0 additions & 12 deletions doc/Changelog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,6 @@ og:description: See what's new in the latest release of Roseau Load Flow !

## Unreleased

- {gh-pr}`287` **BREAKING CHANGES**: The constructor of the class `LineParameters` now only accepts 4x4 line
impedance and shunt admittance matrices. This means that the same `LineParameters` instance can be used for lines
that have different phases. It has the following consequences:

- The methods `z_line`, `y_shunt`, `with_shunt`, `sections`, `materials`, `insulators` and `ampacities` are not
anymore properties. They are now methods that takes the phases of a line as argument.
- These parameters can not be set anymore.
- All the alternative constructors of the class have also been modified and don't accept anymore parameters about
the number of phases or of neutral.
- The conversion of files generated with previous versions of _Roseau Load Flow_ may rename some line parameters
to avoid mistakes when they are used with lines using different phases. An `UserWarning` is raised in such cases.

- {gh-pr}`285` {gh-issue}`279` **BREAKING CHANGE**: Add limits on assets. It is now possible to define a maximum
loading for lines and transformers. It generates some indirect consequences:

Expand Down
8 changes: 4 additions & 4 deletions doc/advanced/Potential_Reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -204,9 +204,9 @@ rlf.Transformer("MV/LV Transformer", bus1=mv_bus1, bus2=lv_bus1, parameters=tp)

# Create a common ground for the MV and LV sides
ground = rlf.Ground("Ground")
mv_lp = rlf.LineParameters.from_catalogue("U_AL_150")
mv_lp = rlf.LineParameters.from_catalogue("U_AL_150", nb_phases=3)
rlf.Line("MV Line", bus1=mv_bus1, bus2=mv_bus2, length=1, parameters=mv_lp, ground=ground)
lv_lp = rlf.LineParameters.from_catalogue("U_AL_70")
lv_lp = rlf.LineParameters.from_catalogue("U_AL_70", nb_phases=4)
rlf.Line(
"LV Line", bus1=lv_bus1, bus2=lv_bus2, length=0.1, parameters=lv_lp, ground=ground
)
Expand Down Expand Up @@ -246,12 +246,12 @@ rlf.Transformer("MV/LV Transformer", bus1=mv_bus1, bus2=lv_bus1, parameters=tp)

# Create separate grounds for the MV and LV sides
mv_ground = rlf.Ground("MVGround")
mv_lp = rlf.LineParameters.from_catalogue("U_AL_150")
mv_lp = rlf.LineParameters.from_catalogue("U_AL_150", nb_phases=3)
rlf.Line(
"MV Line", bus1=mv_bus1, bus2=mv_bus2, length=1, parameters=mv_lp, ground=mv_ground
)
lv_ground = rlf.Ground("LVGround")
lv_lp = rlf.LineParameters.from_catalogue("U_AL_70")
lv_lp = rlf.LineParameters.from_catalogue("U_AL_70", nb_phases=4)
rlf.Line(
"LV Line", bus1=lv_bus1, bus2=lv_bus2, length=0.1, parameters=lv_lp, ground=lv_ground
)
Expand Down
4 changes: 2 additions & 2 deletions doc/models/Ground.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@ vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
# Define the impedance and admittance parameters of the lines (can be reused)
parameters = rlf.LineParameters(
id="parameters",
z_line=rlf.Q_((0.12 + 0.1j) * np.eye(4), "ohm/km"),
y_shunt=rlf.Q_(2e-4j * np.eye(4), "S/km"),
z_line=rlf.Q_((0.12 + 0.1j) * np.eye(3), "ohm/km"),
y_shunt=rlf.Q_(2e-4j * np.eye(3), "S/km"),
)

# Define a line between bus1 and bus2 (using g1 for the shunt connections)
Expand Down
192 changes: 110 additions & 82 deletions doc/models/Line/Parameters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ configurations and material types.

This page describes how to build the impedance and shunt admittance matrices and thus the line
parameters object using these alternative data. This is achieved via the alternative constructors
of the `LineParameters` class.
of the `LineParameters` class. Note that only 3-phase lines are supported by the alternative
constructors.

(models-line_parameters-alternative_constructors-symmetric)=

Expand All @@ -44,25 +45,15 @@ the shunt admittance matrix $\underline{Y}$ using the following equations:
```{math}
\begin{aligned}
\underline{Z} &= \begin{pmatrix}
\underline{Z_{\mathrm{s}}} & \underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{m}}} &
\underline{Z_{\mathrm{m}}} \\
\underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{s}}} & \underline{Z_{\mathrm{m}}} &
\underline{Z_{\mathrm{m}}} \\
\underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{s}}} &
\underline{Z_{\mathrm{m}}} \\
\underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{m}}} &
\underline{Z_{\mathrm{s}}} \\
\underline{Z_{\mathrm{s}}} & \underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{m}}} \\
\underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{s}}} & \underline{Z_{\mathrm{m}}} \\
\underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{m}}} & \underline{Z_{\mathrm{s}}} \\
\end{pmatrix}\\
\underline{Y} &=
\begin{pmatrix}
\underline{Y_{\mathrm{s}}} & \underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{m}}} &
\underline{Y_{\mathrm{m}}} \\
\underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{s}}} & \underline{Y_{\mathrm{m}}} &
\underline{Y_{\mathrm{m}}} \\
\underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{s}}} &
\underline{Y_{\mathrm{m}}} \\
\underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{m}}} &
\underline{Y_{\mathrm{s}}} \\
\underline{Y_{\mathrm{s}}} & \underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{m}}} \\
\underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{s}}} & \underline{Y_{\mathrm{m}}} \\
\underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{m}}} & \underline{Y_{\mathrm{s}}} \\
\end{pmatrix}
\end{aligned}
```
Expand Down Expand Up @@ -92,8 +83,8 @@ For lines with a neutral, this method also takes the following optional extra pa

```{note}
If any of those parameters is omitted or if $\underline{Z_{\mathrm{n}}}$ and
$\underline{X_{p\mathrm{n}}}$ are zeros, the neutral wire is omitted and the symmetrical matrix described above is
returned.
$\underline{X_{p\mathrm{n}}}$ are zeros, the neutral wire is omitted and a 3-phase line parameters
is built.
```

In this case, the following matrices are built:
Expand Down Expand Up @@ -130,6 +121,22 @@ $\underline{Y_{\mathrm{m}}}$ as before and:
respectively the phase-to-neutral series impedance (in $\Omega$/km), the neutral shunt admittance (in S/km) and
the phase-to-neutral shunt admittance (in S/km).

````{note}
If the computed impedance matrix is be non-invertible, the `from_sym` class method builds impedance
and shunt admittance matrices using the following definitions:
```{math}
\begin{aligned}
\underline{Z_{\mathrm{s}}} &= \underline{Z_1} \\
\underline{Z_{\mathrm{m}}} &= 0 \\
\underline{Y_{\mathrm{s}}} &= \underline{Y_1} \\
\underline{Y_{\mathrm{m}}} &= 0 \\
\end{aligned}
```
It means that we try to define $\underline{Z_0}=\underline{Z_1}$ and $\underline{Y_0}=\underline{Y_1}$. If this
"degraded" model also leads to a non-invertible impedance matrix, an error is raised.
````

### Examples

```pycon
Expand All @@ -141,23 +148,44 @@ the phase-to-neutral shunt admittance (in S/km).
... "sym_line_example", z0=0.2 + 0.1j, z1=0.2 + 0.1j, y0=0.00014106j, y1=0.00014106j
... )

>>> line_parameters.z_line("abcn")
<Quantity(
[[0.2+0.1j, 0. +0.j , 0. +0.j , 0. +0.j ],
[0. +0.j , 0.2+0.1j, 0. +0.j , 0. +0.j ],
[0. +0.j , 0. +0.j , 0.2+0.1j, 0. +0.j ],
[0. +0.j , 0. +0.j , 0. +0.j , 0.2+0.1j]],
'ohm / kilometer')>

>>> line_parameters.y_shunt("abcn")
<Quantity(
[[0.+0.00014106j, 0.+0.j , 0.+0.j , 0.+0.j ],
[0.+0.j , 0.+0.00014106j, 0.+0.j , 0.+0.j ],
[0.+0.j , 0.+0.j , 0.+0.00014106j, 0.+0.j ],
[0.+0.j , 0.+0.j , 0.+0.j , 0.+0.00014106j]],
'siemens / kilometer')>

>>> # Take into account neutral elements
>>> line_parameters.z_line
array(
[[ 0.2+0.1j, 0. +0.j , 0. +0.j ],
[ 0. +0.j , 0.2+0.1j, 0. +0.j ],
[ 0. +0.j , 0. +0.j , 0.2+0.1j ]]
) <Unit('ohm / kilometer')>

>>> line_parameters.y_shunt
array(
[[ 0.+0.00014106j, 0.+0.j , 0.+0.j ],
[ 0.+0.j , 0.+0.00014106j, 0.+0.j ],
[ 0.+0.j , 0.+0.j , 0.+0.00014106j ]]
) <Unit('siemens / kilometer')>


>>> # Simple example in "downgraded" model
... line_parameters = rlf.LineParameters.from_sym(
... "NKBA NOR 25.00 kV", z0=0.0j, z1=1.0 + 1.0j, y0=0.0j, y1=1e-06j
... )
The symmetric model data provided for line type 'NKBA NOR 25.00 kV' produces invalid line impedance matrix... It is
often the case with line models coming from PowerFactory. Trying to handle the data in a 'degraded' line model.

>>> line_parameters.z_line
array(
[[1.+1.j, 0.+0.j, 0.+0.j],
[0.+0.j, 1.+1.j, 0.+0.j],
[0.+0.j, 0.+0.j, 1.+1.j]]
) <Unit('ohm / kilometer')>

>>> line_parameters.y_shunt
array(
[[0.+1.e-06j, 0.+0.e+00j, 0.+0.e+00j],
[0.+0.e+00j, 0.+1.e-06j, 0.+0.e+00j],
[0.+0.e+00j, 0.+0.e+00j, 0.+1.e-06j]]
) <Unit('siemens / kilometer')>


>>> # 4x4 matrix
... line_parameters = rlf.LineParameters.from_sym(
... "sym_neutral_underground_line_example",
... z0=0.188 + 0.8224j,
Expand All @@ -170,21 +198,21 @@ the phase-to-neutral shunt admittance (in S/km).
... bpn=-0.000031502,
... )

>>> line_parameters.z_line("abcn")
<Quantity(
[[0.188 +0.32826667j, 0. +0.24706667j, 0. +0.24706667j, 0. +0.2471j],
[0. +0.24706667j, 0.188 +0.32826667j, 0. +0.24706667j, 0. +0.2471j],
[0. +0.24706667j, 0. +0.24706667j, 0.188 +0.32826667j, 0. +0.2471j],
[0. +0.2471j , 0. +0.2471j , 0. +0.2471j , 0.4029+0.3522j]],
'ohm / kilometer')>

>>> line_parameters.y_shunt("abcn").to("uS/km")
<Quantity(
[[10.462+174.37133333j, 0. -55.61866667j, 0. -55.61866667j, 0. -31.502j],
[ 0. -55.61866667j, 10.462+174.37133333j, 0. -55.61866667j, 0. -31.502j],
[ 0. -55.61866667j, 0. -55.61866667j, 10.462+174.37133333j, 0. -31.502j],
[ 0. -31.502j , 0. -31.502j , 0. -31.502j , 0. +114.07j ]],
'microsiemens / kilometer')>
>>> line_parameters.z_line
array(
[[0.188 +0.32826667j, 0. +0.24706667j, 0. +0.24706667j, 0. +0.2471j ],
[0. +0.24706667j, 0.188 +0.32826667j, 0. +0.24706667j, 0. +0.2471j ],
[0. +0.24706667j, 0. +0.24706667j, 0.188 +0.32826667j, 0. +0.2471j ],
[0. +0.2471j , 0. +0.2471j , 0. +0.2471j , 0.4029+0.3522j ]]
) <Unit('ohm / kilometer')>

>>> line_parameters.y_shunt
array(
[[ 1.0462e-05+1.74371333e-04j, 0.0000e+00-5.56186667e-05j, 0.0000e+00-5.56186667e-05j, -0.0000e+00-3.15020000e-05j],
[ 0.0000e+00-5.56186667e-05j, 1.0462e-05+1.74371333e-04j, 0.0000e+00-5.56186667e-05j, -0.0000e+00-3.15020000e-05j],
[ 0.0000e+00-5.56186667e-05j, 0.0000e+00-5.56186667e-05j, 1.0462e-05+1.74371333e-04j, -0.0000e+00-3.15020000e-05j],
[-0.0000e+00-3.15020000e-05j, -0.0000e+00-3.15020000e-05j, -0.0000e+00-3.15020000e-05j, 0.0000e+00+1.14070000e-04j]]
) <Unit('siemens / kilometer')>
```

## Geometric model
Expand Down Expand Up @@ -434,24 +462,24 @@ The formulas of the previous sections are used to get the impedance and shunt ad
... section=150, # mm²
... section_neutral=70, # mm²
... height=10, # m
... external_diameter=rlf.Q_(5, "cm"),
... external_diameter=rlf.Q_(4, "cm"),
... )

>>> line_parameters.z_line("abcn")
<Quantity(
[[0.18842667+0.32828403j , 0. +0.24081693j, 0. +0.24081693j, 0. +0.27533085j],
[ 0. +0.24081693j, 0.18842667+0.32828403j, 0. +0.24081693j, 0. +0.27533085j],
[ 0. +0.24081693j, 0. +0.24081693j, 0.18842667+0.32828403j, 0. +0.27533085j],
[ 0. +0.27533085j, 0. +0.27533085j, 0. +0.27533085j, 0.40377143+0.35222736j]],
'ohm / kilometer')>

>>> line_parameters.y_shunt("abcn").to("uS/km")
<Quantity(
[[0.10014735+37.06451833j, 0. -2.29401352j, 0. -2.29320761j, 0. -7.44046029j],
[0. -2.29401352j, 0.10014735+37.06451833j, 0. -2.29320761j, 0. -7.44046029j],
[0. -2.29320761j, 0. -2.29320761j, 0.10015225+37.06535779j, 0. -7.44087918j],
[0. -7.44046029j, 0. -7.44046029j, 0. -7.44087918j, 0.17653382+66.45525438j]],
'microsiemens / kilometer')>
>>> line_parameters.z_line
array(
[[0.188 +0.32828403j, 0. +0.25483745j, 0. +0.25483745j, 0. +0.28935138j],
[0. +0.25483745j, 0.188 +0.32828403j, 0. +0.25483745j, 0. +0.28935138j],
[0. +0.25483745j, 0. +0.25483745j, 0.188 +0.32828403j, 0. +0.28935138j],
[0. +0.28935138j, 0. +0.28935138j, 0. +0.28935138j, 0.40285714+0.35222736j]]
) <Unit('ohm / kilometer')>

>>> line_parameters.y_shunt.to("uS/km")
array(
[[0.09883654 +48.82465468j, 0. -1.92652134j, 0. -1.92555213j, 0. -12.02706891j],
[0. -1.92652134j, 0.09883654 +48.82465468j, 0. -1.92555213j, 0. -12.02706891j],
[0. -1.92555213j, 0. -1.92555213j, 0.09884227 +48.82653968j, 0. -12.02801059j],
[0. -12.02706891j, 0. -12.02706891j, 0. -12.02801059j, 0.21303236+107.09293474j]]
) <Unit('microsiemens / kilometer')>)
```

### Underground line
Expand Down Expand Up @@ -519,21 +547,21 @@ Please note that for underground lines, the provided height $h$ must be negative
... external_diameter=0.049, # m
... )

>>> line_parameters.z_line("abcn")
<Quantity(
[[0.18842667+0.32828403j, 0. +0.25482437j, 0. +0.23304851j, 0. +0.25482437j],
[0. +0.25482437j, 0.18842667+0.32828403j, 0. +0.25482437j, 0. +0.23304851j],
[0. +0.23304851j, 0. +0.25482437j, 0.18842667+0.32828403j, 0. +0.25482437j],
[0. +0.25482437j, 0. +0.23304851j, 0. +0.25482437j, 0.40377143+0.35222736j]],
'ohm / kilometer')>

>>> line_parameters.y_shunt("abcn").to("uS/km")
<Quantity(
[[39.15717351+564.81344205j, 0. -92.08685834j, 0. -25.86533679j, 0. -55.28951177j],
[ 0. -92.08685834j, 42.33666455+615.05672632j, 0. -92.08685834j, 0. -7.51636412j],
[ 0. -25.86533679j, 0. -92.08685834j, 39.15717351+564.81344205j, 0. -55.28951177j],
[ 0. -55.28951177j, 0. -7.51636412j, 0. -55.28951177j, 26.01989043+378.29429195j]],
'microsiemens / kilometer')>
>>> line_parameters.z_line
array(
[[0.188 +0.32828403j, 0. +0.25482437j, 0. +0.23304851j, 0. +0.25482437j],
[0. +0.25482437j, 0.188 +0.32828403j, 0. +0.25482437j, 0. +0.23304851j],
[0. +0.23304851j, 0. +0.25482437j, 0.188 +0.32828403j, 0. +0.25482437j],
[0. +0.25482437j, 0. +0.23304851j, 0. +0.25482437j, 0.40285714+0.35222736j]]
) <Unit('ohm / kilometer')>

>>> line_parameters.y_shunt.to("uS/km")
array(
[[19.06271927+458.27618628j, 0. -74.71708551j, 0. -20.98651877j, 0. -44.86059415j],
[ 0. -74.71708551j, 20.61057729+499.04239152j, 0. -74.71708551j, 0. -6.09859898j],
[ 0. -20.98651877j, 0. -74.71708551j, 19.06271927+458.27618628j, 0. -44.86059415j],
[ 0. -44.86059415j, 0. -6.09859898j, 0. -44.86059415j, 12.66715195+306.9389864j ]]
) <Unit('microsiemens / kilometer')>
```

## Import from OpenDSS
Expand Down
26 changes: 9 additions & 17 deletions doc/usage/Data_Exchange.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ The data on these two screenshots translate to:

`roseau-load-flow` supports creating lines and transformers from OpenDSS data.

### Lines
#### Lines

To create line parameters from an OpenDSS `LineCode` object, use the
{meth}`LineParameters.from_open_dss() <roseau.load_flow.LineParameters.from_open_dss>` method. For
Expand All @@ -173,25 +173,17 @@ translates to:
```pycon
>>> lp = rlf.LineParameters.from_open_dss(
... id="240sq",
... r1=rlf.Q_(0.127, "ohm/km"),
... x1=rlf.Q_(0.072, "ohm/km"),
... r0=rlf.Q_(0.342, "ohm/km"),
... x0=rlf.Q_(0.089, "ohm/km"),
... c1=rlf.Q_(3.4, "nF/km"), # default value used in OpenDSS code
... c0=rlf.Q_(1.6, "nF/km"), # default value used in OpenDSS code
... nphases=3, # creates 3x3 Z,Y matrices
... r1=Q_(0.127, "ohm/km"),
... x1=Q_(0.072, "ohm/km"),
... r0=Q_(0.342, "ohm/km"),
... x0=Q_(0.089, "ohm/km"),
... c1=Q_(3.4, "nF/km"), # default value used in OpenDSS code
... c0=Q_(1.6, "nF/km"), # default value used in OpenDSS code
... )
```

As the DSS command contains the `nphases=3` data, this parameters can now be used in a line with three phases:

```pycon
bus1 = rlf.Bus(id="bus1", phases="abc")
bus2 = rlf.Bus(id="bus2", phases="abc")
ground=rlf.Ground("ground")
line = rlf.Line(id="line",bus1=bus1, bus2=bus2, phases="abc", parameters=lp, length=rlf.Q_(300, "m"), ground=ground)
```

### Transformers
#### Transformers

To create a transformer from an OpenDSS 2-winding `Transformer` object, use the
{meth}`TransformerParameters.from_open_dss() <roseau.load_flow.TransformerParameters.from_open_dss>`
Expand Down
Loading

0 comments on commit 919be96

Please sign in to comment.