shuffle_states

Randomly permute the order of a pool’s state space, optionally with a fixed seed for deterministic shuffling, while leaving the sequences themselves unchanged.

import poolparty as pp
pp.init()

Parameters

Parameter	Type	Default	Description
`pool`	`Pool`	(required)	Input pool whose state order will be shuffled.
`seed`	`int \| None`	`None`	Random seed for deterministic shuffling. `None` uses a random seed.
`permutation`	`list[int] \| None`	`None`	Explicit permutation of state indices. Overrides `seed` when provided.
`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.

Note

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

Examples

Shuffle All 16 2-mer States with a Fixed Seed

Reorder the 16 2-mers produced by get_kmers using seed=0 so that the permutation is deterministic and reproducible.

import poolparty as pp
pp.init()
kmers    = pp.get_kmers(length=2, mode="sequential")
shuffled = pp.state_shuffle(kmers, seed=0)
shuffled.print_library()

shuffled: seq_length=2, num_states=16 GG
TG
CC
AC
GC ... (16 total)

Shuffle Then Slice to Get a Random Subset

Combine state_shuffle with state_slice to draw a reproducible random subset without replacement — equivalent to a seeded random sample.

import poolparty as pp
pp.init()
kmers   = pp.get_kmers(length=2, mode="sequential")
shuffled = pp.state_shuffle(kmers, seed=0)
subset  = pp.state_slice(shuffled, slice(0, 6))
subset.print_library()

subset: seq_length=2, num_states=6 GG
TG
CC
AC
GC
AG

Two Shuffles with Different Seeds Produce Different Orders

Changing the seed produces an independent permutation, demonstrating that the output order is fully determined by the seed value.

import poolparty as pp
pp.init()
kmers      = pp.get_kmers(length=2, mode="sequential")
shuffled_0 = pp.state_shuffle(kmers, seed=0)
shuffled_0.print_library()
shuffled_1 = pp.state_shuffle(kmers, seed=1)
shuffled_1.print_library()

shuffled_0: seq_length=2, num_states=16 GG
TG
CC
AC
GC ... (16 total)

shuffled_1: seq_length=2, num_states=16 AG
GG
AA
TG
CG ... (16 total)

See state_shuffle().