stack

Combine multiple pools into one by stacking their state spaces as a disjoint union — each state in the resulting pool comes from exactly one of the input pools, enumerated in order.

import poolparty as pp
pp.init()

Parameters

Parameter	Type	Default	Description
`pools`	`list[Pool]`	(required)	List of pools to stack. States are concatenated in order.
`prefix`	`str \| None`	`None`	Prefix for the operation node name in the pool graph.
`iter_order`	`float \| None`	`None`	Iteration priority for downstream multi-pool iteration.
`cards`	`dict \| list \| None`	`None`	Design card columns to include in library output. Available card key: `"active_parent"` (index of which input pool produced each state).

Note

Only the most commonly used parameters are shown above. For the full parameter list, see stack() in the API Reference.

Examples

Stack Three Fixed-Sequence Pools

Merge three single-sequence pools into one pool that contains all three sequences.

a = pp.from_seq("AAAA")
b = pp.from_seq("CCCC")
c = pp.from_seq("GGGG")
combined = pp.stack([a, b, c])
combined.print_library()

combined: seq_length=4, num_states=3 AAAA
CCCC
GGGG

Stack Pools of Different Sizes

Stack a four-sequence pool and a two-sequence pool to produce a single pool with six states total.

pool_a = pp.from_seqs(["AAAA", "CCCC", "GGGG", "TTTT"], mode="sequential")
pool_b = pp.from_seqs(["ACGT", "TGCA"], mode="sequential")
combined = pp.stack([pool_a, pool_b])
combined.print_library()

combined: seq_length=4, num_states=6 AAAA
CCCC
GGGG
TTTT
ACGT
TGCA

Stack the Results of Two Scan Operations

Combine deletion scans over two different sequences into one pooled library covering both targets.

wt_a  = pp.from_seq("AAAACCCC")
wt_b  = pp.from_seq("GGGGTTTT")
dels_a = wt_a.deletion_scan(deletion_length=2, mode="sequential")
dels_b = wt_b.deletion_scan(deletion_length=2, mode="sequential")
merged = pp.stack([dels_a, dels_b])
merged.print_library()

merged: seq_length=8, num_states=14 --AACCCC
A--ACCCC
AA--CCCC
AAA--CCC
AAAA--CC
... (14 total)

Stack combined state space

After stacking, the combined pool enumerates every state from the first input, then every state from the second, and so on.

pool_a = pp.from_seqs(["AAAA", "CCCC"], mode="sequential")
pool_b = pp.from_seqs(["GGGG", "TTTT"], mode="sequential")
combined = pp.stack([pool_a, pool_b])
combined.print_library()

combined: seq_length=4, num_states=4 AAAA
CCCC
GGGG
TTTT

Operator shorthand (`+`)

pool_a + pool_b is equivalent to pp.stack([pool_a, pool_b]) — it creates a disjoint union of both pools’ states so draws can come from either pool. Chaining + appends additional pools.

wt   = pp.from_seq("ATCG")
muts = pp.mutagenize(wt, num_mutations=1, mode="sequential")
ctrl = pp.from_seqs(["AAAA", "TTTT"], mode="sequential")
lib  = muts + ctrl   # all single-point mutants + 2 controls
lib.print_library()

lib: seq_length=4, num_states=14 CTCG
GTCG
TTCG
AACG
ACCG ... (14 total)

a = pp.from_seqs(["AAAA", "CCCC"], mode="sequential")
b = pp.from_seqs(["GGGG"], mode="sequential")
c = pp.from_seqs(["TTTT", "ACGT"], mode="sequential")
lib = a + b + c
lib.print_library()

lib: seq_length=4, num_states=5 AAAA
CCCC
GGGG
TTTT
ACGT

See stack().