Module parallel 

Serial or Rayon-parallel evaluation of independent items. treams-rs extension.

Four forms decide when work runs on the Rayon pool:

• Parallel is the policy of the elementwise evaluations in broadcast: in parallel from a number of elements (Parallel::AtLeast), or in about four chunks per thread for cheap, uniform elements (Parallel::Chunked).
• try_map, try_fill_chunks and try_fold_ordered take parallel: bool, which callers compute from a size and PARALLEL_ITEMS or PARALLEL_ENTRIES, or set for items that are expensive on their own.
• LU factorizations and solves pass faer a worker count computed from the matrix size (linalg::lu_threads).
• The S-matrix illumination in smatrix::illuminate compares a row count with a constant and calls Rayon directly.

Parallel, try_map and try_fill_chunks keep every output in index order, and try_fold_ordered adds in an order set by the number of items, so the thread count never changes their results. The three try_* helpers guard serial work and parallel callbacks, including callbacks on foreign or fallback workers. Ordered reductions also guard the final combine on the caller.

Module	Threshold	Value	Runs in parallel
numerics::parallel	PARALLEL_ITEMS	1024 items	plane-wave permutations (pw::permute), chirality densities (smatrix::chirality)
numerics::parallel	PARALLEL_ENTRIES	4096 entries	plane-wave phases and fields, and their pullbacks (pw::field)
special::bessel	PARALLEL	AtLeast(64)	Bessel arrays and their pullbacks
special::legendre	PARALLEL	AtLeast(1024)	angular-function arrays and their pullbacks
special::wigner	PARALLEL	AtLeast(1024)	Wigner D arrays and their pullbacks
special::integrals	PARALLEL	AtLeast(1024)	incomplete gamma and Kambe arrays and their pullbacks
vectorwaves	PARALLEL	AtLeast(1024)	vector-wave arrays and their pullbacks
lattice::batch	PARALLEL	AtLeast(8)	batched lattice sums and their pullbacks, per output
sw::polar	PARALLEL	AtLeast(1024)	spherical translation arrays and their pullbacks
sw::polar	PLANS	AtLeast(64)	coupling plans, per distinct mode pair
cw::polar	literal	Chunked(512) regular, Chunked(64) singular	cylindrical translation arrays
cw::polar	literal	Chunked(64)	their pullback
cw::expansion	PARALLEL	AtLeast(64)	expansion coefficients, per distinct coupling
smatrix::illuminate	PARALLEL_SCAN_ROWS	256 rows	the finite check of illumination inputs
smatrix::illuminate	PARALLEL_SNAPSHOT_ROWS	128 rows	copies of the recorded blocks, with more than one thread
smatrix::illuminate	WORKER_SNAPSHOT_ROWS	512 rows	copies of the recorded blocks on the worker, with one thread
linalg	lu_threads	max(min(rows / 512, 4), rows / 2048) workers, at most columns / 16; the whole pool up to 4 threads	LU factorizations and solves (faer)

The ufunc loops of the bindings use their own tiers (parallel_from in the treams-py file ufunc/kinds.rs). Other Rayon calls fill matrix columns or map independent items at any size, also in index order.

Reductions

Pullbacks that add gradients over many items reduce with try_fold_ordered. It splits the items into at most REDUCTION_CHUNKS consecutive chunks, with boundaries set by the number of items alone, folds each chunk in index order and adds the chunk results in chunk order, on the pool or on the calling thread alike, so the thread count sets how many chunks run at once but never the order of the additions. A gradient that belongs to one item, such as the q gradient of one column, travels with that item as a mutable slot and is written in place; a partial sum holds only the gradients that all items share.

Module	Pullback	Items	Written in place
channels	SphericalChannelsResidual::pullback, CylindricalChannelsResidual::pullback	plane-mode columns	q gradients
cluster::iterative	IterativeSphereCluster::pair_gradients	particles i, each with its pairs (i, j)	-
cw::to_sw	ToSwResidual::pullback	cylindrical source modes	-
fields	WaveSet::pullback	samples	point gradients
pw::expand	ExpansionResidual::pullback	plane modes	wavevector gradients
pw::field	FieldResidual::pullback	at most 32 blocks of points or of modes, whichever axis is longer	the gradients of that axis
smatrix::layers	LayerStackResidual::pullback	transverse wavevectors	q gradients
sw::periodic_to_cw	PeriodicToCwResidual::pullback	spherical source modes	-
sw::plan	TranslationPlan::pullback_periodic	harmonics, whose gradients are collected and then added in order	-

Each item is expensive on its own (a column of entries, the pair blocks of a particle, a layer stack or a lattice sum), so these pullbacks pass parallel: true, except pw::field, which runs its blocks in parallel from PARALLEL_ENTRIES as its forward does. Its blocks are those of pw::PhasesResidual::pullback, which maps them with try_map and adds the partial gradients in block order.

Enums

Parallel 🔒

How an elementwise evaluation uses the rayon pool.

Constants

PARALLEL_ENTRIES 🔒

Matrix entries from which independent per-entry work runs in parallel.

PARALLEL_ITEMS 🔒

Items (modes, columns) from which independent per-item work runs in parallel.

REDUCTION_CHUNKS 🔒

Chunks of a deterministic reduction: try_fold_ordered splits its items into at most this many consecutive chunks, which bounds both the parallelism of a reduction and the partial results alive at once.

Functions

try_fill_chunks 🔒

Fill data chunk by chunk with fill(index, chunk), stopping at the first error.

try_fold_ordered 🔒

Fold items into one result whose bits do not depend on the thread count.

try_map 🔒

map over 0..count, collected in index order and stopping at the first error.