Skip to content

Scientific processes

Choose a process guide for practical setup and an executable example:

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 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.

Pass aerosol.particles, aerosol.gas, and scalar values from aerosol.environment to the configured strategy:

import particula as par
from 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_strategy
coagulation = 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.0
initial_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.

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.

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.

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 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.

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.

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