GPU coagulation configuration and sidecar ownership
Native resolved coagulation combines Brownian motion, charged Brownian motion, differential sedimentation and turbulent shear in one candidate/acceptance stream. All 15 nonempty subsets are executable, including Brownian + sedimentation + shear. This development capability removes the former 256 and 16,384 active-slot limits. It does not change the supported population measure or collision physics.
from particula.gpu.kernels import coagulation_step_gpufrom particula.gpu.kernels.coagulation import ( CoagulationMechanismConfig, CoagulationWorkConfig, coagulation_preflight_gpu,)
mechanisms = CoagulationMechanismConfig( mechanisms=("brownian", "sedimentation_sp2016", "turbulent_shear_st1956"))work = CoagulationWorkConfig(max_trials_per_box=65536)inputs = dict( temperature=283.15, pressure=101325.0, mechanism_config=mechanisms, work_config=work, turbulent_dissipation=1e-4, fluid_density=1.2, max_collisions=particles.masses.shape[1] // 2,)report = coagulation_preflight_gpu(particles, time_step=0.1, **inputs)# Inspect report["admitted"] before calling the step at the same state.if report["admitted"].all(): particles, pairs, counts = coagulation_step_gpu( particles, time_step=0.1, **inputs )The configuration and preflight helpers are concrete-module APIs, not package
exports. The return tuple remains (particles, collision_pairs, n_collisions).
Supplied outputs are returned by identity. Temperature and pressure accept
scalars, supported floating Warp vectors (n_boxes,), or a same-device
WarpEnvironmentData with the direct arguments set to None. Physical box
volume belongs to ParticleData; an explicit volume must agree with it.
Physics and represented counts
Section titled “Physics and represented counts”| Identifier | Bit | Physical model |
|---|---|---|
brownian |
1 | Neutral Brownian coagulation |
charged_hard_sphere |
2 | Complete charged Brownian rate with selected fit |
sedimentation_sp2016 |
4 | Slip-corrected Stokes differential settling, efficiency 1 |
turbulent_shear_st1956 |
8 | Saffman–Turner turbulent shear |
charged_model accepts hard_sphere, dyachkov2007, gatti2008,
gopalakrishnan2012, or chahl2019. Nondefault fits require the charged
mechanism. These are complete Brownian rates: adding ordinary Brownian sums
both complete rates. Do not add a charged term merely to obtain an allowed
combination. Mechanisms normalize to the table’s order; duplicates and unknown
identifiers reject before particle access.
Only particle_resolved is supported. Positive concentration is represented
count, and must be equal within each physical box, including non-unit counts.
Unequal weights, discrete populations and continuous PDFs are unsupported.
No fallback, physical-box subdivision, resampling or weight change is implicit.
Species masses and signed charge are conserved with represented-count weighting.
Shear requires positive finite turbulent_dissipation [m²/s³] and
fluid_density [kg/m³], supplied as floating scalars or same-device fp64 vectors.
Settling uses π(r_i+r_j)²|v_i-v_j| [m³/s]. Direct settling uses each particle’s
effective material density; prepared strategies retain their native mean-density
convention. Compare CPU and GPU observables only under matching assumptions.
Resources and rejection
Section titled “Resources and rejection”Parallel tiles evaluate every active unordered pair and reduce the maximum of the summed rate. Property and active-index storage scale linearly with slot capacity; reduction scratch uses at most 4,096 lanes per box. Total pair work is still quadratic. Tile sizes are not scientific population limits. Device memory, signed slot indexing and representable allocation sizes remain real limits.
For active count A, equal represented count w, volume V [m³], majorant M
[m³/s] and timestep dt [s], expected trial demand is
lambda = M * A * (A - 1) / 2 * w * dt / V.
Admission requires ceil(lambda) to fit the trial budget, collision capacity
and available disjoint pairs. This deliberately conservative bound ensures the
whole scheduled pass fits even if every proposal is accepted.
CoagulationWorkConfig defaults to 65,536 trials per box and 256 MiB for collision
outputs. These are configurable resource budgets. A request exceeding the byte
budget raises an actionable allocation error instead of shrinking the buffer.
An overloaded step raises CoagulationBudgetError with the box, required and
available trials, and a budget-admissible timestep. Infinite demand rejects.
No collision demand is silently clipped, and no automatic subcycling is used.
A smaller admitted timestep still requires a separate convergence study.
Preflight returns active counts, unordered pair evaluations, expected/required trials, available trials, budget-admissible timesteps, admission flags and the bound workspace/collision bytes. It allocates temporary workspace and downloads compact diagnostics, but leaves caller particles, outputs and RNG unchanged. Its state-dependent result must be recomputed after the population changes.
Persistent execution
Section titled “Persistent execution”Supplied RNG streams advance across successful calls. initialize_rng=True
requests a reset only after admission succeeds. Invalid and over-budget calls
preserve caller particles, outputs and RNG, even when reset was requested.
Omitted RNG uses convenience call-local storage. Allocation, transfer and
synchronization boundaries remain explicit; compact preflight readback does not
copy the simulation to CPU for execution.
Pass coagulation_work_config=work to a runnable’s prepare() to freeze resource
budgets. Prepared combinations support unique subsets of the same mechanisms.
Scratch is allocated during preparation and reused during resident execution.
Per-step device admission blocks dependent writers on failure; observation
faults the owner. Earlier successful processes or steps are not rolled back.
Checkpoints retain budget configuration and sampler compatibility; incompatible
older sampler checkpoints reject rather than silently changing continuation.
The worked resource-admission example uses explicit Warp CPU and can be run on requested native CUDA. The validation record distinguishes historical qualification from new checks. Native CUDA capture and performance claims require actual CUDA evidence; Warp CPU is not a substitute.
Executed work
Section titled “Executed work”Pass a separate work_counts Warp int32 array of shape (n_boxes, 2) to
coagulation_step_gpu to observe scheduled and attempted candidate trials.
The returned n_collisions contains accepted, applied collisions. These are
last-step counts, distinct from preflight expectations. Admission rejection
preserves caller-owned counters, RNG and collision outputs. Counters do not
consume random draws. Download them only at an explicit observation boundary.
Explore this topic: Direct kernels