Add torques field to TablePumpDescription for PCP pump support

Added optional 'torques' array field to TablePumpDescription class
to support PCP (Progressive Cavity Pump) pump models.

Changes:
- Add torques field to TablePumpDescription with
  validation logic allowing either empty or matching array length
- Update TablePumpDescription schema definition
- Update documentation in TablePumpDescription.txt
- Update test fixtures for schema and docstring generation
- Add documentation reference for torque units
- Update CHANGELOG.rst

ASIM-6417

Author: caio-ramos

CHANGELOG.rst

@@ -8,6 +8,7 @@ CHANGELOG
 
 * Types are now exported and can be verified by type-checkers such as ``mypy``.
 * Add ``progressive_cavity_pump`` as a new pump type option in ``PumpType`` enum.
+* Add ``torques`` field to ``TablePumpDescription`` to support PCP (Progressive Cavity Pump) pump models.
 
 
 1.3.0 (2025-10-07)

docs/source/alfacase_definitions/TablePumpDescription.txt

@@ -12,6 +12,7 @@
             heads: \ :class:`Array <barril.units.Array>`\  = Array(length, [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 122.32415902140673, 101.9367991845056, 91.74311926605505, 76.4525993883792, 50.9683995922528, 0.0, 101.9367991845056, 91.74311926605505, 81.54943934760449, 61.162079510703364, 35.67787971457696, 0.0, 142.71151885830784, 122.32415902140673, 101.9367991845056, 81.54943934760449, 56.065239551478086, 0.0, 137.61467889908258, 114.16921508664628, 96.83995922528032, 77.47196738022426, 53.00713557594292, 0.0], m)
             efficiencies: \ :class:`Array <barril.units.Array>`\  = Array(dimensionless, [0.0, 0.311, 0.511, 0.6, 0.578, 0.2, 0.0, 0.28, 0.46, 0.54, 0.52, 0.18, 0.0, 0.311, 0.511, 0.6, 0.578, 0.2, 0.0, 0.28, 0.46, 0.54, 0.52, 0.18, 0.0, 0.311, 0.511, 0.6, 0.578, 0.2, 0.0, 0.28, 0.46, 0.54, 0.52, 0.18], %)
             powers: \ :class:`Array <barril.units.Array>`\  = Array(power, [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 160714.29, 160714.29, 176086.96, 187500.0, 173076.92, 0.0, 160714.29, 160714.29, 173913.04, 166666.67, 134615.38, 0.0, 192857.14, 192857.14, 195652.17, 200000.0, 190384.62, 0.0, 200000.0, 200000.0, 206521.74, 211111.11, 200000.0, 0.0], W)
+            torques: \ :class:`Array <barril.units.Array>`\  = Array(moment of force, [], N.m)
 
 .. tab:: Schema
 
@@ -38,3 +39,6 @@
             powers:  # optional
                 values: [number]
                 unit: string
+            torques:  # optional
+                values: [number]
+                unit: string

src/alfasim_sdk/_internal/alfacase/alfacase_to_case.py

@@ -1437,6 +1437,7 @@ def load_table_pump_description(
         "heads": get_array_loader(from_unit="m"),
         "efficiencies": get_array_loader(from_unit="%"),
         "powers": get_array_loader(from_unit="W"),
+        "torques": get_array_loader(from_unit="N.m"),
     }
     case_values = to_case_values(document, alfacase_to_case_description)
     item_description = case_description.TablePumpDescription(**case_values)

src/alfasim_sdk/_internal/alfacase/case_description.py

@@ -690,12 +690,16 @@ class TablePumpDescription:
         Pump power values. There a relation between other pump variables and power. In SI units:
         BHP [W] = P [Pa] * Q [m^3/s] / eff [%]
 
+    :ivar torques:
+        Pump torque values. Used for PCP pumps.
+
     .. include:: /alfacase_definitions/TablePumpDescription.txt
 
     .. include:: /alfacase_definitions/list_of_unit_for_angle_per_time.txt
     .. include:: /alfacase_definitions/list_of_unit_for_volume_flow_rate.txt
     .. include:: /alfacase_definitions/list_of_unit_for_volume_fraction.txt
     .. include:: /alfacase_definitions/list_of_unit_for_pressure.txt
+    .. include:: /alfacase_definitions/list_of_unit_for_torque.txt
     """
     speeds: Array = attrib_array(Array("angle per time", [0.0] * 12 + [400.0] * 12 + [600.0] * 12, 'rpm'))
     void_fractions: Array = attrib_array(Array("volume fraction", ([0.0] * 6 + [0.1] * 6) * 3, '-'))
@@ -741,12 +745,15 @@ class TablePumpDescription:
         )
     )
 
+    torques: Array = attrib_array(Array([], 'N.m'))
 
 
     def __attrs_post_init__(self):
         expected_length = len(self.speeds)
         all_fields = list(attr.fields_dict(self.__class__).keys())
-        if any(len(getattr(self, field)) != expected_length for field in all_fields):
+        # torques is optional, so it can be empty or have the expected length
+        fields_to_check = [field for field in all_fields if field != 'torques']
+        if any(len(getattr(self, field)) != expected_length for field in fields_to_check):
             msg = (
                 f"speeds, void_fractions, flow_rates, pressure_boosts, heads, efficiencies and powers must have the "
                 f"same size, got:\n"
@@ -759,6 +766,16 @@ def __attrs_post_init__(self):
                 f"    - {len(self.powers)} items for powers\n"
             )
             raise ValueError(msg)
+        
+        # Validate torques separately: if not empty, it must have the expected length
+        torques_length = len(self.torques)
+        if torques_length != 0 and torques_length != expected_length:
+            msg = (
+                f"torques must be either empty or have the same size as other fields, got:\n"
+                f"    - {expected_length} items expected\n"
+                f"    - {torques_length} items for torques\n"
+            )
+            raise ValueError(msg)
 
 # fmt: on
 

src/alfasim_sdk/_internal/alfacase/schema.py

@@ -757,6 +757,7 @@
         Optional("heads"): Map({"values": Seq(Float()), "unit": Str()}),
         Optional("efficiencies"): Map({"values": Seq(Float()), "unit": Str()}),
         Optional("powers"): Map({"values": Seq(Float()), "unit": Str()}),
+        Optional("torques"): Map({"values": Seq(Float()), "unit": Str()}),
     }
 )
 temperatures_container_description_schema = Map(
@@ -1238,4 +1239,4 @@
         Optional("walls"): Seq(wall_description_schema),
     }
 )
-# [[[end]]] (sum: R2T4gbe3ct)
+# [[[end]]] (sum: pPP2WuWNdo)

tests/alfacase/test_case_description.py

@@ -100,6 +100,26 @@ def test_table_pump_description_length():
             efficiencies=Array([1], "-"),
             powers=Array([1], "W"),
         )
+    
+    # Test torques validation separately
+    expected_msg_torques = dedent(
+        """\
+    torques must be either empty or have the same size as other fields, got:
+        - 2 items expected
+        - 1 items for torques
+    """
+    )
+    with pytest.raises(ValueError, match=re.escape(expected_msg_torques)):
+        case_description.TablePumpDescription(
+            speeds=Array([1, 2], "rpm"),
+            void_fractions=Array([1, 2], "-"),
+            flow_rates=Array([1, 2], "m3/s"),
+            pressure_boosts=Array([1, 2], "bar"),
+            heads=Array([1, 2], "m"),
+            efficiencies=Array([1, 2], "-"),
+            powers=Array([1, 2], "W"),
+            torques=Array([1], "N.m"),
+        )
 
     # Check if the defaults values works well
     case_description.TablePumpDescription()

tests/alfacase/test_generate_case_description_docstring/test_generate_case_description_docstring_TablePumpDescription_.txt

@@ -12,6 +12,7 @@
             heads: \ :class:`Array <barril.units.Array>`\  = Array(length, [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 122.32415902140673, 101.9367991845056, 91.74311926605505, 76.4525993883792, 50.9683995922528, 0.0, 101.9367991845056, 91.74311926605505, 81.54943934760449, 61.162079510703364, 35.67787971457696, 0.0, 142.71151885830784, 122.32415902140673, 101.9367991845056, 81.54943934760449, 56.065239551478086, 0.0, 137.61467889908258, 114.16921508664628, 96.83995922528032, 77.47196738022426, 53.00713557594292, 0.0], m)
             efficiencies: \ :class:`Array <barril.units.Array>`\  = Array(dimensionless, [0.0, 0.311, 0.511, 0.6, 0.578, 0.2, 0.0, 0.28, 0.46, 0.54, 0.52, 0.18, 0.0, 0.311, 0.511, 0.6, 0.578, 0.2, 0.0, 0.28, 0.46, 0.54, 0.52, 0.18, 0.0, 0.311, 0.511, 0.6, 0.578, 0.2, 0.0, 0.28, 0.46, 0.54, 0.52, 0.18], %)
             powers: \ :class:`Array <barril.units.Array>`\  = Array(power, [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 160714.29, 160714.29, 176086.96, 187500.0, 173076.92, 0.0, 160714.29, 160714.29, 173913.04, 166666.67, 134615.38, 0.0, 192857.14, 192857.14, 195652.17, 200000.0, 190384.62, 0.0, 200000.0, 200000.0, 206521.74, 211111.11, 200000.0, 0.0], W)
+            torques: \ :class:`Array <barril.units.Array>`\  = Array(moment of force, [], N.m)
 
 .. tab:: Schema
 
@@ -38,3 +39,6 @@
             powers:  # optional
                 values: [number]
                 unit: string
+            torques:  # optional
+                values: [number]
+                unit: string

tests/alfacase/test_generate_case_schema/test_generate_schema_for_all_cases.txt

@@ -790,6 +790,7 @@ table_pump_description_schema = Map(
         Optional("heads"): Map({"values": Seq(Float()), "unit": Str()}),
         Optional("efficiencies"): Map({"values": Seq(Float()), "unit": Str()}),
         Optional("powers"): Map({"values": Seq(Float()), "unit": Str()}),
+        Optional("torques"): Map({"values": Seq(Float()), "unit": Str()}),
     }
 )
 

tests/common_testing/alfasim_sdk_common_testing/filled_case_descriptions.py

@@ -426,6 +426,7 @@
     heads=Array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], "m") * 1.0e5 / (9.8 * 1000.0),
     efficiencies=Array([0.01, 0.2, 0.4, 0.2, 0.009, 0.18, 0.36, 0.18], "-"),
     powers=Array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], "W"),
+    torques=Array([0.0, 0.0, 0.0, 0.0, 19.1, 22.9, 26.7, 30.6], "N.m"),
 )
 SURGE_VOLUME_OPTIONS_DESCRIPTION = case_description.SurgeVolumeOptionsDescription(
     time_mode=constants.SurgeVolumeTimeMode.UserDefined,