Defining a New Instrument

sliding_window_mask(h::Head,l::Labware,direction::Symbol; v_spacing=1,h_spacing=1,v_out=false,h_out=false)

Build the (predicate,positions) pair for the sliding-window mask archetype – the head's channel grid (spaced v_spacing/h_spacing well-units apart, optionally overhanging the labware edge via v_out/h_out) slides across the labware's well grid. Covers every Mask branch except the undifferentiated-well case (see blanket_mask); a single-channel head reduces to a plain point match automatically (the spacing term vanishes when H[d]=1), so there is no separate case to hand-write.

Per dimension, if effective_head_size collapsed (the head is wider/taller than the labware in that dimension – only for a pairing already declared safe by the calling Mask branch's kind list), the channel term is dropped from the predicate: any channel is valid, matching the position-count that already clamped for the same reason.

blanket_mask(h::Head,l::Labware,direction::Symbol)

Build the (predicate,positions) pair for the blanket mask archetype: any in-bounds (well,position,channel) combination is valid, with no further geometric discrimination – for a single, undifferentiated well (e.g. a deep reservoir) that multiple channels/positions may validly touch at once.

effective_head_size(h::Head,l::Labware,direction::Symbol)

The effective channel-grid size to use when computing positions/masks for h/l in direction. Defaults to the raw head size (no collapsing). Some instruments (e.g. EightChannel/PlateMaster) are sometimes paired with a labware kind whose grid is smaller than the head's channel count in some dimension – only ever for a (head,labware kind) pairing already declared safe by the calling Mask branch's own kind list – and override this to clamp the effective size down to the labware's own extent in that dimension. compute_positions and sliding_window_mask both consult this single function, so the position-count and the mask predicate can never drift out of sync with each other.

write_instrument_files(directory, design, source, target, config::Configuration{Nimbus}, slotting=slotting_greedy(...);
                        batch_ordering::Symbol=:greedy, volume_precision::Int=1, insert_blowouts::Bool=true,
                        waste_target=nimbus_waste_target, dead_volume_buffer::Real=20.0, aspirate_buffer::Real=0.01,
                        polish_clustering::Bool=false, polish_max_iterations::Int=1000, kwargs...)

Compile a design into a Nimbus protocol CSV written to directory. Unlike the generic compiler fallback, the Nimbus supports one-to-many aspirate/dispense: for each source well, as many destination dispenses as fit within the channel's capacity are drawn up in a single aspirate and dispensed together, rather than aspirating once per destination (see batch_design for the full batching/rounding/blowout pipeline). batch_ordering selects how dispenses within a batch are sequenced – :greedy (default, nearest-neighbor) or :exact (optimal, brute-force – only tractable for small batches, see order_exact) – and can be benchmarked against each other by calling pourfecto/compile with either value.

The written CSV uses a unified action-row schema: "Labware ID","Labware Position ID", "Volume (uL)","Action","Change Tip Before", Action being "Aspirate", "Dispense", or "Blowout". An aspirate row is always immediately followed by the rows it feeds (its dispenses, and a trailing blowout when insert_blowouts=true and a re-aspirate follows under the same tip), whose volumes sum to aspirate - aspirate_buffer exactly at volume_precision decimal places (see round_with_exact_sum) – the aspirate carries aspirate_buffer extra, a small unconditional physical safety margin (default 0.01 µL) against real-world pipetting inaccuracy on the last action in a cycle; see batch_design for the full precision/headroom reasoning. "Change Tip Before" is 1 on an aspirate row when the tip should be changed before that aspirate: always on a source change, and periodically thereafter per the instrument's "max_tip_use" setting (see tip_change_flags) – note "max_tip_use" counts aspirate batches, not individual dispense shots. It's always 0 on Dispense/Blowout rows.

insert_blowouts, waste_target, and dead_volume_buffer control the dead-volume Blowout path – see batch_design. insert_blowouts defaults to true, with dead_volume_buffer defaulting to 20.0 µL – compiling with none of these three kwargs supplied still inserts Blowout rows wherever a re-aspirate happens under the same tip. waste_target defaults to the permanently-reserved waste conical (nimbus_waste_target) automatically excluded from ordinary source/target slotting (see slotting_greedy's Configuration{Nimbus} override), so it doesn't need to be supplied explicitly either. Pass insert_blowouts=false to disable the path entirely.

polish_clustering (and polish_max_iterations) enable an exchange/local-search pass over cluster_batches's output to further reduce head-travel distance – see polish_batches and batch_design. Opt-in; default false preserves current behavior exactly.

Compiling function for Mantis

write_instrument_files(directory, design, source, target, config::Configuration{NimbusFourChannel},
                        slotting=slotting_greedy(...); n_channels, volume_precision,
                        insert_blowouts, waste_target, dead_volume_buffer, aspirate_buffer,
                        priming, priming_volume, priming_target, kwargs...)

Compile a design into a 4-channel Nimbus protocol CSV written to directory. See batch_design_four_channel for the full sweep/order/assembly pipeline (and for what each named keyword controls). This is a standalone compile entry point, independent of single-channel Nimbus's write_instrument_files (see this file's header comment).

Named keywords are forwarded to batch_design_four_channel; any other keyword (kwargs...) is accepted and silently dropped, not forwarded further – mirroring single-channel Nimbus's own write_instrument_files. This matters because pourfecto(directory,...)'s single-call form forwards the same keyword set to both the solve (e.g. optimizer=SCIP.Optimizer) and the compile stage (compile(directory,pourcast;kwargs...), Pourfecto/src/compiler/compile.jl:69) – without a catch-all here, a solve-only keyword like optimizer would otherwise reach batch_design_four_channel (which has no catch-all of its own) and error.

packing_greedy(pairings::Vector{Tuple{Labware,Labware}}, config::Configuration; kwargs...) -> Vector{SlottingDict}

Produce one or more SlottingDict layouts covering every (source,target) pairing that must be co-slotted, by repeatedly calling slotting_greedy on the full remaining labware set and peeling off however many pairings that solution satisfies, until every pairing is covered. Each returned SlottingDict becomes one compiled protocol (see compile).

This is the default packing_method for compile and the extension point instruments should override only when they have unusual slotting constraints – e.g. Cobra overrides this to always produce one protocol per pairing (it only has two deck slots and deliberately wants a fresh protocol whenever the labware pairing changes), rather than greedily co-packing as many pairings as possible into each protocol the way this generic implementation does.

slotting_greedy(labware::Vector{<:Labware}, config::Configuration; pinned::SlottingDict=SlottingDict()) -> SlottingDict

Greedily assign each piece of labware to an open, admissible deck slot on config's deck. Labware sharing a name (e.g. the same physical plate used as both a source and a target) is slotted once and shares that slot. Errors if any labware can't be placed on config's deck at all (see can_place); labware that can be placed but for which no slot remains open is returned in the not_placed local (not currently surfaced – see packing_greedy, which calls this repeatedly to produce one or more slotting solutions covering everything).

pinned pre-seeds the result with fixed labware => (position,slot) assignments – e.g. a permanently-mounted fixture that always occupies the same physical deck slot – before the greedy loop runs; those slots are removed from consideration for every other piece of labware, and pinned labware is skipped by the ordinary placement loop. Empty by default, so existing callers see no behavior change. See Nimbus.jl's slotting_greedy(::Vector{<:Labware},::Configuration{Nimbus}) override for a worked example (a reserved waste-conical slot).

slotting_greedy(labware::Vector{<:Labware}, config::Configuration{Nimbus}) -> SlottingDict

Nimbus-specific override: pins nimbus_waste_conical to its fixed physical slot (TubeRack50ML_WellNames_0006, well A3, nearest the tip rack) before delegating everything else to the generic slotting_greedy. That slot is a permanent fixture on the real Nimbus deck – excluded from ordinary source/target slotting on every compile, independent of whether the protocol actually uses the Blowout path, exactly like Cobra's packing_greedy override reflects its own instrument-specific deck constraints.

slotting_greedy(labware::Vector{<:Labware}, config::Configuration{NimbusFourChannel}) -> SlottingDict

Pins nimbus_4ch_waste_conical to its fixed physical slot before delegating to the generic slotting_greedy, mirroring single-channel Nimbus's own override (reimplemented independently, per this module's design decisions).

register_instrument!(config::Configuration; name::AbstractString, override::Bool=false)

Register config in the global configurations registry under name, making it discoverable via configurations["name"] and usable by name in pourfecto.

Errors if name is already registered unless override=true (in which case the previous entry is replaced and a warning is emitted) – this guards against two independently-authored instrument packages accidentally colliding on the same name. config.kind's capability-bearing validation already happens inside the Configuration{I} outer constructor (see Configuration); this function only handles registry-level name bookkeeping, not re-validation.

Third-party instrument packages should call this once per Configuration they define, typically at module top-level (or from __init__() if settings need to be read from Preferences.jl/environment state at load time) right after using Pourfecto.

Examples

julia> abstract type ExInstrument <: InstrumentModel end

julia> piston = Piston{ContinuousActuator,SingleRepeater}((20u"µL",200u"µL"),(20u"µL",200u"µL"),1);

julia> head = Head{ExInstrument}([piston],[Channel(220u"µL")],trues(1,1));

julia> deck = [UnconstrainedPosition("Deck",true,true,"square")];

julia> register_instrument!(Configuration{ExInstrument}(head,deck); name="ex_instrument");

julia> haskey(configurations,"ex_instrument")
true

test_instrument_interface(config::Configuration; kwargs...) -> Bool

Convenience wrapper running all Tier-1 (no-solver) checks: test_mask_coverage and test_json_roundtrip. This is the recommended entry point for a quick, solver-free sanity check on a newly-registered Configuration – e.g. @test test_instrument_interface(my_config) in your own package's test suite. kwargs are forwarded to test_mask_coverage (e.g. kinds=...).

test_mask_coverage(config::Configuration; kinds=default_test_labware_kinds()) -> Bool

Brute-force-verify that Mask(head(config), labware) for every kind in kinds produces exactly the per-well visit counts implied by mask_rules_for(config). Requires no optimizer.

If mask_rules_for(config) === nothing (no MaskRule table defined), emits a warning and returns true without testing anything – your Mask method exists and is used for scheduling, but hasn't opted into MaskRule-based coverage verification. Define mask_rules_for(::Configuration{YourInstrument}) to enable this check.

Uses @test internally (so it reports through any enclosing @testset), and also returns a Bool so it can be checked directly (e.g. @test test_mask_coverage(config)).

test_json_roundtrip(config::Configuration) -> Bool

Verify that config survives a JSON serialize/deserialize round trip (json_to_config(config_to_json(config))), catching serialization bugs in a custom instrument's types before they surface at Pourcast-save time. Requires no optimizer.

Configuration has no == method (its settings::Dict field defaults to reference equality), so this checks structural equivalence field-by-field instead of a single ==: instrument type, kind, deck (names/labware-kinds/slots per position), head (piston/channel counts and aspirate/dispense masks), and settings keys.

test_pourcast_compilation(name::AbstractString, pourcast::Pourcast) -> Nothing

Solver-backed integration check: compiles pourcast to a temporary directory and asserts the expected output structure (pourcast.json, a directory per config type, at least one non-empty protocol subfolder per config with slotting requirements) – verifies your instrument's write_instrument_files method actually produces files, not just that its Mask/deck logic is internally consistent.

This function does not run a solver itself – pourcast must already be a solved Pourcast (i.e. you called pourfecto(...) yourself with a real optimizer beforehand, e.g. pourfecto(...; optimizer=SCIP.Optimizer) – SCIP is already a Pourfecto dependency, or any other JuMP-compatible MILP solver you have configured/licensed).

Runs inside its own @testset "$name" block, so wrap the call in your own enclosing @testset if you want it nested under a named group.