Sequential/stacking ('Stacking Access') storage abstraction backed by ResourceStack

[c-reiter]

Context

The storage user guide already defines two retrieval patterns — Stacking Access (Sequential) vs Random Access — and explicitly puts the Agilent BenchCel 4R, Labware MiniHub, and Lab Services PlateCarousel in the sequential column (docs/user_guide/01_material-handling/storage/storage.rst).

In code, though, that distinction doesn't exist yet: Incubator is the only storage frontend, and it is fundamentally random-access — it takes racks: List[PlateCarrier] of addressable PlateHolder sites and exposes find_random_site / find_smallest_site_for_plate / take_in_plate(site). Every backend (CytomatBackend, LiCONiC, Heraeus, and now BenchCel4RBackend) subclasses IncubatorBackend.

The mismatch (surfaced while adding the BenchCel, #1109)

A BenchCel stacker is a single-ended LIFO stack of nesting plates — the firmware only addresses whole stackers (downstack/upstack at one end); there is no slot addressing. To fit the Incubator model, #1109 currently fakes each stacker as a 20-site PlateCarrier where only the stacker identity is ever used and the sites are cosmetic. The frontend therefore advertises random-access operations (find_random_site, placing into an arbitrary site) that the hardware cannot honor.

Opportunity

ResourceStack(direction="z") already models exactly this: single-ended LIFO access (it only lets you unassign the top item), and — since #1110 (Plate.stacking_z_height) and #1112 — it nests plates by their stacking pitch, which is precisely a stacker's geometry. #1109 also now maps Plate.stacking_z_height → BenchCel StackingThickness.

Proposal / question for discussion

Would you be open to a sequential/stacking storage abstraction (e.g. a Stacker frontend, or a shared storage base) backed by ResourceStack, exposing downstack/upstack (LIFO) semantics instead of random-access site selection? It would model the documented "Stacking Access" category directly and would also fit the MiniHub / PlateCarousel.

Open design questions I'd love your steer on, @rickwierenga:

• A new parallel frontend (Stacker) vs. generalizing the existing storage frontend to support both access patterns.
• Whether to introduce a StorageBackend base above IncubatorBackend, or keep backends as-is.
• How loading/transfer should be modelled for sequential devices (the BenchCel has no fixed loading position — it uses teachpoints).

Happy to prototype whichever direction you prefer. Not blocking #1109 — that ships with the current Incubator-based model and a doc note describing this limitation.

Refs: #1109 (BenchCel), #1110 (Plate.stacking_z_height), #1112 (ResourceStack nesting).

[rickwierenga]

sounds interesting! would love to see a more detailed proposal on this

we recently got a high res microserve, which should be able to use the same capability (always nice to start a new frontend/capability with two machines!)

[c-reiter]

thanks @rickwierenga here's a detailed proposal:

Why the current base doesn't fit sequential devices

Two concrete problems, both visible in #1109:

1. IncubatorBackend is incubator-shaped. open_door, close_door, set_temperature, get_temperature, start_shaking, stop_shaking are all @abstractmethod, so the BenchCel implements all six as raise NotImplementedError. A MicroServe would too.
2. Incubator (frontend) is random-access. It holds racks: List[PlateCarrier] of addressable PlateHolder sites and exposes find_random_site / find_smallest_site_for_plate / take_in_plate(site) - semantics a LIFO (last-in-first-out) stacker cannot honour. Add Agilent BenchCel 4R storage backend #1109 fakes each stacker as a 20-site PlateCarrier where only the stacker identity is ever used.

Proposed shape

Split the storage base so access-pattern-specific behaviour lives in sibling frontends/backends over a thin shared base:

MachineBackend
└── StorageBackend          # NEW: resource model + transfer only; no door/temp/shake
    ├── IncubatorBackend    # existing: + door/temperature/shaking, random-access
    └── StackerBackend      # NEW: sequential downstack/upstack

Machine, Resource
├── Incubator               # existing, random-access  (racks: List[PlateCarrier])
└── Stacker                 # NEW, sequential          (stacks: List[ResourceStack])

Resource model

Each stack is a ResourceStack(direction="z"). That already (a) enforces LIFO - only the top item can be unassigned - and (b) computes true stack height by nesting plates via Plate.stacking_z_height (#1110 / #1112). No faked fixed-site grid, and the geometry is correct for free.

How the StackerBackend interface could look

class StackerBackend(StorageBackend, metaclass=ABCMeta):
    async def set_stacks(self, stacks: List[ResourceStack]): ...

    @abstractmethod
    async def downstack(self, stack: ResourceStack, **kw):       # accessible plate -> transfer pos
        ...
    @abstractmethod
    async def upstack(self, stack: ResourceStack, plate: Plate, **kw):  # transfer pos -> stack
        ...

The Stacker frontend owns the LIFO bookkeeping (push/pop the ResourceStack) and exposes ergonomic ops mirroring Incubator's style.

Mapping to the two machines

• BenchCel 4R - 4 stacks; downstack/upstack are the capture-confirmed serial commands 0x62/0x63; transfer position is a teachpoint on the left or right side of the machine (there's no fixed tray); stacking_z_height is already used for both nesting and the device StackingThickness (wired in Add Agilent BenchCel 4R storage backend #1109).
• HighRes MicroServe - second sequential device, drops into the same Stacker / StackerBackend with its own protocol backend at pylabrobot/storage/highres/microserve*.py I guess (mirroring the existing highres/microspin layout).

Migration

Incubator and all random-access devices are untouched. The BenchCel migrates from the faked-PlateCarrier model to Stacker - I could do that as a follow-up after #1109 is merged, to keep #1109 reviewable for you.

Decisions I'd like your call on

1. Should we do Two sibling frontends (Incubator + Stacker) or one Store parameterised by access pattern. I lean in the direction of two siblings, seems clearer, and matches the existing Incubator.
2. Introduce the shared StorageBackend and base the Incubator on that, or keep IncubatorBackend as-is and add StackerBackend independently?
3. Transfer modelling - should we expose a generic "transfer position" for all StorageBackends (BenchCel = teachpoint id, incubators = loading tray), or leave it device-specific?
4. Carousels (also "sequential" in the docs) -> should we fold them into Stacker or a later ring-buffer frontend? I'd rather defer that for now.

If you're happy with this, I'll prototype Stacker + StackerBackend against the BenchCel first, then you or someone else can wire the MicroServe.

[rickwierenga]

this would work well in V1, not "split front ends" but making it into capabilities. see https://discuss.pylabrobot.org/t/updating-plr-api-for-machine-interfaces-discussion/445

I like having a Stacker capability

yes, the transfer position would be a part of the stacker. Incubators call that the loading tray

[c-reiter]

Started building this now. opened #1119 with a first Stacker capability + StackerBackend (composable, no Incubator changes, transfer position owned by the stacker, LIFO/nesting via ResourceStack). Includes a chatterbox backend and tests. The remaining open questions (generic transfer-position abstraction; carousels) and the BenchCel migration are noted there as follow-ups - happy to adjust the shape based on your feedback.

[c-reiter]

Reworked the Stacker as a v1 Capability per your steer: #1142 (targets v1b1). It extracts a shared LoadingTrayRetrieval base (loading tray + plate-movement plumbing) that both AutomatedRetrieval and the new Stacker use — the code-sharing you suggested. The v0 attempt (#1119) is closed. Next I'll rework the BenchCel driver as a v1 device composing this capability.