Build on the CPU, evolve on CUDA, analyze on the CPU
Build on the CPU, evolve on CUDA, analyze on the CPU
Section titled “Build on the CPU, evolve on CUDA, analyze on the CPU”How do you keep a cooling experiment reproducible while its state lives on a GPU? Follow construction, physical evolution, and detached analysis as separate stages. You will learn which evidence comes from inventory checks, timestep refinement, and checkpoint replay. Begin with native aerosol assembly if counts, volume, or species ordering are unfamiliar.
A prepared simulation owns the complete aerosol state on one GPU. Construct
particles, gas and environment normally, compose supported processes with
|, then call prepare once. run keeps state resident. snapshot returns
detached NumPy arrays for analysis and plotting.
This example contains eight independent boxes, 1,024 resolved particles per box, two particle materials, and three gas species. Water is gas lane 2 and particle material 0: an explicit species map preserves that distinction. Temperature varies between boxes. After one millisecond, every box cools by 5 K. We capture the subsequent schedule and verify exact checkpoint continuation. A second run halves the timestep at the same forcing time and checks final particle masses and vapor. This is a short, illustrative cooling experiment. CUDA is required; there is no CPU fallback or GPU timing claim here.
Python · section 1
"""A complete native CPU → prepared CUDA → CPU analysis workflow."""
import numpy as npfrom particula import Aerosolfrom particula.dynamics import Dilution, DilutionStrategy, MassCondensationfrom particula.dynamics.condensation.condensation_strategies import ( CondensationIsothermal,)from particula.dynamics.condensation.species_mapping import ( CondensationSpeciesMap,)from particula.execution import Backendfrom particula.gas import EnvironmentData, GasDatafrom particula.gas.vapor_pressure_strategies import ( ConstantVaporPressureStrategy, WaterBuckStrategy,)from particula.particles import ParticleDatafrom particula.particles.activity_strategies import ActivityIdealMolarfrom particula.particles.surface_strategies import SurfaceStrategyVolumefrom particula.util.constants import GAS_CONSTANT
def build_aerosol(): """Construct float64 native state with unit particle multiplicities.""" boxes, slots = 8, 1024 rng = np.random.default_rng(42) radius = rng.lognormal(np.log(35e-9), np.log(1.6), (boxes, slots)) total_mass = 4 * np.pi / 3 * 1000 * radius**3 masses = total_mass[..., None] * np.array([0.2, 0.8]) temperature = np.linspace(278.15, 308.15, boxes) molar_mass = np.array([0.028, 0.2, 0.018]) gas = np.full((boxes, 3), 1e-8) celsius = temperature - 273.15 pressure_water = 611.21 * np.exp( (18.678 - celsius / 234.5) * celsius / (257.14 + celsius) ) gas[:, 2] = ( 1.3 * pressure_water * molar_mass[2] / (GAS_CONSTANT * temperature) ) return Aerosol( particles=ParticleData( masses=masses, concentration=np.ones((boxes, slots)), # counts, not m^-3 charge=np.zeros((boxes, slots)), density=np.array([1000.0, 1000.0]), volume=np.full(boxes, slots / 5e13), distribution_type="particle_resolved", ), gas=GasData( name=["inert", "tracer", "water"], molar_mass=molar_mass, concentration=gas, # kg m^-3 partitioning=np.array([False, False, True]), ), environment=EnvironmentData( temperature=temperature, pressure=np.full(boxes, 101325.0), saturation_ratio=np.ones((boxes, 3)), ), )Bind supported physics explicitly
Section titled “Bind supported physics explicitly”The condensation configuration supplies the water vapor-pressure law, ideal molar activity, surface tension and transport coefficients. Each CUDA condensation call performs four equal coupled substeps. Dilution removes particle counts and gas with the same exponential factor.
Preparation validates this configuration before upload and freezes it for the session. Editing the original process object later does not change the prepared calculation. Unsupported strategies raise an error.
Python · section 2
def build_process(aerosol): """Compose water condensation and dilution without backend-specific physics.""" condensation = MassCondensation( CondensationIsothermal( molar_mass=aerosol.gas.molar_mass.copy(), diffusion_coefficient=np.full(3, 2e-5), accommodation_coefficient=np.full(3, 0.5), activity_strategy=ActivityIdealMolar(np.array([0.018, 0.2])), surface_strategy=SurfaceStrategyVolume( surface_tension=0.072, density=1000.0 ), vapor_pressure_strategy=( ConstantVaporPressureStrategy(1.0), ConstantVaporPressureStrategy(1.0), WaterBuckStrategy(), ), species_map=CondensationSpeciesMap( tuple(aerosol.gas.name), ((2, 0),) ), ) ) return condensation | Dilution(DilutionStrategy(0.02))
def water_inventory(aerosol): """Compute extensive water inventory independently from CPU snapshot arrays.""" p = aerosol.particles return np.sum(p.masses[..., 0] * p.concentration, axis=1) + ( aerosol.gas.concentration[:, 2] * p.volume )Run, change forcing, capture and restart
Section titled “Run, change forcing, capture and restart”update_environment is an explicit synchronization and upload boundary.
capture() records the schedule without taking a scientific timestep.
A snapshot is for inspection; a checkpoint additionally retains process
configuration, random continuation and canonical state for exact restart.
A resumed session can capture its own new graph if desired.
Python · section 3
def run_example(): """Execute the complete three-millisecond CUDA trajectory and exact continuation.""" import matplotlib.pyplot as plt import warp as wp
if not wp.is_cuda_available(): raise RuntimeError("This example requires CUDA; no CPU fallback") initial = build_aerosol() process = build_process(initial) original_masses = initial.particles.masses.copy() with process.prepare( initial, backend=Backend.WARP, device="cuda:0", time_step=1e-6, root_seed=7, logical_box_ids=tuple(f"box-{i}" for i in range(8)), ) as simulation: simulation.run(steps=1000) warm = simulation.snapshot() simulation.update_environment( temperature=initial.environment.temperature - 5.0 ) simulation.capture() simulation.run(steps=1000) saved = simulation.checkpoint() simulation.run(steps=1000) final = simulation.snapshot() diagnostics = simulation.diagnostics() with process.resume(saved) as resumed: resumed.run(steps=1000) continued = resumed.snapshot() for field in ("masses", "concentration", "charge", "volume"): np.testing.assert_array_equal( getattr(final.particles, field), getattr(continued.particles, field) ) np.testing.assert_array_equal( final.gas.concentration, continued.gas.concentration ) np.testing.assert_array_equal(initial.particles.masses, original_masses) expected = water_inventory(initial) * np.exp(-0.02 * 0.003) np.testing.assert_allclose( water_inventory(final), expected, rtol=2e-12, atol=1e-30 ) if not np.any(final.particles.masses != original_masses): raise AssertionError("No condensation occurred") verify_refinement(initial, process, final, expected) plot_snapshots(initial, warm, final) print("CUDA:", wp.get_device("cuda:0").name) print("Physical time: 3 ms; 8 boxes × 1024 particle slots; float64.") print( "Final number concentrations (m^-3):", diagnostics.number_concentration ) print( "Water inventory matches dilution; restart is exact; CPU input is unchanged." ) plt.show() return final
def verify_refinement(initial, process, coarse, expected_inventory): """Check final-state timestep sensitivity at identical forcing times.""" with process.prepare(initial, device="cuda:0", time_step=5e-7) as refined: refined.capture() refined.run(steps=2000) refined.update_environment( temperature=initial.environment.temperature - 5.0 ) refined.run(steps=4000) fine = refined.snapshot() coarse_mass = coarse.particles.masses.sum(axis=2) fine_mass = fine.particles.masses.sum(axis=2) np.testing.assert_allclose(coarse_mass, fine_mass, rtol=0.01, atol=0) np.testing.assert_allclose( coarse.gas.concentration[:, 2], fine.gas.concentration[:, 2], rtol=0.001, atol=0, ) np.testing.assert_allclose( water_inventory(fine), expected_inventory, rtol=2e-12, atol=1e-30 ) print( "Maximum final particle-mass change with half timestep:", np.max(np.abs(coarse_mass / fine_mass - 1)), )Analyze detached snapshots
Section titled “Analyze detached snapshots”The left panel compares size distributions before and after cooling in two boxes. The right panel shows the final distribution in every box. Histogram weights use represented counts divided by each box’s volume and by bin width in log10 radius. These are particle-resolved histograms, not a PDF solver.
Python · section 4
def plot_snapshots(initial, warm, final): """Plot distributions using only CPU NumPy arrays.""" import matplotlib.pyplot as plt from matplotlib.colors import LogNorm
edges = np.geomspace(5e-9, 2e-6, 55)
def histogram(state): p = state.particles radius = np.cbrt( np.sum(p.masses / p.density, axis=-1) * 3 / (4 * np.pi) ) return np.array( [ np.histogram(r, bins=edges, weights=c / v)[0] for r, c, v in zip( radius, p.concentration, p.volume, strict=True ) ] ) / np.diff(np.log10(edges))
fig, axes = plt.subplots(1, 2, figsize=(11, 4), constrained_layout=True) for box, color in ((0, "#287a90"), (7, "#be6c39")): for state, style, label in ( (initial, ":", "initial"), (warm, "--", "1 ms"), (final, "-", "3 ms"), ): axes[0].stairs( histogram(state)[box], edges * 1e9, color=color, linestyle=style, label=f"Box {box + 1}, {label}", ) axes[0].set( xscale="log", xlabel="Radius (nm)", ylabel="dN / dlog₁₀ r (m$^{-3}$)" ) axes[0].legend(fontsize=8) values = histogram(final) mesh = axes[1].pcolormesh( edges * 1e9, np.arange(9) + 0.5, np.ma.masked_less_equal(values, 0), norm=LogNorm(), cmap="viridis", shading="flat", ) axes[1].set( xscale="log", xlabel="Radius (nm)", ylabel="Box", yticks=np.arange(8) + 1, ) fig.colorbar(mesh, ax=axes[1], label="dN / dlog₁₀ r (m$^{-3}$)") fig.suptitle( "Prepared CUDA simulation · cooling eight particle-resolved boxes" )
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:
~/.cache/warp/1.11.1
Module particula.gpu.kernels.condensation 14a649a load on device 'cuda:0' took 0.44 ms (cached)
Module particula.gpu.kernels.condensation 2c7d291 load on device 'cuda:0' took 0.29 ms (cached)
Module particula.gpu.kernels.environment e11375e load on device 'cuda:0' took 0.26 ms (cached)
Module particula.gpu.kernels._condensation_native 34375de load on device 'cuda:0' took 0.34 ms (cached)
Module particula.gpu.kernels.dilution 0472484 load on device 'cuda:0' took 0.53 ms (cached)
Module particula.gpu.kernels._population_validation 65eaa49 load on device 'cuda:0' took 0.35 ms (cached)
Module particula.gpu.kernels.thermodynamics 563d292 load on device 'cuda:0' took 0.30 ms (cached)
Module particula.execution.prepared_guards e16d312 load on device 'cuda:0' took 0.39 ms (cached)
Module particula.gpu.kernels.condensation c7ee7df load on device 'cuda:0' took 0.28 ms (cached)
Module particula.gpu.kernels.condensation 57dfed0 load on device 'cuda:0' took 0.33 ms (cached)
Module particula.gpu.kernels.condensation 75f771c load on device 'cuda:0' took 0.69 ms (cached)
Module particula.gpu.kernels._condensation_native 9623455 load on device 'cuda:0' took 0.26 ms (cached)
Module particula.gpu.kernels.condensation 825fe64 load on device 'cuda:0' took 0.74 ms (cached)
Module particula.gpu.kernels._condensation_native 76403ad load on device 'cuda:0' took 0.28 ms (cached)
Module particula.gpu.kernels.condensation a676aa8 load on device 'cuda:0' took 0.64 ms (cached)
Module particula.gpu.kernels._condensation_native c295a4d load on device 'cuda:0' took 0.32 ms (cached)
Module particula.gpu.kernels._condensation_native a80ebff load on device 'cuda:0' took 0.38 ms (cached)
Module particula.gpu.kernels.condensation eb50632 load on device 'cuda:0' took 0.68 ms (cached)
Module particula.gpu.kernels.condensation d75c422 load on device 'cuda:0' took 0.56 ms (cached)
Module particula.gpu.kernels.condensation f9743ab load on device 'cuda:0' took 0.53 ms (cached)
Module particula.gpu.kernels._condensation_native ff4cf87 load on device 'cuda:0' took 1.38 ms (cached)
Module warp.utils f35afd3 load on device 'cuda:0' took 0.44 ms (cached)
Module warp.math edde159 load on device 'cuda:0' took 0.35 ms (cached)
Module warp.marching_cubes fb6e712 load on device 'cuda:0' took 0.46 ms (cached)
Module particula.execution.communication 2909959 load on device 'cuda:0' took 0.32 ms (cached)
Module particula.gpu.kernels.communication ac9b2a2 load on device 'cuda:0' took 1.64 ms (cached)
Module particula.gpu.properties.gas_properties edde159 load on device 'cuda:0' took 0.19 ms (cached)
Module particula.gpu.properties.particle_properties edde159 load on device 'cuda:0' took 0.16 ms (cached)
Module particula.gpu.dynamics.coagulation_funcs edde159 load on device 'cuda:0' took 0.14 ms (cached)
Module particula.gpu.dynamics.condensation_funcs edde159 load on device 'cuda:0' took 0.14 ms (cached)
Module particula.gpu.kernels._condensation_parallel edde159 load on device 'cuda:0' took 0.13 ms (cached)
Module particula.gpu.kernels.exhaustion ccbadfa load on device 'cuda:0' took 1.16 ms (cached)
Module particula.gpu.kernels.slot_management 0375e2c load on device 'cuda:0' took 0.46 ms (cached)
Module particula.gpu.kernels.nucleation 1124f09 load on device 'cuda:0' took 2.23 ms (cached)
Module particula.execution.gpu_resources 30f296c load on device 'cuda:0' took 0.25 ms (cached)
Module particula.gpu.warp_types edde159 load on device 'cuda:0' took 0.17 ms (cached)
Module particula.execution.prepared_diagnostics ca06582 load on device 'cuda:0' took 0.27 ms (cached)
Maximum final particle-mass change with half timestep: 0.0005447897173971317
CUDA: NVIDIA GeForce RTX 5060
Physical time: 3 ms; 8 boxes × 1024 particle slots; float64.
Final number concentrations (m^-3): [4.99970001e+13 4.99970001e+13 4.99970001e+13 4.99970001e+13
4.99970001e+13 4.99970001e+13 4.99970001e+13 4.99970001e+13]
Water inventory matches dilution; restart is exact; CPU input is unchanged.

What this short cooling experiment establishes
Section titled “What this short cooling experiment establishes”The snapshots show how water exchange changes a distribution while dilution changes its abundance. The tests separately establish the stated water ledger, exact restart for the compared fields, unchanged CPU input, and bounded final mass/vapor changes under one timestep halving. These do not validate the chosen material properties or isolate cooling from continued evolution.
For a cooling-rate question, add an otherwise identical uncooled control and compare size-resolved water uptake at the same physical times. Keep gas/material mapping explicit and refine any rapid forcing transitions. Continue with the heterogeneous ensemble for more boxes or custom process example to supply a new forcing law.
Explore this topic: Prepared simulations