From f3bcf48676c0df254792d974807099e72bc6b338 Mon Sep 17 00:00:00 2001 From: Ali Hamdan Date: Tue, 19 Sep 2023 15:59:02 +0200 Subject: [PATCH 1/2] Add a doc page about converters and constants Resolves #101 --- doc/usage/Extras.md | 103 ++++++++++++++++++++++++++++ doc/usage/index.md | 1 + roseau/load_flow/utils/constants.py | 8 +-- 3 files changed, 108 insertions(+), 4 deletions(-) create mode 100644 doc/usage/Extras.md diff --git a/doc/usage/Extras.md b/doc/usage/Extras.md new file mode 100644 index 00000000..f185bdbe --- /dev/null +++ b/doc/usage/Extras.md @@ -0,0 +1,103 @@ +# Extras + +`roseau-load-flow` comes with some extra features that can be useful for some users. + +## Conversion to symmetrical components + +{mod}`roseau.load_flow.converters` contains helpers to convert between phasor and symmetrical +components. For example, to convert a phasor voltage to symmetrical components: + +```pycon +>>> import numpy as np +>>> from roseau.load_flow.converters import phasor_to_sym, sym_to_phasor +>>> v = 230 * np.exp([0, -2j * np.pi / 3, 2j * np.pi / 3]) +>>> v +array([ 230. +0.j , -115.-199.18584287j, -115.+199.18584287j]) +>>> v_sym = phasor_to_sym(v) +>>> v_sym +array([[ 8.52651283e-14-1.42108547e-14j], + [ 2.30000000e+02+4.19109192e-14j], + [-7.10542736e-14-2.84217094e-14j]]) +``` + +As you can see, for this positive-sequence balanced voltage, only the positive-sequence component +is non-zero. Converting back to phasor, you get the original voltage values back: + +```pycon +>>> sym_to_phasor(v_sym) +array([[ 230.-7.21644966e-16j], + [-115.-1.99185843e+02j], + [-115.+1.99185843e+02j]]) +``` + +You can also convert pandas Series to symmetrical components. If we take the example network of the +[Getting Started](Getting_Started.md) page: + +```pycon +>>> from roseau.load_flow.converters import series_phasor_to_sym +>>> series_phasor_to_sym(en.res_buses_voltages["voltage"]) +bus_id sequence +lb zero 8.526513e-14-1.421085e-14j + pos 2.219282e+02+4.167975e-14j + neg -5.684342e-14-2.842171e-14j +sb zero 9.947598e-14-1.421085e-14j + pos 2.309401e+02+3.483159e-14j + neg -4.263256e-14-2.842171e-14j +Name: voltage, dtype: complex128 +``` + +## Potentials to voltages conversion + +{mod}`roseau.load_flow.converters` also contains helpers to convert a vector of potentials to a +vector of voltages. Example: + +```pycon +>>> import numpy as np +>>> from roseau.load_flow.converters import calculate_voltages, calculate_voltage_phases +>>> potentials = 230 * np.array([1, np.exp(-2j * np.pi / 3), np.exp(2j * np.pi / 3), 0]) +>>> potentials +array([ 230. +0.j , -115.-199.18584287j, -115.+199.18584287j, + 0. +0.j ]) +>>> phases = "abcn" +>>> calculate_voltages(potentials, phases) +array([ 230. +0.j , -115.-199.18584287j, -115.+199.18584287j]) +``` + +Because the phases include the neutral, the voltages calculated are phase-to-neutral voltages. +You can also calculate phase-to-phase voltages by omitting the neutral: + +```pycon +>>> calculate_voltages(potentials[:-1], phases[:-1]) +array([ 345.+199.18584287j, 0.-398.37168574j, -345.+199.18584287j]) +``` + +To get the phases of the voltage, you can use `calculate_voltage_phases`: + +```pycon +>>> calculate_voltage_phases(phases) +['an', 'bn', 'cn'] +``` + +Of course these functions work with arbitrary phases: + +```pycon +>>> calculate_voltages(potentials[:2], phases[:2]) +array([345.+199.18584287j]) +>>> calculate_voltage_phases(phases[:2]) +['ab'] +>>> calculate_voltage_phases("abc") +['ab', 'bc', 'ca'] +>>> calculate_voltage_phases("bc") +['bc'] +>>> calculate_voltage_phases("bcn") +['bn', 'cn'] +``` + +## Constants + +{mod}`roseau.load_flow.utils.constants` contains some common constants like the resistivity +and permeability of common conductor types in addition to other useful constants. Please refer to +the module documentation for more details. + +An enumeration of available conductor types can be found in the {mod}`roseau.load_flow.utils.types` +module. diff --git a/doc/usage/index.md b/doc/usage/index.md index 05695cd9..664f16cc 100644 --- a/doc/usage/index.md +++ b/doc/usage/index.md @@ -13,4 +13,5 @@ Flexible_Loads Short_Circuit Catalogues Plotting +Extras ``` diff --git a/roseau/load_flow/utils/constants.py b/roseau/load_flow/utils/constants.py index eae33041..c1d7b586 100644 --- a/roseau/load_flow/utils/constants.py +++ b/roseau/load_flow/utils/constants.py @@ -38,8 +38,8 @@ ConductorType.CU: Q_(1.2566e-8, "H/m"), ConductorType.AL: Q_(1.2566e-8, "H/m"), ConductorType.AM: Q_(1.2566e-8, "H/m"), - ConductorType.AA: np.nan, # TODO - ConductorType.LA: np.nan, # TODO + ConductorType.AA: Q_(np.nan, "H/m"), # TODO + ConductorType.LA: Q_(np.nan, "H/m"), # TODO } """Magnetic permeability of common conductor materials (H/m).""" @@ -47,8 +47,8 @@ ConductorType.CU: Q_(9.3, "mm"), ConductorType.AL: Q_(112, "mm"), ConductorType.AM: Q_(12.9, "mm"), - ConductorType.AA: np.nan, # TODO - ConductorType.LA: np.nan, # TODO + ConductorType.AA: Q_(np.nan, "mm"), # TODO + ConductorType.LA: Q_(np.nan, "mm"), # TODO } """Skin effect of common conductor materials (mm).""" From 29daa3082cd6375cf6843a253f2b41be5a599d6c Mon Sep 17 00:00:00 2001 From: Ali Hamdan Date: Tue, 19 Sep 2023 18:09:40 +0200 Subject: [PATCH 2/2] Add changelog entry --- doc/Changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Changelog.md b/doc/Changelog.md index 1ad7d719..cd6c232a 100644 --- a/doc/Changelog.md +++ b/doc/Changelog.md @@ -4,6 +4,7 @@ **In development** +- {gh-pr}`132` {gh-issue}`101` Document extra utilities including converters and constants. - {gh-pr}`130` Mark some internal attributes as private, they were previously marked as public. - {gh-pr}`128` Add the properties `z_line`, `y_shunt` and `with_shunt` to the `Line` class. - {gh-pr}`125` Speed-up build of conda workflow using mamba.