Deprecate LineParameters.from_name_lv method

doc/Changelog.md

@@ -4,6 +4,8 @@
 
 **In development**
 
+- {gh-pr}`148` {gh-issue}`122` deprecate `LineParameters.from_name_lv()` in favor of the more generic
+  `LineParameters.from_geometry()`. The method will be removed in a future release.
 - {gh-pr}`142` {gh-issue}`136` Add `Bus.res_voltage_unbalance()` method to get the Voltage Unbalance
   Factor (VUF) as defined by the IEC standard IEC 61000-3-14.
 - {gh-pr}`141` {gh-issue}`137` Add `ElectricalNetwork.to_graph()` to get a `networkx.Graph` object

doc/usage/Connecting_Elements.md

@@ -118,7 +118,16 @@ Creating a line connecting the `load_bus` (belonging to the network `en`) and ou
 belong to a network) will propagate the network to the new elements.
 
 ```pycon
->>> lp_u_al_240 = LineParameters.from_name_lv("U_AL_240")
+>>> lp_u_al_240 = LineParameters.from_geometry(
+...     "U_AL_240",
+...     line_type=LineType.UNDERGROUND,
+...     conductor_type=ConductorType.AL,
+...     insulator_type=InsulatorType.PVC,
+...     section=240,
+...     section_neutral=240,
+...     height=Q_(-1.5, "m"),
+...     external_diameter=Q_(40, "mm"),
+... )
 >>> new_line = Line(
 ...     id="new_line",
 ...     bus1=load_bus,

doc/usage/Flexible_Loads.md

@@ -56,7 +56,16 @@ a Delta-Wye transformer and a small LV network.
 ... )
 
 >>> # Add the LV network elements
-... lp = LineParameters.from_name_lv("U_AL_150")
+... lp = LineParameters.from_geometry(
+...     "U_AL_150",
+...     line_type=LineType.UNDERGROUND,
+...     conductor_type=ConductorType.AL,
+...     insulator_type=InsulatorType.PVC,
+...     section=150,
+...     section_neutral=150,
+...     height=Q_(-1.5, "m"),
+...     external_diameter=Q_(40, "mm"),
+... )
 ... bus1 = Bus(id="bus1", phases="abcn")
 ... bus2 = Bus(id="bus2", phases="abcn")
 ... load_bus1 = Bus(id="load_bus1", phases="abcn")

doc/usage/Short_Circuit.md

@@ -31,11 +31,29 @@ is impossible.
 ... vs = VoltageSource(id="vs", bus=source_bus, phases="abcn", voltages=source_voltages)
 
 >>> # Add LV lines
-... lp1 = LineParameters.from_name_lv("U_AL_240")
+... lp1 = LineParameters.from_geometry(
+...     "U_AL_240",
+...     line_type=LineType.UNDERGROUND,
+...     conductor_type=ConductorType.AL,
+...     insulator_type=InsulatorType.PVC,
+...     section=240,
+...     section_neutral=240,
+...     height=Q_(-1.5, "m"),
+...     external_diameter=Q_(40, "mm"),
+... )
 ... line1 = Line(
 ...     id="line1", bus1=source_bus, bus2=bus1, parameters=lp1, length=1.0, ground=ground
 ... )
-... lp2 = LineParameters.from_name_lv("U_AL_150")
+... lp2 = LineParameters.from_geometry(
+...     "U_AL_150",
+...     line_type=LineType.UNDERGROUND,
+...     conductor_type=ConductorType.AL,
+...     insulator_type=InsulatorType.PVC,
+...     section=150,
+...     section_neutral=150,
+...     height=Q_(-1.5, "m"),
+...     external_diameter=Q_(40, "mm"),
+... )
 ... line2 = Line(id="line2", bus1=bus1, bus2=bus2, parameters=lp2, length=2.0, ground=ground)
 
 >>> # Create network

roseau/load_flow/models/lines/parameters.py

@@ -5,7 +5,7 @@
 import numpy as np
 import numpy.linalg as nplin
 import pandas as pd
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
 from roseau.load_flow.exceptions import RoseauLoadFlowException, RoseauLoadFlowExceptionCode
 from roseau.load_flow.typing import ComplexArray, ComplexArrayLike2D, Id, JsonDict
@@ -493,6 +493,11 @@ def _geometry_to_zy(
         return z_line, y_shunt
 
     @classmethod
+    @deprecated(
+        "The method LineParameters.from_name_lv() is deprecated and will be removed in a future "
+        "version. Use LineParameters.from_geometry() instead.",
+        category=FutureWarning,
+    )
     @ureg_wraps(None, (None, None, "mm²", "m", "mm", "A"), strict=False)
     def from_name_lv(
         cls,
@@ -524,6 +529,9 @@ def from_name_lv(
 
         Returns:
             The corresponding line parameters.
+
+        .. deprecated:: 0.6.0
+            Use :meth:`LineParameters.from_geometry` instead.
         """
         match = cls._REGEXP_LINE_TYPE_NAME.fullmatch(string=name)
         if not match:

roseau/load_flow/models/tests/test_line_parameters.py

@@ -314,17 +314,19 @@ def test_sym():
 
 
 def test_from_name_lv():
-    with pytest.raises(RoseauLoadFlowException) as e:
+    with pytest.raises(RoseauLoadFlowException) as e, pytest.warns(FutureWarning):
         LineParameters.from_name_lv("totoS_Al_150")
     assert "The line type name does not follow the syntax rule." in e.value.msg
     assert e.value.code == RoseauLoadFlowExceptionCode.BAD_TYPE_NAME_SYNTAX
 
-    lp = LineParameters.from_name_lv("S_AL_150")
+    with pytest.warns(FutureWarning):
+        lp = LineParameters.from_name_lv("S_AL_150")
     assert lp.z_line.shape == (4, 4)
     assert lp.y_shunt.shape == (4, 4)
     assert (lp.z_line.real >= 0).all().all()
 
-    lp2 = LineParameters.from_name_lv("U_AL_150")
+    with pytest.warns(FutureWarning):
+        lp2 = LineParameters.from_name_lv("U_AL_150")
     npt.assert_allclose(lp2.z_line.m_as("ohm/km"), lp.z_line.m_as("ohm/km"))
     npt.assert_allclose(lp2.y_shunt.m_as("S/km"), lp.y_shunt.m_as("S/km"), rtol=1e-4)