Material Mutation and Transfer

Material mutation uses the << operator to move or merge material into a destination.

target << [source:5uL];

The left side is the destination container. The source list on the right describes material sources and optional transfer quantities.

Use execution requirements for dropwise delivery or surface spreading. They constrain how the transfer is performed while preserving its declared amount.

Quantified Transfer

A quantified transfer pairs a source with an amount expressed in a volume, mass, or count unit. The amount can be a literal, a recipe calculation, or a calculation based on the source's current contents. For a recipe calculation:

let total_volume = 10mL;
let dilution = 1000;
let aliquot = total_volume / dilution;
target << [source:aliquot];

This requests 0.01mL, equivalent to 10uL. Writing target << [source:total_volume / dilution]; has the same quantity semantics. Compatible units are converted according to the quantity arithmetic rules. A unitless amount such as target << [source:1]; is invalid.

For an aliquot that depends on earlier additions, read the source's current contents volume at the transfer. Suppose source currently holds 110uL and buffer has at least 20uL available:

source << [buffer:20uL];
target << [source:source.contents.volume * 0.6];

The addition brings the source to 130uL. The next statement moves 78uL into the target and leaves 52uL in the source. Here 0.6 is the author's chosen fraction. A calculation saved with let before the addition would keep its earlier value, so place the calculation where its inputs should be read.

The requested quantity must also be available at runtime. Material with unknown mass can follow a volume aliquot when its carrier volume and distribution are known; its mass stays unknown and its tracked share is scaled. A mass-based request cannot use that unknown quantity and fails with MAT_QUANTITY_UNKNOWN.

Cell suspensions may be transferred by cellular count:

target << [source:25000cells];

cells remains an independent count axis. For a homogeneous suspension, runtime uses the recorded concentration to resolve the carrier volume that must physically move with the requested cells, then applies the ordinary volume transfer path. Count transfer is rejected for adherent cells, pellets, and other non-homogeneous material until an operation establishes a transferable suspension.

A count-only free cellular constructor uses the reference runtime's recorded default concentration to create an implicit carrier after all load items are known. Supplying an explicit medium volume avoids that assumption. Adherent cells retain their count without an implicit carrier.

Full Transfer

A source item can also be unquantified:

target << [source];

That expresses full-transfer or merge semantics for the source item.

Multiple Sources

Each entry in a source list independently specifies a full or quantified transfer. For example, a mixture can use fixed amounts from both sources:

target << [sample:80uL, buffer:20uL];

Or it can take all of the sample and a fixed amount of buffer:

target << [sample, buffer:20uL];

Items contribute to the same target in source-list order. The transfer commits only if every source item succeeds. This source list does not imply ordered mapping across a group.

Source-Local Separation

A transfer source can select one side of a binary separation without first binding a named sep(...) group:

waste << [sample.partition(magnetic_program(duration = 5min))[1]:120uL];

The selector is source-local. It partitions the source for this transfer, moves the selected slot into the target, and leaves the unselected material in the source container. It does not create an indexed group binding.

Use sep(...) instead when both slots need names or later reuse.

Ordered Mapping with series

For group targets, ordered mapping uses series(...).

group_ref << [series(stock, [5uL, 10uL, 20uL])];

The value list must match the target group size. series(...) is only a mutation source-list form; it is not a general-purpose list mapping expression.

Unit Collection

Culsma also allows collecting a unit back into a container:

keep_tube << [cell];

This is used with stream/unit workflows and belongs to more advanced authoring.

Same-Container No-Op

If a source item resolves to the same container as the target, the item is legal and is treated as a no-op at material execution.

What Transfer Is Not

<< no longer carries a source-level program argument. Actions such as vortexing, shaking, or stirring belong to agit(...), not to transfer syntax.