feat(api): don't make UserDefinedVolumes require (max_height, max_volume) (#19066)

Author: caila-marashaj

api/src/opentrons/protocol_engine/errors/__init__.py

@@ -78,6 +78,7 @@
     LiquidHeightUnknownError,
     LiquidVolumeUnknownError,
     IncompleteLabwareDefinitionError,
+    InvalidUserDefinedVolumesError,
     IncompleteWellDefinitionError,
     OperationLocationNotInWellError,
     InvalidDispenseVolumeError,
@@ -180,6 +181,7 @@
     "LiquidHeightUnknownError",
     "LiquidVolumeUnknownError",
     "IncompleteLabwareDefinitionError",
+    "InvalidUserDefinedVolumesError",
     "IncompleteWellDefinitionError",
     "OperationLocationNotInWellError",
     "InvalidDispenseVolumeError",

api/src/opentrons/protocol_engine/errors/exceptions.py

@@ -1196,6 +1196,19 @@ def __init__(
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class InvalidUserDefinedVolumesError(ProtocolEngineError):
+    """Raised when a UserDefinedVolumes type InnerLabwareDefinition is invalid."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an InvalidUserDefinedVolumesError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class IncompleteWellDefinitionError(ProtocolEngineError):
     """Raised when a well definition lacks a geometryDefinitionId."""
 

api/src/opentrons/protocol_engine/state/inner_well_math_utils.py

@@ -3,7 +3,7 @@
 from numpy import pi, iscomplex, roots, real
 from math import isclose
 
-from ..errors.exceptions import InvalidLiquidHeightFound
+from ..errors.exceptions import InvalidLiquidHeightFound, InvalidUserDefinedVolumesError
 
 from opentrons.protocol_engine.types.liquid_level_detection import (
     LiquidTrackingType,
@@ -363,10 +363,12 @@ def _find_volume_in_partial_frustum(
 def _linear_interpolation(
     interpolating_from: List[float], to_interpolate: List[float], target_val: float
 ) -> float:
-    assert len(interpolating_from) == len(to_interpolate), "Invalid height/volume data"
-    assert (
-        interpolating_from[0] == to_interpolate[0] == 0.0
-    ), "height and volume data must start with 0.0"
+    if len(interpolating_from) != len(to_interpolate):
+        raise InvalidUserDefinedVolumesError(
+            "Height and volume data have unequal sizes"
+        )
+    if not (interpolating_from[0] == to_interpolate[0] == 0.0):
+        raise ValueError("linear interpolation datasets must start with 0.0")
 
     if target_val == 0.0:
         return 0.0
@@ -395,7 +397,7 @@ def find_volume_user_defined_volumes(
     max_height = sorted_volume_map[-1].height
     if target_height < 0 or target_height > max_height:
         raise InvalidLiquidHeightFound(
-            f"Invalid target height {target_height} mm; max well height is {max_height} mm."
+            f"Invalid target height {target_height} mm; greatest well height in InnerLabwareGeometry is {max_height} mm."
         )
     volumes = [0.0]
     heights = [0.0]
@@ -426,7 +428,7 @@ def find_height_user_defined_volumes(
     max_volume = sorted_volume_map[-1].volume
     if target_volume < 0 or target_volume > max_volume:
         raise InvalidLiquidHeightFound(
-            f"Invalid target volume {target_volume} mm; max well volume is {max_volume} uL."
+            f"Invalid target volume {target_volume}µL; greatest well volume in InnerLabwareGeometry is {max_volume}µL."
         )
 
     volumes = [0.0]
@@ -516,7 +518,7 @@ def _find_height_in_partial_frustum(
     # also this code should never be reached bc an invalid target volume should be changed
     # by find_height_at_well_volume
     raise InvalidLiquidHeightFound(
-        f"Target volume {target_volume} uL exceeds the well volume {total_well_volume} uL."
+        f"Target volume {target_volume}µL exceeds the well volume {total_well_volume}µL."
     )
 
 

api/tests/opentrons/protocols/geometry/test_inner_well_math_utils.py

@@ -404,6 +404,61 @@ def test_volume_at_section_boundary_heights(well: List[Any]) -> None:
         assert isclose(cast(float, top_ul), tot_ul)
 
 
+def test_user_volumes_raises_error_for_invalid_target(
+    user_defined_volumes_params: Dict[str, Any]
+) -> None:
+    """Test that UserDefinedVolumes calculations reject target inputs that are not allowed."""
+    user_defined_volumes_obj = user_defined_volumes_params["obj"]
+    max_defined_height = user_defined_volumes_obj.heightToVolumeMap[-1].height
+    max_defined_volume = user_defined_volumes_obj.heightToVolumeMap[-1].volume
+    min_defined_height = user_defined_volumes_obj.heightToVolumeMap[0].height
+    min_defined_volume = user_defined_volumes_obj.heightToVolumeMap[0].volume
+
+    # less than 0 should raise an error
+    with pytest.raises(InvalidLiquidHeightFound):
+        find_volume_user_defined_volumes(
+            target_height=-0.01, well_geometry=user_defined_volumes_obj
+        )
+    with pytest.raises(InvalidLiquidHeightFound):
+        find_height_user_defined_volumes(
+            target_volume=-0.01, well_geometry=user_defined_volumes_obj
+        )
+
+    # between 0 and min defined height should be ok
+    vol = find_volume_user_defined_volumes(
+        target_height=(min_defined_height / 2), well_geometry=user_defined_volumes_obj
+    )
+    assert vol is not None
+    height = find_height_user_defined_volumes(
+        target_volume=(min_defined_volume / 2), well_geometry=user_defined_volumes_obj
+    )
+    assert height is not None
+
+    # betwen min defined height and max defined height should be ok
+    vol = find_volume_user_defined_volumes(
+        target_height=((min_defined_height + max_defined_height) / 2),
+        well_geometry=user_defined_volumes_obj,
+    )
+    assert vol is not None
+    height = find_height_user_defined_volumes(
+        target_volume=((min_defined_volume + max_defined_volume) / 2),
+        well_geometry=user_defined_volumes_obj,
+    )
+    assert height is not None
+
+    # any greater than max defined height should cause an error
+    with pytest.raises(InvalidLiquidHeightFound):
+        find_volume_user_defined_volumes(
+            target_height=max_defined_height + 0.01,
+            well_geometry=user_defined_volumes_obj,
+        )
+    with pytest.raises(InvalidLiquidHeightFound):
+        find_height_user_defined_volumes(
+            target_volume=max_defined_volume + 0.01,
+            well_geometry=user_defined_volumes_obj,
+        )
+
+
 def test_get_user_volumes(user_defined_volumes_params: Dict[str, Any]) -> None:
     """Test linear interpolation math for user-defined volumes."""
     user_defined_volumes_obj = user_defined_volumes_params["obj"]

shared-data/js/__tests__/labwareDefSchemaV2.test.ts

@@ -285,21 +285,6 @@ const checkGeometryDefinitions = (labwareDef: LabwareDefinition2): void => {
     }
   })
 
-  test('the last entry for UserDefinedVolumes should be the max volume of the well at its depth', () => {
-    for (const well of Object.values(labwareDef.wells)) {
-      const wellGeometryId = well.geometryDefinitionId
-      if (wellGeometryId === undefined) return
-      const wellDepth = well.depth
-      const innerGeometryObject =
-        labwareDef.innerLabwareGeometry?.[wellGeometryId]
-      if (innerGeometryObject === undefined) return
-      if (!isUserDefinedVolumes(innerGeometryObject)) return
-      const pairingList = innerGeometryObject.heightToVolumeMap
-      const firstEntry = pairingList[0]
-      expect(firstEntry.height).toStrictEqual(wellDepth)
-    }
-  })
-
   test('the bottom of a well geometry should be at height 0', () => {
     for (const geometry of Object.values(
       labwareDef.innerLabwareGeometry ?? {}
@@ -341,12 +326,6 @@ const checkGeometryDefinitions = (labwareDef: LabwareDefinition2): void => {
     return 'sections' in def
   }
 
-  function isUserDefinedVolumes(
-    def: InnerWellGeometry | UserDefinedVolumes
-  ): def is UserDefinedVolumes {
-    return 'heightToVolumeMap' in def
-  }
-
   test("a well's depth should equal the height of its geometry", () => {
     for (const well of Object.values(labwareDef.wells)) {
       const wellGeometryId = well.geometryDefinitionId