Native dynamics migration
CPU processes and boxes
Section titled “CPU processes and boxes”Native runnables consume the current Aerosol.particles, .gas and
.environment objects. They preserve those identities during in-place process
execution. Condensation, coagulation, wall loss, dilution, and nucleation
runnables process every box. Direct strategy methods remain single-box.
Runnable rates retain the box axis, including B=1: use rates[0] when
passing one box to existing plotting or single-box numerical utilities.
Run this excerpt from the selected native checkout. Its maintained constructors
are in docs/examples/fundamentals/native_state_access.py:
from docs.examples.fundamentals.native_state_access import build_aerosol, build_condensation
aerosol = build_aerosol()condensation = build_condensation(aerosol.gas)particles, gas, environment = aerosol.particles, aerosol.gas, aerosol.environmentassert condensation.execute(aerosol, time_step=4e8, sub_steps=4) is aerosolassert aerosol.particles is particles and aerosol.gas is gasassert aerosol.environment is environmentThe example explicitly maps water at gas lane 2 to particle material 0 and organic at gas lane 1 to material 1, retaining inert gas at lane 0. It supplies full gas-order molar masses and process-owned activity, surface and vapor-pressure strategies. Do not infer chemistry from equal array widths or discard inert gas. The runnable reads current environment and gas state during its substeps.
| Process | Native guidance |
|---|---|
MassCondensation |
Explicit expected full gas order and material mapping; finite inventories; process-owned thermodynamics |
Coagulation |
Match distribution_type; resolved native coagulation requires equal positive active counts; retained binned methods have composition limitations |
Dilution |
Exponential finite-step decay of particle populations and every gas lane; masses per particle remain unchanged |
WallLoss |
Match the population kind and geometry; resolved removal retires lost slots; gas is not a wall sink |
Nucleation |
Explicit source/commit configuration and mapping; uses held environment and current gas; fixed capacity and exhaustion rules apply |
See the condensation guide,
coagulation guide, and
nucleation guide. The binned coagulation
limitation is not a tolerance to relax: radius-varying composition can require a
resolved model. A composed first | second sequence executes each full cycle
with equal substep durations and reads the state left by preceding processes.
Direct array mutation is caller-owned. Process validation still applies on the next invocation. Aggregate replacement validates shape/representation before publication, but it does not rewrite a process’s expected gas order or physical configuration. Rebuild that configuration explicitly when its meaning changes. Validation rejection is distinct from rollback after a process writer runs; there is no blanket whole-sequence rollback guarantee.
Direct Warp steps
Section titled “Direct Warp steps”Import steps from particula.gpu.kernels. Conversion helpers remain under
particula.gpu; maps, scratch and resident configuration remain at their concrete
modules. See the maintained
direct quick start
and five-process sequence.
Explicitly convert native discrete/resolved data; radius PDFs cannot be uploaded. Raw resolved concentration stays counts. Condensation couples gas through counts/volume, and extensive energy weights transfers by counts. Keep full ordered gas names externally. Prepare a condensation or nucleation species binding against the exact transferred carriers, with explicit lane pairs and full expected gas order. Replacing storage invalidates that binding; normal dispatch does not silently recreate it.
condensation_step_gpu requires thermodynamics= and native species_binding=.
It returns the identical particle carrier and whole-call transfer accumulator;
gas mutates in place and optional energy is a caller-owned output, not a third
return. Four equal fixed substeps refresh derived vapor pressure and couple later
proposals to updated gas. This is the bounded direct method, not general CPU
strategy parity, adaptive stepping or a high-level runnable.
Temperature and pressure may be positive finite scalars or same-device (B,)
Warp arrays, including scalar/array hybrids. Alternatively supply
environment=WarpEnvironmentData and omit both direct inputs. Never mix these
forms. Synchronize explicitly before host observation/restoration. Validation
may synchronize flags internally; simulation-state transfers remain explicit.
Prepared runnable execution
Section titled “Prepared runnable execution”Call process.prepare(aerosol, device="cuda:0", time_step=...) for supported
processes or ordered sequences. The owner provides run, explicit forcing,
reduced diagnostics and detached snapshot() results. checkpoint() and
process.resume(checkpoint) retain exact random continuation; capture()
records without advancing physics. See capabilities and examples.
Existing direct calls remain explicit, and CPU execution semantics are unchanged.
Resident and capture paths
Section titled “Resident and capture paths”The resident multi-timestep example prepares exact session/registry/guard ownership and process mappings, then runs the maintained twelve-node composition. After explicit same-device restart it prepares new mappings against fresh carriers. Its prescribed gas and wall loss make it an open system: zero-ledger residuals report net inventory change, not zero closed-system drift.
Uncaptured examples use Warp CPU when installed. The native capture example requires CUDA and never substitutes CPU or Warp CPU. Optional CUDA absence is not performance evidence. See container foundations for transfers and resident checkpoints for canonical-byte continuation and lossy inspection boundaries.