1 Plan a batch

If everything you submit uses the same cartridge and the same chip, skip this chapter: put the oligos in the queue in any order and the machine will work through them.

It matters when a batch is mixed — some plain oligos, some with a fluorophore, some with a quencher. The machine will still run all of it without being told anything extra, but the order you submit in decides how much of the work is synthesis and how much is changing consumables.

1.1 What the machine adds for you

You never queue a cartridge change or a chip insertion. You queue oligos, and the machine works out what has to happen in between. You can see it doing so: every queued entry carries a processTypes array listing the steps it will actually perform.

Queue one oligo on a machine that has just been switched on and it plans six steps:

insertChip -> cartridgeInit -> cartridgeActivate -> initializeSystem -> insertChip -> synthesis

Queue a second oligo of the same kind behind it and it plans two:

insertChip -> synthesis

The difference is everything the first one had to set up and the second one inherits. The setup is not quick either: activating a cartridge alone takes about 20 minutes before any synthesis starts. This is the single most useful field in the queue: before starting anything, read processTypes and see what you have actually asked for.

1.2 Why grouping is worth the effort

Because a cartridge change is not free.

• A chip is single-use. Every oligo costs one, whatever you do.
• Changing a cartridge discards the one that is installed, with whatever is left in it.
• Changing the cartridge type while a cartridge is installed additionally inserts a Manual cleaning run before the new cartridge can be set up. That is a procedure in its own right — protective equipment, a syringe, acetonitrile — and somebody has to stand at the Kilobaser and do it. See Manual cleaning in Operation.

So the cost is not per oligo, it is per transition between kinds. Consider four oligos — two plain, two with a 6-FAM and BHQ-1 probe — submitted in the two obvious orders. These numbers come from the processTypes the machine planned for each:

Same four oligos, same Kilobaser, same result. Alternating them costs three manual cleanings, each of which needs a person; grouping them costs one.

The rule that falls out of this is simple: oligos that need the same cartridge and chip should be adjacent in the queue. Not sorted in any particular way, just contiguous.

1.3 Grouping a real assay

The example assay is six plain primers plus one dual-labeled probe:

Two groups, so one transition. Put the six primers first and the probe last, and the machine inserts exactly one cartridge change and one cleaning, at the boundary.

1.4 Check the sequences fit

A cartridge holds a fixed number of bases, and each of the four bases has its own allowance. Both limits apply, so a set of sequences skewed towards one base can run out before the total does.

The six primers above come to 162 bases, which does not fit a standard cartridge. You can run them on two standard cartridges, or on one XL. kb_queue_assay.py reports this before you queue anything:

Standard Cartridge + Standard chip  (2 / 2)
  6 oligos, 162 bases
  ! 162 bases needs 2 cartridges (Standard Cartridge holds 150)

Re-run it with --cartridge 2-XL and the warning goes away.

Note the difference in how long each stays usable. A fluorophore cartridge expires in half the time of a standard one, and the clock starts when it is activated, not when it is installed. If a batch is going to sit in the queue for a week, put the fluorophore work at the end for that reason too.

1.5 Which combinations exist

Not every cartridge works with every chip, and the valid pairs are a property of the device, not of this guide. Read them at runtime from ccSettings.operations in GET /api/init, where a pair exists exactly when it can be run:

operations = kb.init()["ccSettings"]["operations"]
sorted(operations["3"])      # -> ['1', '1000', '2', '3-BHQ1', '3-single-label']
sorted(operations["2"])      # -> ['1', '1000', '2', '2-nocap']

Two things worth reading off that. A 6-FAM cartridge also runs the plain 2 chip, so it can make unmodified oligos — useful if you are already on it. And a standard cartridge never runs 3-BHQ1, so a quencher oligo can never be made on one, whatever you ask for.

Validating locally is worth the few lines, because the device rejects an impossible combination with 2-11-20, whose message is "provided processType is invalid" — which sends you looking at the wrong field entirely.

1.6 Putting it together

kb_queue_assay.py does all of the above: it reads the compatibility matrix from the device, groups the file by cartridge and chip, puts fluorophore groups last, checks each group against the cartridge budget, and then queues each group with one call.

python3 kb_queue_assay.py --host kilobaser.lab.example.org --user apibot \
    --insecure --dry-run kb_lamp_primers.fasta

Run it with --dry-run first. It prints the plan and touches nothing.

1.7 If you would rather not

Nothing here is mandatory. Submitting a mixed batch in arbitrary order produces the same oligos; it just spends more consumables and asks more of whoever is at the Kilobaser. If your users select a handful of oligos at a time and somebody is standing there anyway, queue them in whatever order they arrive and move on. Group when batches get large enough that the consumable cost is worth a few lines of code.