Explicit atmospheric ion balance on CUDA
Explicit atmospheric ion balance on CUDA
Section titled “Explicit atmospheric ion balance on CUDA”When only a few ions occupy each physical box, is the continuum balance an adequate reference? You will compare a stochastic particle ensemble with both a finite-population master equation and a continuum equation, then account for supplied and exported mass. This is the prerequisite for interpreting the seed-survival experiment.
Before asking whether charging helps a rare seed survive, check the ion population itself. Here every ion is a unit-count particle of diameter 0.5 nm. Positive and negative ions carry +1 and −1 elementary charges and masses of 150 u and 90 u. Their different material densities give the same initial diameter without conflating mass with size.
We compare no production (decay) with 2 and 10 ion pairs cm⁻³ s⁻¹. A Poisson source creates pairs; opposite ions recombine with coefficient α = 1.7 × 10⁻¹² m³ s⁻¹. Neutral products retain both material masses until cleanup exports them. There are no aerosols, walls, vapor or bulk ion sinks. Thus this example tests source and recombination physics, not attachment.
Python · section 1
"""Validate explicit ion production, recombination and export on real CUDA."""
from time import perf_counter
import matplotlib.pyplot as pltimport numpy as npimport warp as wpfrom particula import Aerosolfrom particula.dynamics.ions.cleanup import IonNeutralCleanupfrom particula.dynamics.ions.coagulation import ( NEGATIVE_ION_MASS, POSITIVE_ION_MASS, AtmosphericCoagulation,)from particula.dynamics.ions.source import IonPairSourcefrom particula.gas import EnvironmentData, GasDatafrom particula.particles import ParticleDatafrom scipy.sparse import diagsfrom scipy.sparse.linalg import expm_multiply
ALPHA = 1.7e-12VOLUME = 2e-8 # m³ per independent box
def initial_state(boxes=64, capacity=256, initial_pairs=0): """Create independent physical boxes with two reserved ion materials.""" masses = np.zeros((boxes, capacity, 2)) counts = np.zeros((boxes, capacity)) charges = np.zeros((boxes, capacity)) for start, mass, sign, material in ( (0, POSITIVE_ION_MASS, 1, 0), (initial_pairs, NEGATIVE_ION_MASS, -1, 1), ): stop = start + initial_pairs masses[:, start:stop, material] = mass counts[:, start:stop] = 1 charges[:, start:stop] = sign ion_volume = np.pi / 6 * (0.5e-9) ** 3 return Aerosol( particles=ParticleData( masses, counts, charges, np.array([POSITIVE_ION_MASS, NEGATIVE_ION_MASS]) / ion_volume, np.full(boxes, VOLUME), distribution_type="particle_resolved", ), gas=GasData( ["inert air"], np.array([0.0289644]), np.zeros((boxes, 1)), np.array([False]), ), environment=EnvironmentData( np.full(boxes, 298.15), np.full(boxes, 101325.0), np.zeros((boxes, 1)), ), )An independent finite-population reference
Section titled “An independent finite-population reference”In one box there are always n positive and n negative free ions. The exact continuous-time birth–death process has transitions n → n+1 at rate qV and n → n−1 at rate αn²/V. We solve its master equation independently with a sparse matrix exponential. The upper state is a numerical truncation; its probability must remain below 10⁻¹⁰. This is not the GPU particle algorithm.
The familiar continuum equation dn/dt = q − αn² gives equilibrium √(q/α). Finite boxes fluctuate, so their ensemble mean need not exactly equal that continuum prediction. Both references are shown. Shading is a pointwise 95% normal interval for the mean of independent boxes, not an interval for an individual ion trajectory or a simultaneous confidence band.
Python · section 2
def finite_population_reference(q, initial_pairs, times, maximum_pairs=128): """Return pair-count moments at uniform times starting at zero.
The sparse exponential API returns an evenly spaced time grid. Reject incompatible inputs rather than labeling its results with different times. """ times = np.asarray(times, dtype=float) if ( times.ndim != 1 or times.size < 2 or not np.all(np.isfinite(times)) or times[0] != 0 or times[-1] <= 0 or not np.allclose( np.diff(times), times[-1] / (times.size - 1), rtol=1e-12, atol=0 ) ): raise ValueError("times must be uniform, increasing and start at zero") if type(maximum_pairs) is not int or maximum_pairs < 1: raise ValueError("maximum_pairs must be a positive integer") if ( type(initial_pairs) is not int or not 0 <= initial_pairs <= maximum_pairs ): raise ValueError("initial_pairs must be an integer within the chain") if not np.isfinite(q) or q < 0: raise ValueError("q must be finite and nonnegative") states = np.arange(maximum_pairs + 1, dtype=float) birth = np.full(maximum_pairs + 1, q * VOLUME) birth[-1] = 0 death = ALPHA * states**2 / VOLUME generator = diags( [birth[:-1], -(birth + death), death[1:]], [-1, 0, 1], format="csc", ) initial = np.zeros(maximum_pairs + 1) initial[initial_pairs] = 1 probabilities = expm_multiply( generator, initial, start=0, stop=float(times[-1]), num=len(times) ) assert probabilities[:, -2:].sum(axis=1).max() < 1e-10 np.testing.assert_allclose(probabilities.sum(axis=1), 1, rtol=0, atol=1e-10) mean = probabilities @ states variance = np.maximum(probabilities @ states**2 - mean**2, 0) return mean, variance
def run_case(q_cm3, *, boxes=64, capacity=256, time_step=1.0): """Run 2000 s, observing only box reductions and cumulative budgets.""" q = q_cm3 * 1e6 # pairs cm⁻³ s⁻¹ → pairs m⁻³ s⁻¹ initial_pairs = 20 if q == 0 else 0 initial = initial_state(boxes, capacity, initial_pairs) process = ( IonPairSource(q, 0, 1, POSITIVE_ION_MASS, NEGATIVE_ION_MASS) | AtmosphericCoagulation(0, 1, recombination=ALPHA) | IonNeutralCleanup(0, 1) ) times = np.linspace(0, 2000, 41) segment_steps = round(50 / time_step) assert segment_steps * time_step == 50 mean, sem = [], [] compute_seconds = 0.0 maximum_occupancy = 0 maximum_budget_error = 0.0 setup_start = perf_counter() with process.prepare( initial, device="cuda:0", time_step=time_step, root_seed=821 ) as simulation: simulation.capture() simulation.synchronize() setup_seconds = perf_counter() - setup_start for index in range(len(times)): if index: start = perf_counter() simulation.run(segment_steps) simulation.synchronize() compute_seconds += perf_counter() - start data = simulation.diagnostics() np.testing.assert_array_equal(data.charge_concentration, 0) # Cleanup leaves only free ions, with exactly equal polarities. pairs = data.number_concentration * VOLUME / 2 mean.append(pairs.mean()) sem.append(pairs.std(ddof=1) / np.sqrt(boxes)) maximum_occupancy = max(maximum_occupancy, data.active_slots.max()) source = simulation.ion_source_diagnostics() cleanup = simulation.ion_cleanup_diagnostics() before = initial.particles.masses.sum(axis=1) supplied = before + source["injected_mass"] accounted = ( data.particle_mass_concentration * VOLUME + cleanup["exported_mass"] ) np.testing.assert_allclose(accounted, supplied, rtol=2e-12, atol=0) nonzero = supplied > 0 if np.any(nonzero): maximum_budget_error = max( maximum_budget_error, np.max(np.abs(accounted[nonzero] / supplied[nonzero] - 1)), ) reference, variance = finite_population_reference(q, initial_pairs, times) mean, sem = np.asarray(mean), np.asarray(sem) uncertainty = np.sqrt(variance[1:] / boxes) # Fixed acceptance criterion for the stochastic implementation at dt=1 s. standardized_error = np.max(np.abs(mean[1:] - reference[1:]) / uncertainty) assert standardized_error < 6 print( f"q={q_cm3:g} pairs cm^-3 s^-1: {boxes} boxes, capacity={capacity}, " f"dt={time_step:g} s; max mean error={standardized_error:.2f} SE; " f"observed peak slots={maximum_occupancy}/{capacity}; " f"mass residual={maximum_budget_error:.2e}; " f"setup/capture={setup_seconds:.3f} s, " f"synchronized stepping={compute_seconds:.3f} s" ) return times, mean, sem, referenceRun the three source conditions
Section titled “Run the three source conditions”The workload contains 64 independent boxes per condition and 256 allocated slots per box. Cleanup runs after coagulation every second. No slot resizing or resampling occurs. Exhaustion raises an error instead of dropping ions. Timings separate preparation/capture from synchronized stepping and exclude the reference solver and analysis. Device exclusivity is not controlled; elapsed stepping can include contention from other GPU jobs. This small validation workload does not establish a CPU speedup or a maximum GPU particle count.
Python · section 3
def run_example(): """Compare CUDA ensembles with independent references and inspect budgets.""" if not wp.is_cuda_available(): raise RuntimeError("This example requires CUDA; no CPU fallback") figure, axes = plt.subplots(1, 3, figsize=(12, 4), constrained_layout=True) conversion = 1 / VOLUME / 1e6 # pairs per box → ions per polarity per cm³ for axis, q in zip(axes, [0, 2, 10], strict=True): times, mean, sem, reference = run_case(q) axis.plot(times, mean * conversion, label="CUDA ensemble") axis.fill_between( times, (mean - 1.96 * sem) * conversion, (mean + 1.96 * sem) * conversion, alpha=0.25, ) axis.plot(times, reference * conversion, "--", label="Finite-box exact") if q: continuum = ( np.sqrt(q * 1e6 / ALPHA) * np.tanh(np.sqrt(q * 1e6 * ALPHA) * times) / 1e6 ) else: n0 = 20 / VOLUME continuum = n0 / (1 + ALPHA * n0 * times) / 1e6 axis.plot(times, continuum, ":", label="Continuum") axis.set( title=f"q = {q} pairs cm⁻³ s⁻¹", xlabel="Time [s]", ylabel="Free ions per polarity [cm⁻³]", ) axes[0].legend(fontsize=8) plt.show() return figureInterpretation and next step
Section titled “Interpretation and next step”Charge remains zero because production and recombination both act on pairs. Mass is conserved after including externally supplied ion mass and exported neutral products. The two polarities therefore overlap exactly in this closed ion-only example. In an aerosol population their free concentrations can differ because attachment removes a particular sign from the free pool.
The source range is an illustrative sensitivity study, not a site-specific ionization measurement. The recombination coefficient is fixed at reference conditions; atmospheric composition and temperature dependence require a broader model. Before a survival claim, add attachment and condensation, then verify timestep, capacity, cleanup and ensemble convergence separately.
Primary sources:
- Yu (2010), ion-mediated nucleation and ionization sensitivity.
- Rose et al. (2013), cluster ion sources and sinks.
- Zauner-Wieczorek et al. (2022), ion–ion recombination review.
- López-Yglesias and Flagan (2013), attachment coefficients,
used by
AtmosphericCoagulationwhen aerosols are present; not exercised here.
Python · section 4
if __name__ == "__main__": run_example()Explicit cuda invocation
result = run_example()Warp 1.11.1 initialized:
CUDA Toolkit 12.9, Driver 13.4
Devices:
"cpu" : "CPU"
"cuda:0" : "NVIDIA GeForce RTX 5060" (8 GiB, sm_120, mempool enabled)
Kernel cache:
/tmp/particula-charged-warp
Module particula.gpu.kernels.coagulation 907b9eb load on device 'cuda:0' took 1.34 ms (cached)
Module particula.gpu.kernels.coagulation 583acfc load on device 'cuda:0' took 1.86 ms (cached)
Module particula.gpu.kernels.coagulation 33bf240 load on device 'cuda:0' took 1.75 ms (cached)
Module particula.gpu.kernels.environment e11375e load on device 'cuda:0' took 1.85 ms (cached)
Module particula.gpu.kernels.coagulation 5b8dfcc load on device 'cuda:0' took 1.35 ms (cached)
Module particula.gpu.kernels._coagulation_native f93a244 load on device 'cuda:0' took 1.77 ms (cached)
Module warp.utils f35afd3 load on device 'cuda:0' took 1.72 ms (cached)
Module warp.math edde159 load on device 'cuda:0' took 2.12 ms (cached)
Module warp.marching_cubes fb6e712 load on device 'cuda:0' took 1.16 ms (cached)
Module particula.execution.communication 2909959 load on device 'cuda:0' took 1.54 ms (cached)
Module particula.gpu.kernels._population_validation edde159 load on device 'cuda:0' took 2.19 ms (cached)
Module particula.gpu.kernels.communication ac9b2a2 load on device 'cuda:0' took 2.91 ms (cached)
Module particula.gpu.properties.gas_properties edde159 load on device 'cuda:0' took 2.19 ms (cached)
Module particula.gpu.properties.particle_properties edde159 load on device 'cuda:0' took 2.21 ms (cached)
Module particula.gpu.dynamics.coagulation_funcs edde159 load on device 'cuda:0' took 2.20 ms (cached)
Module particula.gpu.dynamics.condensation_funcs edde159 load on device 'cuda:0' took 2.20 ms (cached)
Module particula.gpu.kernels._condensation_native edde159 load on device 'cuda:0' took 2.20 ms (cached)
Module particula.gpu.kernels._condensation_parallel edde159 load on device 'cuda:0' took 2.21 ms (cached)
Module particula.gpu.kernels.thermodynamics edde159 load on device 'cuda:0' took 2.21 ms (cached)
Module particula.gpu.kernels.condensation edde159 load on device 'cuda:0' took 2.19 ms (cached)
Module particula.gpu.kernels.exhaustion ccbadfa load on device 'cuda:0' took 2.06 ms (cached)
Module particula.gpu.kernels.slot_management 0375e2c load on device 'cuda:0' took 1.15 ms (cached)
Module particula.gpu.kernels.nucleation 1124f09 load on device 'cuda:0' took 3.00 ms (cached)
Module particula.execution.gpu_resources 30f296c load on device 'cuda:0' took 2.08 ms (cached)
Module particula.gpu.warp_types edde159 load on device 'cuda:0' took 2.20 ms (cached)
Module particula.execution.prepared_diagnostics ca06582 load on device 'cuda:0' took 1.91 ms (cached)
Module particula.gpu.kernels.ion_source b9167ba load on device 'cuda:0' took 1.84 ms (cached)
Module particula.gpu.dynamics.ion_pair_data edde159 load on device 'cuda:0' took 2.20 ms (cached)
Module particula.gpu.kernels._brownian_parallel ccaec59 load on device 'cuda:0' took 2.37 ms (cached)
Module particula.execution.prepared_guards e16d312 load on device 'cuda:0' took 1.72 ms (cached)
Module particula.gpu.dynamics.ion_attachment edde159 load on device 'cuda:0' took 2.20 ms (cached)
Module particula.gpu.kernels.ion_coagulation 99b4407 load on device 'cuda:0' took 1.27 ms (cached)
Module particula.gpu.kernels.ion_cleanup 803bfea load on device 'cuda:0' took 1.77 ms (cached)
Module particula.gpu.kernels._brownian_parallel aae0d34 load on device 'cuda:0' took 3.84 ms (cached)
Module particula.gpu.kernels.coagulation 54d7db3 load on device 'cuda:0' took 2.78 ms (cached)
Module particula.gpu.kernels.coagulation d9d6c48 load on device 'cuda:0' took 0.87 ms (cached)
q=0 pairs cm^-3 s^-1: 64 boxes, capacity=256, dt=1 s; max mean error=1.58 SE; observed peak slots=40/256; mass residual=6.66e-16; setup/capture=0.714 s, synchronized stepping=1.946 s
q=2 pairs cm^-3 s^-1: 64 boxes, capacity=256, dt=1 s; max mean error=2.67 SE; observed peak slots=70/256; mass residual=7.77e-16; setup/capture=0.029 s, synchronized stepping=3.424 s
q=10 pairs cm^-3 s^-1: 64 boxes, capacity=256, dt=1 s; max mean error=2.54 SE; observed peak slots=128/256; mass residual=9.77e-15; setup/capture=0.026 s, synchronized stepping=10.743 s

Choose the reference for the population you simulate
Section titled “Choose the reference for the population you simulate”The finite-box curve and continuum curve answer different questions: the former retains discrete population fluctuations, while the latter evolves a smooth concentration. The printed standardized discrepancy checks the sampled CUDA means against the independent finite-box reference. Passing its six-standard-error criterion is not a claim that every point lies within the plotted 95% interval.
For a low-ion-concentration experiment, vary physical box volume at fixed source rate density and compare the gap between the two references. Increase the number of independent boxes to reduce sampling error without changing the physical volume within each box. Then refine timestep and capacity before adding aerosol attachment; otherwise finite-population effects and numerical bias can be mistaken for a charging mechanism.
Explore this topic: Charged particles and ions · GPU workflows