Agitation

agit(...) mechanically handles material within an existing container or group of containers. Use << to transfer material between containers. It does not return a material or readout value.

Choose a Mode

Use an AgitationMode member to select the action. SHAKE accepts an optional ShakeMotion member to describe how the container moves.

Mode	Meaning	Parameters
VORTEX	Vortex mixing	Optional duration, rate in rpm
INVERT	Discrete inversion	Optional cycles
FLICK	Gentle tube flicking	Optional cycles
TAP	Tapping a container or a whole plate to mix its contents	No time, rate or count parameters
STIR	Stirring	Optional duration, rate in rpm
SHAKE	Container motion, with or without a specified trajectory	See the motion table below
CENTRIFUGE	Centrifugation without declared fractions	Required drive (g or rpm) and positive duration

agit(sample = sample, mode = AgitationMode.VORTEX, duration = 30s, rate = 2000rpm);
agit(sample = sample, mode = AgitationMode.INVERT, cycles = 10);

INVERT and FLICK do not accept duration or rate. VORTEX and STIR do not accept cycles. Only SHAKE accepts motion.

Use FLICK for a finger flick of a tube and TAP for tapping a container. For a procedure that calls for gently tapping a plate, pass the plate itself:

let reaction_plate = plate(label = "ReactionPlate", format = PlateFormat.WELL_96);
agit(sample = reaction_plate, mode = AgitationMode.TAP)
    with constraint(ConstraintRequirement.GENTLE);

This requests one action on the plate. Its allocated wells retain their own contents and quantities; liquid is not combined across wells. Passing a selected well group instead requests independent actions on those wells. A plate's identity is preserved through aliases and protocol parameters, independently of its label.

TAP accepts no duration, rate, cycles, motion or drive. If the procedure does not specify a tapping count or intensity, leave those details unspecified. Use GENTLE when gentle handling is required; choosing TAP does not supply that requirement automatically.

For a quick spin that keeps the same tube and does not request supernatant or pellet parts, use:

agit(sample = sample, mode = AgitationMode.CENTRIFUGE,
     drive = 3000g, duration = 5s);

CENTRIFUGE does not accept motion, rate, cycles, or a separation program. Its drive accepts g or rpm. It preserves container identity and material quantities; it does not create contents[0/1] or claim that beads stayed suspended. Drive and duration specify the requested action, not an observed outcome. Use sep(...) when the protocol intends to collect or route fractions.

Both enum types are closed. Corresponding lowercase tokens and strings, such as mode=shake, motion=rock, are accepted; a member of AgitationMode cannot be used where a ShakeMotion member is expected.

Shake Motions

Motion	Movement	Required extent	Optional rate
Omitted	Unspecified shaking trajectory	Neither time nor count is required; duration is allowed, cycles is not	rpm, retaining the existing generic SHAKE contract
ShakeMotion.LINEAR	Back-and-forth translation along a line	duration	Hz or cycle/min
ShakeMotion.ORBITAL	Circular orbital translation	duration	rpm
ShakeMotion.ROCK	Limited-angle tilting and return	Exactly one of duration or cycles	Hz or cycle/min
ShakeMotion.ROTATION	Continuous rotation, such as end-over-end tube rotation	duration	rpm

Omitting motion does not default to orbital shaking. Omitted speed and geometry remain unspecified; do not invent them when the source gives no value.

For orbital shaking:

agit(sample = sample, mode = AgitationMode.SHAKE,
     motion = ShakeMotion.ORBITAL, duration = 16h, rate = 200rpm);

For three complete rocking movements, where one cycle is an out-and-back tilt:

agit(sample = sample, mode = AgitationMode.SHAKE,
     motion = ShakeMotion.ROCK, cycles = 3)
    with constraint(ConstraintRequirement.GENTLE);

For time-based rocking:

agit(sample = sample, mode = AgitationMode.SHAKE,
     motion = ShakeMotion.ROCK, duration = 5min, rate = 20cycle/min);

Motion durations and rates must be finite and positive. Rocking counts must be positive unitless integers. A count may be combined with a rate, but not with a duration. Other explicit motions do not accept cycles. Frequency units describe complete back-and-forth cycles (1Hz = 60cycle/min); they are not interchangeable with rpm under these motion contracts.

GENTLE is a separate execution requirement. Choosing ROCK alone does not promise gentle handling or that adherent cells remain attached.

Continuous Rotation and Compatibility

For continuous rotation under a cold environment:

with env(thermal = 4C) {
    agit(sample = sample, mode = AgitationMode.SHAKE,
         motion = ShakeMotion.ROTATION, duration = 2h, rate = 20rpm);
}

The existing mode=AgitationMode.ROTATION form remains accepted with the same rotation semantics: required positive duration, optional positive rpm rate and no cycles. Do not add motion to that compatibility form; use SHAKE when specifying a motion explicitly. Existing source and stored plans remain valid.

Scope and Validation

sample can be a single container or a flat group; TAP also accepts a whole plate carrier. Each group member is handled independently, preserving material quantities and invalidating prior indexed separation of its contents. Mixing modes mark that organization mixed; CENTRIFUGE only invalidates the old indices. The action does not predict a mixing yield or prove a physical outcome.

Known invalid mode/motion/parameter combinations fail validation. Values supplied through protocol arguments or runtime expressions are checked before the action. Execution backends receive the selected motion and its parameters without substituting another movement.

agit.duration is the action's duration; env.duration describes the surrounding environment window and does not fill in a missing required action duration.

This motion contract does not add times, orbit_diameter, stroke_length, tilt_angle, SWIRL, or SURFACE_RINSE. Surface washing remains a procedure composed of the appropriate transfers, motions and material-handling steps.