fix(api): Fix floating point errors and backwards incompatibility in volume validation

[SyntaxColoring]

Overview

This fixes two bugs: RQA-2001 and RESC-182.

RQA-2001 is that if you had an incorrect protocol like this:

pipette.pick_up_tip()
pipette.aspirate(50)
pipette.dispense(100)  # bad, invalid volume

...then it has started to raise an exception instead of silently clamping 100 to 50. This is a good thing to do, but it's a backwards-incompatible change, and it should have been behind an apiLevel bump. This PR makes the change opt-in, behind "apiLevel": "2.17".

RESC-182 is related. If you had a correct protocol like this:

requirements = {"robotType": "OT-2", "apiLevel": "2.16"}

def run(protocol):
    tip_rack = protocol.load_labware("opentrons_96_tiprack_300ul", location="9")
    well_plate = protocol.load_labware("opentrons_24_tuberack_eppendorf_1.5ml_safelock_snapcap", location="10")

    pipette = protocol.load_instrument("p300_single_gen2", mount="left", tip_racks=[tip_rack])

    pipette.pick_up_tip()
    pipette.distribute(
        volume=[22.7, 22.7],
        source=well_plate["A1"],
        dest=[well_plate["B1"], well_plate["B2"]],
        air_gap=10,
        new_tip="never",
        disposal_volume=0,
    )
    pipette.drop_tip()

...then it has started to raise "invalid volume" errors stemming from floating point rounding errors. This is more straightforwardly a bug; it should just not do that.

Test Plan

I've tested this with the protocols from the tickets.

Background

The long-standing historical behavior (since #2481 at least) seems to be that we clamp dispenses but do strict bounds-checking on aspirates. I'm not sure why they differed from each other. I'm also not sure how the strict bounds-checking on aspirates never caused any problems with floating point rounding.

In RSS-330 / PR #13546, we added strict bounds-checking to the Protocol Engine dispense command. We mistakenly thought we were fixing an omission and bringing simulation in line with execution, but we were actually making a breaking change to the interface. And, separately, we forgot about floating point error.

Changelog

• At the Protocol Engine level, lean into doing strict bounds-checking everywhere, instead of clamping.
  • Unlike the historical behavior, do it for both aspirates and dispenses.
  • Add a tolerance to account for floating point rounding.
  • This is a potentially breaking change for anyone directly using Protocol Engine (e.g. generating JSON protocols, or using the HTTP /runs API). We could perhaps add a "clamp": true param to dispense to change that, but I suspect it's not worthwhile.
  • I don't believe this is a breaking change for anyone using Protocol Designer, because Protocol Designer already does its own bookkeeping of the pipette volume.
  • This is not a breaking change for anyone using the Python Protocol API, because of the next bullet point.
• Preserve backwards-compatible behavior for Python Protocol API users by adding conditional clamping based on "apiLevel".

Review requests

• Do we agree with the breaking change for the Protocol Engine dispense command?
• Is it correct to apply this bounds-checking to only the virtual pipette handler, or do we also want to do it on the hardware pipette handler?

Risk assessment

Medium.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (7a3b2da) 68.53% compared to head (3a51a90) 68.58%.
Report is 6 commits behind head on edge.

Additional details and impacted files

@@            Coverage Diff             @@
##             edge   #14253      +/-   ##
==========================================
+ Coverage   68.53%   68.58%   +0.04%     
==========================================
  Files        2421     2513      +92     
  Lines       67108    71392    +4284     
  Branches     8823     9089     +266     
==========================================
+ Hits        45993    48961    +2968     
- Misses      19040    20340    +1300     
- Partials     2075     2091      +16     

Flag	Coverage Δ
app	65.53% <ø> (-2.61%)	⬇️
g-code-testing	96.48% <ø> (ø)
notify-server	89.13% <ø> (ø)
protocol-designer	34.93% <ø> (ø)
shared-data	75.12% <ø> (+2.09%)	⬆️
step-generation	86.84% <ø> (-0.07%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
api/src/opentrons/hardware_control/ot3api.py	79.58% <ø> (ø)
...i/src/opentrons/protocol_api/instrument_context.py	89.18% <ø> (ø)
...src/opentrons/protocol_engine/commands/aspirate.py	100.00% <ø> (ø)
...src/opentrons/protocol_engine/commands/dispense.py	100.00% <ø> (ø)
...trons/protocol_engine/commands/pipetting_common.py	100.00% <ø> (ø)
...src/opentrons/protocol_engine/errors/exceptions.py	100.00% <ø> (ø)
...c/opentrons/protocol_engine/execution/pipetting.py	100.00% <ø> (ø)
...pi/src/opentrons/protocol_engine/state/pipettes.py	100.00% <ø> (ø)
...src/opentrons/protocols/api_support/definitions.py	100.00% <ø> (ø)

... and 299 files with indirect coverage changes

[sfoster1]

Yeah, this looks good to me! I agree with the PE dispense change, nice fix.

[jbleon95]

LGTM, keeps everything consistent now.

[ecormany]

If everyone else is cool with this to-do hanging out in the release notes file for now, it's fine with me too. Otherwise, we can offload it to a comment on RTC-384 until the time is right.

[SyntaxColoring]

I'm not sure what the deal was with the timing out G-Code-Confirm test, but it works when I trigger it manually.

I'm unable to easily test on an actual robot at the moment because of unrelated boot problems, but I'm satisfied with our automated test coverage for now.