Add missing information and improve performance (#306)

alihamdan · web-flow · commit 91189494f69f · 2025-01-02T20:15:45.000+01:00
- Add the following missing information to `results_to_dict` with
`full=True`:
  - `loading` for lines and transformers
  - `voltage_levels` for buses
  - `voltages` for loads and sources
- Add the following missing information to network dataframes:
  - `tap` for `en.transformers_frame`.
  - `element_type` for `potential_refs_frame` (can be `ground` or `bus`)
- Improve the performance of `res_violated` of buses, lines and
transformers by not using quantity.m internally
- Improve the performance of network frames by avoiding creating two
dataframes
- Improve the error message when trying to connect a load with the same
ID as an existing one. We now show the type of the old load in the
message.
diff --git a/doc/Changelog.md b/doc/Changelog.md
@@ -19,6 +19,12 @@ og:description: See what's new in the latest release of Roseau Load Flow !
 
 ## Unreleased
 
+- {gh-pr}`305` Add missing `tap` column to `en.transformers_frame`.
+- {gh-pr}`305` Add `element_type` column to `en.potential_refs_frame` to indicate if the potential
+  reference is connected to a bus or a ground.
+- {gh-pr}`305` Add missing information to `results_to_dict` with `full=True`. This adds `loading` to
+  lines and transformers, `voltage_levels` to buses, and `voltages` to loads and sources.
+- {gh-pr}`305` Improve the performance of `res_violated` of buses, lines and transformers.
 - {gh-pr}`304` Add top-level modules `rlf.constants` and `rlf.types`. The old modules in the `utils`
   package are deprecated and will be removed in a future release. The `utils` package is for internal
   use only and should not be considered stable.
diff --git a/doc/models/Bus.md b/doc/models/Bus.md
@@ -80,7 +80,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_((0.3 + 0.35j) * np.eye(4), "ohm/k
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The neutral of bus1 is fixed at potential 0
diff --git a/doc/models/Line/ShuntLine.md b/doc/models/Line/ShuntLine.md
@@ -121,7 +121,7 @@ line = rlf.Line(
 )
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 
diff --git a/doc/models/Line/SimplifiedLine.md b/doc/models/Line/SimplifiedLine.md
@@ -66,7 +66,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_(0.35 * np.eye(4), "ohm/km"))
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The potential of the neutral of bus1 is fixed at 0V
diff --git a/doc/models/Load/CurrentLoad.md b/doc/models/Load/CurrentLoad.md
@@ -64,7 +64,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_(0.35 * np.eye(4), "ohm/km"))
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The potential of the neutral of bus1 is fixed at 0V
diff --git a/doc/models/Load/FlexibleLoad/FeasibleDomain.md b/doc/models/Load/FlexibleLoad/FeasibleDomain.md
@@ -42,7 +42,7 @@ import roseau.load_flow as rlf
 
 # A voltage source
 bus = rlf.Bus(id="bus", phases="abcn")
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus, voltages=rlf.Q_(un, "V"))
 
 # A potential ref
diff --git a/doc/models/Load/ImpedanceLoad.md b/doc/models/Load/ImpedanceLoad.md
@@ -61,7 +61,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_(0.35 * np.eye(4), "ohm/km"))
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The potential of the neutral of bus1 is fixed at 0V
diff --git a/doc/models/Load/PowerLoad.md b/doc/models/Load/PowerLoad.md
@@ -64,7 +64,7 @@ lp = rlf.LineParameters(id="lp", z_line=rlf.Q_(0.35 * np.eye(4), "ohm/km"))
 line = rlf.Line(id="line", bus1=bus1, bus2=bus2, parameters=lp, length=rlf.Q_(1, "km"))
 
 # A voltage source on the first bus
-un = 400 / np.sqrt(3)
+un = 400 / rlf.SQRT3
 vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))
 
 # The potential of the neutral of bus1 is fixed at 0V
diff --git a/doc/models/Switch.md b/doc/models/Switch.md
@@ -52,7 +52,7 @@ bus2 = rlf.Bus(id="bus2", phases="abcn")
 switch = rlf.Switch(id="switch", bus1=bus1, bus2=bus2)
 
 # A voltage source on the first bus
-vs = rlf.VoltageSource(id="source", bus=bus1, voltages=400 / np.sqrt(3))
+vs = rlf.VoltageSource(id="source", bus=bus1, voltages=400 / rlf.SQRT3)
 
 # The potential of the neutral of bus1 is fixed at 0V
 pref = rlf.PotentialRef(id="pref", element=bus1)
diff --git a/doc/models/Transformer/Single_Phase_Transformer.md b/doc/models/Transformer/Single_Phase_Transformer.md
@@ -75,7 +75,7 @@ import roseau.load_flow as rlf
 bus1 = rlf.Bus(id="bus1", phases="abcn")
 pref1 = rlf.PotentialRef(id="pref1", element=bus1)
 
-vs = rlf.VoltageSource(id="vs", bus=bus1, voltages=400 / np.sqrt(3))
+vs = rlf.VoltageSource(id="vs", bus=bus1, voltages=400 / rlf.SQRT3)
 
 # Create the load bus and the load
 bus2 = rlf.Bus(id="bus2", phases="an")
diff --git a/doc/usage/Connecting_Elements.md b/doc/usage/Connecting_Elements.md
@@ -31,7 +31,7 @@ Let's take the electrical network of the [Getting started page](usage-getting-st
 ... pref = rlf.PotentialRef(id="pref", element=ground)
 ... ground.connect(source_bus, phase="n")
 
->>> un = 400 / np.sqrt(3)
+>>> un = 400 / rlf.SQRT3
 ... vs = rlf.VoltageSource(id="vs", bus=source_bus, voltages=un)
 
 >>> load = rlf.PowerLoad(id="load", bus=load_bus, powers=[10e3 + 0j, 10e3, 10e3])  # VA
diff --git a/doc/usage/Getting_Started.md b/doc/usage/Getting_Started.md
@@ -116,7 +116,7 @@ line and a constant power load. This network is a low voltage network (three-pha
 
 >>> # Create a three-phase voltage source at the first bus
 ... # (voltages are phase-to-neutral because the source's phases include a neutral)
-... vs = rlf.VoltageSource(id="vs", bus=source_bus, voltages=un / np.sqrt(3))
+... vs = rlf.VoltageSource(id="vs", bus=source_bus, voltages=un / rlf.SQRT3)
 
 >>> # Add a 30kW load at the second bus (balanced load, 10 kW per phase)
 ... load = rlf.PowerLoad(id="load", bus=load_bus, powers=[10e3 + 0j, 10e3, 10e3])  # In VA
@@ -140,7 +140,7 @@ to `"abc"`:
 ... )
 ```
 
-Note the use of `un` (and not `un / np.sqrt(3)`) as the source voltages as they now represent the phase-to-phase
+Note the use of `un` (and not `un / rlf.SQRT3`) as the source voltages as they now represent the phase-to-phase
 voltages. This is because everywhere in `roseau-load-flow`, the `voltages` of an element depend on
 the element's `phases`. Voltages of elements connected in a _Star (wye)_ configuration (elements
 that have a neutral connection indicated by the presence of the `'n'` character in their `phases`
diff --git a/doc/usage/Short_Circuit.md b/doc/usage/Short_Circuit.md
@@ -39,7 +39,7 @@ is impossible.
 ...     pref = rlf.PotentialRef(id="pref", element=ground)
 ...     ground.connect(bus=source_bus)
 ...     # Create a LV source at the first bus
-...     un = 400 / np.sqrt(3)
+...     un = 400 / rlf.SQRT3
 ...     vs = rlf.VoltageSource(id="vs", bus=source_bus, phases="abcn", voltages=un)
 ...     # Add LV lines
 ...     lp1 = rlf.LineParameters.from_geometry(
diff --git a/pyproject.toml b/pyproject.toml
@@ -113,7 +113,7 @@ docstring-code-format = true
 branch = false
 omit = ["roseau/load_flow/__about__.py"]
 plugins = ["coverage_conditional_plugin"]
-source = ["roseau"]
+source = ["roseau/load_flow/"]
 
 [tool.coverage.coverage_conditional_plugin.rules]
 no-cover-if-py-gte-311 = "sys_version_info >= (3, 11)"
diff --git a/roseau/load_flow/io/dgs/sources.py b/roseau/load_flow/io/dgs/sources.py
@@ -1,8 +1,8 @@
 import logging
 
-import numpy as np
 import pandas as pd
 
+from roseau.load_flow.constants import SQRT3
 from roseau.load_flow.models import Bus, VoltageSource
 from roseau.load_flow.typing import Id
 
@@ -37,7 +37,7 @@ def generate_sources(
     for source_id in elm_xnet.index:
         id_sta_cubic_source = elm_xnet.at[source_id, "bus1"]  # id of the cubicle connecting the source and its bus
         bus_id = sta_cubic.at[id_sta_cubic_source, "cterm"]  # id of the bus to which the source is connected
-        un = elm_term.at[bus_id, "uknom"] / np.sqrt(3) * 1e3  # phase-to-neutral voltage (V)
+        un = elm_term.at[bus_id, "uknom"] / SQRT3 * 1e3  # phase-to-neutral voltage (V)
         tap = elm_xnet.at[source_id, "usetp"]  # tap voltage (p.u.)
         voltage = un * tap
         source_bus = buses[bus_id]
diff --git a/roseau/load_flow/models/buses.py b/roseau/load_flow/models/buses.py
@@ -9,6 +9,7 @@
 from shapely.geometry.base import BaseGeometry
 from typing_extensions import Self
 
+from roseau.load_flow.constants import SQRT3
 from roseau.load_flow.converters import _calculate_voltages, calculate_voltage_phases
 from roseau.load_flow.exceptions import RoseauLoadFlowException, RoseauLoadFlowExceptionCode
 from roseau.load_flow.models.core import Element
@@ -149,7 +150,7 @@ def res_potentials(self) -> Q_[ComplexArray]:
 
     def _res_voltages_getter(self, warning: bool, potentials: ComplexArray | None = None) -> ComplexArray:
         if potentials is None:
-            potentials = np.array(self._res_potentials_getter(warning=warning))
+            potentials = self._res_potentials_getter(warning=warning)
         return _calculate_voltages(potentials, self.phases)
 
     @property
@@ -163,16 +164,20 @@ def res_voltages(self) -> Q_[ComplexArray]:
         """
         return self._res_voltages_getter(warning=True)
 
-    @property
-    def res_voltage_levels(self) -> Q_[FloatArray] | None:
-        """The load flow result of the bus voltage levels (unitless)."""
+    def _res_voltage_levels_getter(self, warning: bool) -> FloatArray | None:
         if self._nominal_voltage is None:
             return None
-        voltages_abs = abs(self._res_voltages_getter(warning=True))
+        voltages_abs = abs(self._res_voltages_getter(warning=warning))
         if "n" in self.phases:
-            return Q_(np.sqrt(3) * voltages_abs / self._nominal_voltage, "")
+            return SQRT3 * voltages_abs / self._nominal_voltage
         else:
-            return Q_(voltages_abs / self._nominal_voltage, "")
+            return voltages_abs / self._nominal_voltage
+
+    @property
+    def res_voltage_levels(self) -> Q_[FloatArray] | None:
+        """The load flow result of the bus voltage levels (unitless)."""
+        voltage_levels = self._res_voltage_levels_getter(warning=True)
+        return None if voltage_levels is None else Q_(voltage_levels, "")
 
     @cached_property
     def voltage_phases(self) -> list[str]:
@@ -294,23 +299,17 @@ def res_violated(self) -> bool | None:
 
         Returns ``None`` if the bus has no voltage limits are not set.
         """
-        if (self._min_voltage_level is None and self._max_voltage_level is None) or self._nominal_voltage is None:
+        u_min = self._min_voltage_level
+        u_max = self._max_voltage_level
+        if u_min is None and u_max is None:
             return None
-        voltages = abs(self._res_voltages_getter(warning=True))
-        if "n" in self.phases:
-            voltages_level = np.sqrt(3) * voltages / self._nominal_voltage
-        else:
-            voltages_level = voltages / self._nominal_voltage
-        if self._min_voltage_level is None:
-            assert self._max_voltage_level is not None
-            return float(max(voltages_level)) > self._max_voltage_level
-        elif self._max_voltage_level is None:
-            return float(min(voltages_level)) < self._min_voltage_level
-        else:
-            return (
-                float(min(voltages_level)) < self._min_voltage_level
-                or float(max(voltages_level)) > self._max_voltage_level
-            )
+        u_nom = self._nominal_voltage
+        if u_nom is None:
+            return None
+        voltage_levels = self._res_voltage_levels_getter(warning=True)
+        return (u_min is not None and bool(min(voltage_levels) < u_min)) or (
+            u_max is not None and bool(max(voltage_levels) > u_max)
+        )
 
     def propagate_limits(self, force: bool = False) -> None:
         """Propagate the voltage limits to galvanically connected buses.
@@ -489,9 +488,10 @@ def _results_to_dict(self, warning: bool, full: bool) -> JsonDict:
             "potentials": [[v.real, v.imag] for v in potentials],
         }
         if full:
-            res["voltages"] = [
-                [v.real, v.imag] for v in self._res_voltages_getter(warning=False, potentials=potentials)
-            ]
+            voltages = self._res_voltages_getter(warning=False, potentials=potentials)
+            res["voltages"] = [[v.real, v.imag] for v in voltages]
+            voltage_levels = self._res_voltage_levels_getter(warning=False)
+            res["voltage_levels"] = None if voltage_levels is None else voltage_levels.tolist()
         return res
 
     def add_short_circuit(self, *phases: str, ground: "Ground | None" = None) -> None:
diff --git a/roseau/load_flow/models/lines/lines.py b/roseau/load_flow/models/lines/lines.py
@@ -343,23 +343,26 @@ def res_power_losses(self) -> Q_[ComplexArray]:
         """Get the power losses in the line (in VA)."""
         return self._res_power_losses_getter(warning=True)
 
+    def _res_loading_getter(self, warning: bool) -> FloatArray | None:
+        if (amp := self._parameters._ampacities) is None:
+            return None
+        currents1, currents2 = self._res_currents_getter(warning)
+        return np.maximum(abs(currents1), abs(currents2)) / amp
+
     @property
     def res_loading(self) -> Q_[FloatArray] | None:
         """The loading of the line (unitless) if ``self.parameters.ampacities`` is set, else ``None``."""
-        if (amp := self._parameters._ampacities) is None:
-            return None
-        currents1, currents2 = self._res_currents_getter(warning=True)
-        return Q_(np.maximum(abs(currents1), abs(currents2)) / amp, "")
+        loading = self._res_loading_getter(warning=True)
+        return None if loading is None else Q_(loading, "")
 
     @property
     def res_violated(self) -> bool | None:
         """Whether the line current loading exceeds its maximal loading.
 
         Returns ``None`` if the ``self.parameters.ampacities`` is not set.
         """
-        if (loading := self.res_loading) is None:
-            return None
-        return bool((loading.m > self._max_loading).any())
+        loading = self._res_loading_getter(warning=True)
+        return None if loading is None else bool((loading > self._max_loading).any())
 
     #
     # Json Mixin interface
@@ -423,4 +426,6 @@ def _results_to_dict(self, warning: bool, full: bool) -> JsonDict:
             results["shunt_power_losses"] = [
                 [s.real, s.imag] for s in self._res_shunt_power_losses_getter(warning=False)
             ]
+            loading = self._res_loading_getter(warning=False)
+            results["loading"] = None if loading is None else loading.tolist()
         return results
diff --git a/roseau/load_flow/models/lines/parameters.py b/roseau/load_flow/models/lines/parameters.py
@@ -13,7 +13,7 @@
 from typing_extensions import Self
 
 from roseau.load_flow._compat import StrEnum
-from roseau.load_flow.constants import EPSILON_0, EPSILON_R, MU_0, OMEGA, PI, RHO, TAN_D, F
+from roseau.load_flow.constants import EPSILON_0, EPSILON_R, MU_0, OMEGA, PI, RHO, SQRT3, TAN_D, F
 from roseau.load_flow.exceptions import RoseauLoadFlowException, RoseauLoadFlowExceptionCode
 from roseau.load_flow.types import Insulator, LineType, Material
 from roseau.load_flow.typing import (
@@ -765,7 +765,7 @@ def _get_geometric_configuration(
                 msg = f"The height of a '{line_type}' line must be a positive number."
                 logger.error(msg)
                 raise RoseauLoadFlowException(msg=msg, code=RoseauLoadFlowExceptionCode.BAD_LINE_MODEL)
-            x = np.sqrt(3) * external_diameter / 8
+            x = SQRT3 * external_diameter / 8
             coord = np.array(
                 [
                     [-x, height + external_diameter / 8],
diff --git a/roseau/load_flow/models/loads/loads.py b/roseau/load_flow/models/loads/loads.py
@@ -317,6 +317,8 @@ def _results_to_dict(self, warning: bool, full: bool) -> JsonDict:
         if full:
             powers = self._res_powers_getter(warning=False, currents=currents, potentials=potentials)
             results["powers"] = [[s.real, s.imag] for s in powers]
+            voltages = _calculate_voltages(potentials, self.phases)
+            results["voltages"] = [[v.real, v.imag] for v in voltages]
         return results
 
 
diff --git a/roseau/load_flow/models/sources.py b/roseau/load_flow/models/sources.py
@@ -321,4 +321,6 @@ def _results_to_dict(self, warning: bool, full: bool) -> JsonDict:
         if full:
             powers = self._res_powers_getter(warning=False, currents=currents, potentials=potentials)
             results["powers"] = [[s.real, s.imag] for s in powers]
+            voltages = _calculate_voltages(potentials, self.phases)
+            results["voltages"] = [[v.real, v.imag] for v in voltages]
         return results
diff --git a/roseau/load_flow/models/transformers/parameters.py b/roseau/load_flow/models/transformers/parameters.py
@@ -8,6 +8,7 @@
 import pandas as pd
 from typing_extensions import Self
 
+from roseau.load_flow.constants import SQRT3
 from roseau.load_flow.exceptions import RoseauLoadFlowException, RoseauLoadFlowExceptionCode
 from roseau.load_flow.typing import FloatArrayLike1D, Id, JsonDict
 from roseau.load_flow.units import Q_, ureg_wraps
@@ -879,7 +880,7 @@ def _compute_open_circuit_parameters(self, solve_kwargs: JsonDict | None = None)
             phases_hv = "abc" if self.winding1[0] == "D" else "abcn"
             phases_lv = "abc" if self.winding2[0] == "d" else "abcn"
             if "n" in phases_hv:
-                voltage /= np.sqrt(3)
+                voltage /= SQRT3
 
         bus_hv = Bus(id="BusHV", phases=phases_hv)
         bus_lv = Bus(id="BusLV", phases=phases_lv)
@@ -894,7 +895,7 @@ def _compute_open_circuit_parameters(self, solve_kwargs: JsonDict | None = None)
         i_primary = abs(transformer.res_currents[0].m[0])
         i_nom = self._sn / self._uhv
         if self.type == "three-phase":
-            i_nom /= np.sqrt(3)
+            i_nom /= SQRT3
 
         # Additional checks
         u_secondary = abs(bus_lv.res_voltages.m)
@@ -903,7 +904,7 @@ def _compute_open_circuit_parameters(self, solve_kwargs: JsonDict | None = None)
         elif self.type == "center-tapped":
             expected_u_secondary = self._ulv / 2
         else:
-            expected_u_secondary = self._ulv / np.sqrt(3)
+            expected_u_secondary = self._ulv / SQRT3
         np.testing.assert_allclose(u_secondary, expected_u_secondary)
 
         return p_primary, i_primary / i_nom
@@ -940,7 +941,7 @@ def _compute_short_circuit_parameters(self, solve_kwargs: JsonDict | None = None
             phases_hv = "abc" if self.winding1[0] == "D" else "abcn"
             phases_lv = "abc" if self.winding2[0] == "d" else "abcn"
             if "n" in phases_hv:
-                voltage /= np.sqrt(3)
+                voltage /= SQRT3
 
         bus_hv = Bus(id="BusHV", phases=phases_hv)
         bus_lv = Bus(id="BusLV", phases=phases_lv)
@@ -956,7 +957,7 @@ def _compute_short_circuit_parameters(self, solve_kwargs: JsonDict | None = None
         # Additional check
         i_nom = self._sn / self._ulv
         if self.type == "three-phase":
-            i_nom /= np.sqrt(3)  # I = S3ph / (sqrt(3) * U)
+            i_nom /= SQRT3  # I = S3ph / (sqrt(3) * U)
         i_secondary = abs(transformer.res_currents[1].m[0])
         np.testing.assert_allclose(i_secondary, i_nom)
 
diff --git a/roseau/load_flow/models/transformers/transformers.py b/roseau/load_flow/models/transformers/transformers.py
diff --git a/roseau/load_flow/network.py b/roseau/load_flow/network.py
diff --git a/roseau/load_flow/tests/test_electrical_network.py b/roseau/load_flow/tests/test_electrical_network.py
diff --git a/roseau/load_flow/utils/__init__.py b/roseau/load_flow/utils/__init__.py
diff --git a/roseau/load_flow/utils/helpers.py b/roseau/load_flow/utils/helpers.py
diff --git a/roseau/load_flow/utils/mixins.py b/roseau/load_flow/utils/mixins.py
diff --git a/scripts/generate_test_networks.py b/scripts/generate_test_networks.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -121,7 +121,7 @@ line = rlf.Line(`
`121`	`121`	`)`
`122`	`122`
`123`	`123`	`# A voltage source on the first bus`
`124`		`-un = 400 / np.sqrt(3)`
	`124`	`+un = 400 / rlf.SQRT3`
`125`	`125`	`vs = rlf.VoltageSource(id="source", bus=bus1, voltages=rlf.Q_(un, "V"))`
`126`	`126`
`127`	`127`