Scientific processes
Choose a process guide for practical setup and an executable example:
- Activity
- Condensation
- Numerical integration and process splitting
- Coagulation
- Wall loss
- Dilution
- Nucleation
Native scientific process calls
Section titled “Native scientific process calls”V0.3.0 connects the native Aerosol aggregate to explicit CPU scientific
strategies. The aggregate owns ParticleData, full-order GasData, and
EnvironmentData references; strategies own physical configuration and RNG.
The integration regression is
particula/integration_tests/native_scientific_processes_test.py. It builds
through the v0.3.0 public initializers/builders and forbids facade construction.
Representation and inventory
Section titled “Representation and inventory”| Representation | Population storage | Species inventory in kg | Volume |
|---|---|---|---|
discrete |
Bin number density, m^-3 | Sum of per-particle mass times bin density, times V | Exactly 1 m^3 |
continuous_pdf |
Radius PDF dn/dr, m^-4 | Radius trapezoidal integral of mass times PDF, times V | Exactly 1 m^3 |
particle_resolved |
Raw representative counts | Sum of per-particle mass times count | Positive physical V |
Per-particle species mass is kg. Resolved number density is count/V. Gas
concentration is kg/m^3 in complete gas order, including inert lanes. CPU
strategies require one box. The five dynamics runnables handle multiple boxes
through the shared RunnableABC driver; strategy methods keep their existing
single-box inputs and outputs.
Explicit calls and configuration
Section titled “Explicit calls and configuration”Pass aerosol.particles, aerosol.gas, and scalar values from
aerosol.environment to the configured strategy:
import particula as parfrom docs.examples.fundamentals.native_state_access import build_aerosol, build_condensation
# Run from the repository root; the fixture includes ordered inert gas.aerosol = build_aerosol()condensation = build_condensation(aerosol.gas).condensation_strategycoagulation = par.dynamics.BrownianCoagulationStrategy("particle_resolved")wall_loss = par.dynamics.SphericalWallLossStrategy( wall_eddy_diffusivity=1e-3, chamber_radius=0.5, distribution_type="particle_resolved",)time_step = 1.0initial_particle_mass = aerosol.particles.species_mass_inventory.copy()initial_gas = aerosol.gas.concentration.copy()temperature = float(aerosol.environment.temperature[0])pressure = float(aerosol.environment.pressure[0])
condensation.step( aerosol.particles, aerosol.gas, temperature, pressure, time_step)coagulation.step(aerosol.particles, temperature, pressure, time_step)wall_loss.step(aerosol.particles, temperature, pressure, time_step)These names denote configured process objects, not aggregate methods or a new orchestration API. Each call preserves its supplied container and primary array identities. Preflight validates current mutable state before publication; CPU stochastic draws are not rolled back after consumption. Three successive calls are three separate transactions, not a whole-sequence rollback guarantee.
Condensation requires an explicit immutable process-owned map, for example
CondensationSpeciesMap(("inert", "B", "A"), ((2, 0), (1, 1))). The map binds
gas A to particle lane 0 and gas B to lane 1. Transport, vapor-pressure and
latent-heat parameters follow full gas order; activity/surface composition
follows full particle order. Skip indices refer to gas lanes. Partitioning
remains dynamic; unmapped, disabled and skipped lanes do not transfer.
See condensation contracts.
Native condensation supports PMF/PDF and arbitrary nonnegative resolved weights. Its finite-stage limiter accounts for actual representable mass changes, evaporation, available gas and PDF quadrature. Staggered modes retain their existing sequential current-gas coupling. Disabling gas updates models a fixed reservoir and does not establish closed-system conservation.
Complete evaporation retires a resolved particle by clearing its count and charge after gas/energy accounting. A remaining nonvolatile or unmapped core keeps the particle active. The resulting free slots are valid for subsequent coagulation and wall loss; gas-phase charge transport is not modeled.
Native coagulation supports the existing CPU mechanisms, including turbulent DNS and the charged strategy variants. Resolved merging requires equal positive active counts within a box; unequal weights reject before selection. Density steps preserve the existing number-density update while keeping per-bin species masses and charge fixed. Their intended use is uniform composition across radius or a single effective material with prescribed effective density, rather than tracking radius-dependent composition. Effective density alone does not provide per-species transport. When composition varies with size, individual species and weighted charge need not be conserved, even if total-mass error converges under grid refinement. This accepted limitation is characterized by independent tests; conservative species transport is deferred. See coagulation contracts.
Choose particle_resolved to track species composition that varies with radius
or more complex interactions involving individual particles’ composition,
size, and charge. Resolved particles retain their own species masses as they
evolve and merge. Use the supported process models and their constraints
described here; resolved coagulation requires equal positive active counts.
Native CPU wall loss retains forward Euler for PMF/PDF and Bernoulli whole- representative removal for resolved counts, including unequal weights. Account for removed inventory as an explicit sink. V0.3.0 native CPU resolved removal clears charge together with mass/count, so removed slots satisfy the activation free-slot contract. Surviving and untouched inactive storage is preserved. This amends v0.3.0 charge retention without changing the CPU removal law. GPU removal also clears charge. See wall-loss contracts.
Direct/prepared Warp boundary
Section titled “Direct/prepared Warp boundary”Transfers are explicit and preserve raw values and supported representation tags. Direct condensation supports discrete density and resolved counts with an explicit species binding; direct coagulation and wall loss support resolved counts. Tagged PDF execution rejects. Coagulation retains its eleven supported mechanism masks and equal-count restriction; no GPU DNS or unsupported mask support follows from metadata.
Configuration and ownership checks happen during preparation. Frozen prepared
calls retain references and scalar semantics; callers must keep their payloads
valid and re-prepare after layout, mapping or semantic changes. Enqueue does
not revalidate, upload, allocate, read back, synchronize or rebind. Wall-loss
prepared calls also retain the explicit kernel reset flag: persistent replay
requires initialized caller-owned RNG and initialize_rng=False.
Integration and migration boundary
Section titled “Integration and migration boundary”The native integration suite verifies condensation deltas separately in particles and mapped gas, actual resolved coagulation conservation at V=.25/1/4, the retained fixed-composition density update and its characterized limitation, and wall-loss sinks. It keeps gas and environment protected across particle-only processes. The owning unit suites provide the wider mechanism, control, rejection and stochastic matrices.
Native runnable composition, execution adapters, dilution/nucleation and resident/checkpoint integration are available under their bounded contracts. See the source, communication and resident sections below, the migration guide, and the complete direct sequence. Temporary facades and untagged compatibility dispatch remain until v0.3.0; these examples do not authorize deletion, a release, or GPU performance claims.
Native source integration (v0.3.0)
Section titled “Native source integration (v0.3.0)”Nucleation(source_config, commit_config) reads the currently held native
Aerosol.gas and Aerosol.environment on each equal substep. Its source config
requires an explicit NucleationSpeciesMap from
particula.dynamics.nucleation.species_mapping: full expected gas names and
unique (gas_index, particle_index) pairs. Gas and particle species widths may
be different. Positive injection composition entries must map to a particle
lane and have partitioning enabled; unmapped gas and particle-only species are
preserved. Native CPU source commits require one resolved box.
Potential rates and immutable finalization records retain number-density units.
At commit, admitted event density is multiplied by current physical volume.
maximum_slot_weight limits represented counts per newly activated slot.
Native final diagnostics expose event_count_units="count"; gas transfer and
mapped conservation residuals remain mass densities. Representative-volume
scaling reduces existing counts and provisional source counts with volume;
it preserves pre-existing particle density and gas concentration. Physical
volume evolution is a separate operation. Resampling retains count-weighted
species mass and charge under its existing bounded moment checks.
Each source attempt stages before writing, retains array identities, and
restores attempted particle/gas writes if a CPU writer fails. Earlier committed
substeps remain applied when a later attempt fails. The small
docs/examples/processes/nucleation/cpu_nucleation.py example exercises this native API
at non-unit volume with inert gas in the unified container. The former
LegacyNucleation compatibility runnable has been removed. Construct
Nucleation(source_config, commit_config) and keep environmental state on
the native aerosol; no constructor-time environment copy or facade cache
synchronization is required.
The direct GPU nucleation_step_gpu requires a separately prepared
NucleationSpeciesBinding for tagged resolved storage. Create it with
prepare_nucleation_species_map from
particula.gpu.nucleation_species_mapping, supplying retained full gas names
and the explicit source map. Preparation uploads only lane configuration and
pins exact carrier arrays; replacing storage or metadata requires preparation
again. Full-gas numerical validation outputs use gas width; resampling scratch uses particle width.
GPU source rates/final demand are densities. The existing direct algorithm requires admitted density times volume to be an integral int32 event count and activates one unit-count slot per event. It does not adopt the CPU weighted-slot packing algorithm. Native representative scaling acts on count demand and volume once, preserves gas concentration, and restores density units before final gas removal. Prepared repeated enqueue performs no allocation, transfer, readback or synchronization; device validation gates invalid live state before primary writers, with explicit observation afterward. Standalone GPU resampling and representative scaling likewise admit only resolved native storage, retaining count-weighted moments or count/volume density respectively.
Native direct communication and physical volume
Section titled “Native direct communication and physical volume”The concrete GPU communication primitives accept tagged resolved counts. Particle transport moves the same represented count out of the source and into its destination, including unequal-volume boxes. Fixed-capacity planning retains its exact population matching, ascending free-slot allocation and gated commit. Count-weighted species mass and signed charge are conserved. PMF/PDF particle transport is unsupported.
volume_evolution_step_gpu prescribes physical volume: native particle counts,
per-particle masses and charge remain unchanged, while every gas density scales
by the old/new volume ratio. This differs from representative-volume exhaustion,
which scales native counts and volume together while preserving gas density.
Invalid volumes or unrepresentable count densities gate primary writes. Callers
retain device placement, transfers and synchronization; prepared enqueue uses
pinned storage without allocation or host readback.
Resident native metadata and diagnostics
Section titled “Resident native metadata and diagnostics”Resident setup accepts tagged PMF and resolved populations and preserves their raw storage. It pins the population type, complete gas names, and separate particle-material and gas widths. Registry validation and capture signatures reject changed semantics or bindings; dispatch does not infer or rebind maps. Condensation and nucleation requests require their explicit uploaded mappings. Gas updates, thermodynamics and gas-shaped scratch use the full gas width.
Native number diagnostics report number density (resolved counts divided by
physical volume). Total-species-mass diagnostics require an explicit
CondensationSpeciesMap in ResidentDiagnosticRegistration.species_map with
the session’s gas order and every particle material mapped. Outputs are
extensive kg in gas order: gas concentration times volume plus mapped particle
inventory. Unmapped particle-only material is supported by process calls, but
this bounded gas-order total-mass diagnostic rejects it rather than dropping
its inventory. Two-snapshot diagnostics do not require a mass map.
Batched CPU runnable execution
Section titled “Batched CPU runnable execution”MassCondensation, Coagulation, WallLoss, Dilution, and Nucleation
use the shared RunnableABC box loop. Each process substep stages independent
state, invokes its single-box strategy for every box, and publishes into the
original arrays only after every box succeeds. Earlier completed substeps and
processes remain committed if a later one fails. Concurrent mutation is not
supported. A RunnableSequence orders work as substep, process, then boxes.
One ParticleData.distribution_type applies to the entire batch. Discrete/PMF
and continuous-PDF boxes retain exactly 1 m³ reference volume; resolved boxes
can have different positive physical volumes. Strategies with a declared kind
must match it. Nucleation accepts resolved populations only. No implicit type
conversion, cross-box transport, or per-box physics configuration is added.
Material densities, gas names, species maps, and process configuration are
shared; gas inventories, temperature, pressure, and resolved volumes are per box.
Runnable rates preserve the box axis even when B=1:
| Runnable | Rate shape |
|---|---|
| Mass condensation | (B, N, Sp) |
| Coagulation (PMF/PDF), wall loss, dilution | (B, N) |
| Nucleation | (B,) |
Direct strategy rates and kernels keep their single-box shapes. Resolved
coagulation still has no continuous number-rate API. Existing PMF/PDF
coagulation composition limitations are unchanged. Latent condensation exposes
MassCondensation.last_latent_heat_energy in J as (B,) for the most recent
successful substep. The strategy scalar remains available for single-box use;
its value is None after multi-box runnable execution to avoid reporting only
the last box.
Stochastic multi-box calls require CPUExecutionContext(root_seed, box_ids)
from particula.execution. Pass it with execute(..., context=context);
sequences and CPU adapter execution-state records also accept the context.
Each process namespace and logical box ID has a persistent independent NumPy
stream. Reuse the context to continue; create a new one to reset. Reorder arrays
and use context.with_box_ids(new_order) together. Views share continuation;
new IDs initialize lazily, and temporarily absent IDs retain their state.
Failed and zero-duration substeps do not advance caller-owned streams.
Single-box calls without a context retain existing strategy seed configuration.
There is no implied equivalence to resident GPU RNG or checkpoint state.
Custom Python processes
Section titled “Custom Python processes”Use BoxProcess for a reusable class or FunctionProcess for a Python
function. Both compose with native processes through |. Declare the arrays
that the process reads and writes. Implement validate(aerosol) for required
species, representation and parameter checks, and
advance(aerosol, *, time, time_step, context) for one box. Both callbacks
return None.
from particula import FunctionProcess
def warm_box(aerosol, *, time, time_step, context): # Temperature is K, time and time_step are seconds. aerosol.environment.temperature[:] += 0.01 * time_step
warming = FunctionProcess( warm_box, name="experiment.warming", reads=("environment.temperature",), writes=("environment.temperature",),)warming.execute(aerosol, time_step=10.0, time=120.0)Callbacks receive normal native containers with their leading box axis kept. They may execute arbitrary Python or call another scientific library. Particula stages the entire batch and publishes declared values only after every box succeeds. Invalid values, undeclared writes, species changes, replaced arrays or containers, and changed shapes reject. Earlier completed processes and substeps remain committed. External side effects and hidden mutable callback state are outside this rollback boundary. The custom process owns scientific source, sink and conservation accounting.
time is the start of the complete call. Each substep advances it by
time_step / sub_steps; all processes in one cycle receive the same interval.
Supply the next start time on repeated calls. A zero duration validates but
does not invoke advancement. Legacy overrides keep their own semantics.
For stochastic callbacks, set stochastic=True, pass a CPUExecutionContext,
and use context.rng inside the callback. context.box_id identifies the
logical box. Random draws commit with successful numeric publication; failed
substeps consume no caller-owned stream state. Use distinct process instance
names within a sequence. Continuation state should live in managed state rather
than mutable closures.
Writable native destinations are particle masses, concentrations, charge and valid volume; gas concentrations; and environment temperature and pressure. Shared material/species metadata is read-only. The public interface does not make arbitrary Python functions GPU kernels; explicit GPU translation is a separate capability.
Explicit Python execution in a GPU sequence
Section titled “Explicit Python execution in a GPU sequence”Wrap a BoxProcess or FunctionProcess in CPUTransfer to select a host round
trip inside a prepared GPU sequence. The
custom CPU/CUDA process example
demonstrates explicit CUDA preparation, transfer execution and checkpoint/resume
on a GPU. The ordinary CPU examples on this page require no GPU.
Each transfer waits for preceding GPU work, downloads the full native and registered state, runs the CPU process with the current simulation time, and validates every box. Only declared writes return to the existing device arrays. A rejected callback publishes none of its candidate values; earlier GPU work remains, and the prepared simulation faults. Host RNG words are checkpointed independently of native GPU random streams. Sequences with transfers reject CUDA graph capture before recording. Unwrapped Python processes require an explicit registered GPU adapter to prepare.
A condensation process supplies thermodynamic refresh when a custom process changes gas concentrations or temperature. A sequence with saturation readers and such writers rejects preparation if it has no refresh provider, including when the reader precedes the writer and would see stale state on the next step. Declared custom saturation readers also refresh after preceding native updates. Combining these readers with native gas-changing dilution or nucleation requires a refresh provider, regardless of their order in the repeating sequence.
Declare immutable parameters, extension_id, and version on the CPU process
when configuration affects its behavior. These join its instance name, reads,
writes and representation support in checkpoint compatibility checks. Resume
requires a compatible caller-supplied process; checkpoints do not serialize
Python code, external library state or mutable callback closures.
Custom runnables that override execute or rate retain their own semantics.
To adopt the public batching contract, implement BoxProcess or wrap a function
with FunctionProcess; custom code owns additional external state.
Legacy custom dilution strategies retain their original delegation path and
cannot accept an execution context. Equilibria still uses auxiliary inputs
and result attachments; native inventory mapping is a separate migration gap.
See the Aerosol Tutorial for an executed two-box example with distinct volumes and stable box IDs.
Run the timed CPU chemistry example for a complete two-box SciPy process, a scheduled function callback, registered source accounting and analytical checks.
Explore this topic: Understand aerosol processes