feat(api): Support slotFootprintAsChild and slotFootprintAsParent locating features

[mjhuff]

Works toward EXEC-77 and closes EXEC-1487

Overview

Adds support for the slotFootprintAsChild and slotFootprintAsParent locating features as defined in the locating features v2 proposal.

Notably, this adds support for parent-child stackups that comprise of:

• A parent deck item with a spring with a child deck item on top of it (ex, a deck slot with a labware).
• A parent deck item with a simple mating plane with a child deck item on top of it (ex, the temperature module or the 96ch tip rack adapter).

In addition to the explanation provided in the proposal, it's helpful to view the impact that these new locating features have on our existing labware offset system. To make these snapshots as useful as possible, a couple development shims are added, such as the one in 37728dc. There are two snapshots in the commit history:

• cc74592 This is the final baseline snapshot before starting the locating feature implementation in earnest. The diff of this snapshot against edge isn't particularly useful, but just shows that we throw a few new errors now.
• 7db8cfb diff this snapshot against the one in the previously mentioned commit. You'll notice that the Aluminum Flat Bottom Plate is now a valid snapshot while it was not in the previous snapshot. That's intentional, and we'll re-gate the labware that may reside on top of it with a more directed locating feature (see proposal).

The only semi-unexpected side-effect of these changes are in 94d85cf, in which we update protocol validation, since v3 won't need stacking offsets. We will gate labware mating via locating features.

e54f045 is more of a fix than a feat, but pretty self explanatory when viewing the commit. This one slipped through the last PR since there was nothing making use of the definitions in the last PR.

Test Plan and Hands on Testing

• Covered by snapshot testing, see above. All the changes are reasonable.

Changelog

• Added slotFootprintAsChild and slotFootprintAsParent locating features to labware v3.

Review requests

• Are we ok with the python? This is the last major architectural PR for the API (let us hope), so locking down the structure now is worthwhile.

Risk assessment

none in the sense the migration hasn't happened yet
low in the sense that we are covered by snapshot testing

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 24.57%. Comparing base (e478e41) to head (56490f4).
Report is 693 commits behind head on edge.

Additional details and impacted files

@@             Coverage Diff             @@
##             edge   #18769       +/-   ##
===========================================
- Coverage   54.65%   24.57%   -30.08%     
===========================================
  Files        3258     3331       +73     
  Lines      281774   290103     +8329     
  Branches    29494    36110     +6616     
===========================================
- Hits       153999    71302    -82697     
- Misses     127585   218780    +91195     
+ Partials      190       21      -169     

Flag	Coverage Δ
protocol-designer	19.03% <ø> (+0.32%)	⬆️
step-generation	5.32% <ø> (+0.99%)	⬆️

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

Files with missing lines	Coverage Δ
...data/python/opentrons_shared_data/labware/types.py	100.00% <100.00%> (ø)

... and 2372 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sfoster1]

what does slotFootPrintAsChild.springDirectionalForce mean? like, "this labware is compatible with a spring parent", where it's true for almost everything? everything?

[mjhuff]

The labware could be placed on any parent with a slotFootprintAsParent, and the child's spring determines the child's positioning on the parent. This currently applies to the temp mod calibration plate. If there is a unique or novel interaction, the way we would handle that theoretical scenario is with a new locating feature.

There's a description of this behavior provided in this PR here: shared-data/labware/schemas/3.json, but happy to update it if you feel it's insufficient. When we get around to the documentation, we'll ensure this is thoroughly explained.

[mjhuff]

Ok, turns out that snapshots were indicating that a lot of stackups involving center-to-center mating were in fact moving the well to effectively "D2" instead of "D3" as should happen, and I missed that. The calculation was a bit off, and updating the deck and module definitions to shift the frontRight / backLeft made that a bit more obvious. I've removed some of the shims I put in earlier for snapshots, because it turns out those actually aren't useful.

Diffing the snapshot in be7b329 compared to 7db8cfb highlights the changes and makes things look reasonable. The thermocycler cases may be off, but it's hard to tell without an in-office repro, and also, the "asParent" feature won't exist for the TC in a bit, too.

The integration tests are now timing out on CI. I'm fixing the root issue soon, so I think it's fine to remove the auto-CI run for now. No one else should be touching the files that impact these tests, anyway.

[SyntaxColoring]

Looks great, thanks! Changes requested for some numbers in the module definitions. Various other things don't need action in this PR.

[SyntaxColoring]

@mjhuff I believe what your code does now, and what your intent is for now, is to interpret a module definition's labwareOffset and slotFootprintAsParent as combining, right?

So, as a contrived example, to find the back-right corner of the slot atop a module:

1. Start with the front-left corner of the underlying deck slot or addressable area beneath the module. (They should be the same thing.)
2. Consulting the module definition's slotTransforms, apply transforms specific to the deck type and slot. This is the thing that moves the bottom of a Flex module "underground."
3. Add the module definition's labwareOffset. On a Flex, this moves us back up to deck level.
4. Add the module definition's slotFootprintAsChild.backLeft.y and slotFootprintAsChild.frontRight.x. These take us from the slot origin to the back-right corner.

If that's correct, then I think these numbers are wrong. They would be correct if labwareOffset were (0, 0, 0), but it's (-0.125, 1.125, 68.275), so it's offsetting the whole slotFootprintAsChild to the wrong place.

I don't know where the existing labwareOffset of (-0.125, 1.125, 67.275) comes from. @vegano1 do you know? Could it have been copy-pasted from heaterShakerModuleV1.json?

[mjhuff]

The labwareOffset is almost vestigial at this point and applies to the OT-2 only despite being included for all the Flex modules. The "asParent" numbers often overlap with the bounding box, but not always (see other comment). Happy to chat about this, too.

[vegano1]

@SyntaxColoring @mjhuff

If what you're describing is correct, then yeah, I agree. The labwareOffset is incorrect and likely an error; it should be 0, especially for the Flex Stacker, which is not compatible with the OT-2.

[SyntaxColoring]

Thanks @vegano1.

@mjhuff re your Slack message, agreed with coming back to this. Let's either ticket it or put up a draft so it doesn't slip through the cracks.

[mjhuff]

Diffing the snapshot in 1aed6ae against 3b49e8a shows no changes, which is what we'd hope to see.

The only known wrong values in the snapshot are the z coordinates for the TC and mag block labware stackups. The stacking offsets associated with them will be incorporated when they get their own respective locating features.

[SyntaxColoring]

LGTM once linting passes. Thank you, this is a huge step!

[SyntaxColoring]

Might be worth leaving a comment on _module_slot_footprint_as_parent and _aa_slot_footprint_as_parent describing that they're normalization shims, in place until we delete labwareOffset+labwareInterfaceXDimension+labwareInterfaceYDimension (in module defs) and boundingBox (in deck defs) and replace them with the same slotFootprintAsParent shape that exists in labware definitions.

[SyntaxColoring]

Thanks @vegano1.

@mjhuff re your Slack message, agreed with coming back to this. Let's either ticket it or put up a draft so it doesn't slip through the cracks.

[mjhuff]

Sее EXEC-1648 for the flex stacker module def update.