Data Structures for Aerosol Simulation
These are standalone Warp teaching patterns, not Particula native container or process APIs. Snippets share surrounding definitions and may require a CUDA device where explicitly selected. They do not validate coupled aerosol physics, conservation, performance or public-step autodiff. For the supported native path, use GPU foundations and its executed direct/resident examples.
Overview
Section titled “Overview”NVIDIA Warp provides a rich set of data structures optimized for parallel computation on both CPU and GPU. For particula, these structures efficiently represent particle populations, aerosol properties, and simulation state.
Arrays
Section titled “Arrays”Array Types
Section titled “Array Types”Warp arrays are the primary container for particle data:
import warp as wpimport numpy as np
# 1D array for particle diametersdiameters = wp.array([1e-6, 2e-6, 5e-6], dtype=float)
# From NumPy (common for initialization)concentrations = np.random.uniform(1e6, 1e8, size=1000) # #/m³conc_array = wp.array(concentrations, dtype=float)
# Multi-dimensional arrays for coagulation kernelskernel_matrix = wp.zeros((100, 100), dtype=float)Array Properties
Section titled “Array Properties”# Shapeprint(diameters.shape) # (3,)
# Data typeprint(diameters.dtype) # float32
# Device (CPU or GPU)print(diameters.device) # "cpu" or "cuda"
# Size (number of particles)print(diameters.size) # 3Array Operations
Section titled “Array Operations”# Create arrays on GPU for large particle populationsn_particles = 100000gpu_positions = wp.zeros(n_particles, dtype=wp.vec3, device="cuda")gpu_diameters = wp.zeros(n_particles, dtype=float, device="cuda")
# Copy between CPU and GPUcpu_data = wp.array(np.ones(n_particles) * 1e-6, dtype=float)gpu_diameters.assign(cpu_data)
# Convert back to NumPy for analysisresult = gpu_diameters.numpy()Vector Types
Section titled “Vector Types”Particle Position and Velocity
Section titled “Particle Position and Velocity”Warp provides fixed-size vector types ideal for 3D particle tracking:
# 3D position vector (meters)position = wp.vec3(0.0, 0.0, 0.0)
# 3D velocity vector (m/s)velocity = wp.vec3(1e-3, 0.0, -1e-4)
# 2D for simplified simulationsposition_2d = wp.vec2(0.0, 0.0)Vector Operations in Kernels
Section titled “Vector Operations in Kernels”@wp.kerneldef update_particle_positions( positions: wp.array(dtype=wp.vec3), velocities: wp.array(dtype=wp.vec3), dt: float,): tid = wp.tid()
# Vector addition positions[tid] = positions[tid] + velocities[tid] * dt
@wp.kerneldef compute_settling_velocities( diameters: wp.array(dtype=float), densities: wp.array(dtype=float), velocities: wp.array(dtype=wp.vec3), air_density: float, viscosity: float,): tid = wp.tid()
d = diameters[tid] rho_p = densities[tid]
# Stokes settling velocity (downward) g = 9.81 # m/s² v_settle = (rho_p - air_density) * g * d * d / (18.0 * viscosity)
# Set velocity vector (settling in -z direction) velocities[tid] = wp.vec3(0.0, 0.0, -v_settle)Distance Calculations
Section titled “Distance Calculations”@wp.funcdef particle_separation(pos_i: wp.vec3, pos_j: wp.vec3) -> float: """Calculate distance between two particles.""" diff = pos_j - pos_i return wp.length(diff)
@wp.funcdef unit_direction(pos_i: wp.vec3, pos_j: wp.vec3) -> wp.vec3: """Unit vector from particle i to particle j.""" diff = pos_j - pos_i dist = wp.length(diff) if dist > 1e-12: return diff / dist return wp.vec3(0.0, 0.0, 0.0)Matrix Types
Section titled “Matrix Types”Coagulation Kernel Matrices
Section titled “Coagulation Kernel Matrices”@wp.kerneldef build_coagulation_matrix( diameters: wp.array(dtype=float), kernel_matrix: wp.array2d(dtype=float), temperature: float, viscosity: float, k_boltzmann: float, # from particula.util.constants.BOLTZMANN_CONSTANT): """Build pairwise coagulation kernel matrix K[i,j].""" i, j = wp.tid()
d_i = diameters[i] d_j = diameters[j]
# Brownian coagulation kernel K_ij = (2.0 * k_boltzmann * temperature / (3.0 * viscosity)) * \ (d_i + d_j) * (1.0/d_i + 1.0/d_j)
kernel_matrix[i, j] = K_ijTransformation Matrices
Section titled “Transformation Matrices”For rotating reference frames or coordinate transformations:
@wp.funcdef rotation_matrix_z(angle: float) -> wp.mat33: """Rotation matrix about z-axis.""" c = wp.cos(angle) s = wp.sin(angle) return wp.mat33(c, -s, 0.0, s, c, 0.0, 0.0, 0.0, 1.0)
@wp.kerneldef rotate_velocities( velocities: wp.array(dtype=wp.vec3), angle: float,): """Rotate all particle velocities.""" tid = wp.tid() R = rotation_matrix_z(angle) velocities[tid] = R * velocities[tid]Custom Structs
Section titled “Custom Structs”Particle Structure
Section titled “Particle Structure”Define custom data structures for aerosol particles:
@wp.structclass Particle: """Single aerosol particle properties.""" position: wp.vec3 # Position (m) velocity: wp.vec3 # Velocity (m/s) diameter: float # Diameter (m) mass: float # Mass (kg) density: float # Material density (kg/m³) charge: int # Number of elementary charges
@wp.structclass ParticleSpecies: """Properties of a particle species/component.""" molar_mass: float # Molar mass (kg/mol) density: float # Bulk density (kg/m³) surface_tension: float # Surface tension (N/m) vapor_pressure: float # Saturation vapor pressure (Pa) hygroscopicity: float # Kappa hygroscopicity parameter
@wp.kerneldef update_particles( particles: wp.array(dtype=Particle), dt: float, gravity: wp.vec3,): """Update particle positions and velocities.""" tid = wp.tid() p = particles[tid]
# Apply gravity acceleration = gravity p.velocity = p.velocity + acceleration * dt p.position = p.position + p.velocity * dt
particles[tid] = pAerosol Distribution Structure
Section titled “Aerosol Distribution Structure”@wp.structclass SizeDistribution: """Log-normal size distribution parameters.""" geometric_mean: float # Geometric mean diameter (m) geometric_std: float # Geometric standard deviation total_number: float # Total number concentration (#/m³)
@wp.structclass AerosolState: """Complete aerosol system state.""" temperature: float # Temperature (K) pressure: float # Pressure (Pa) relative_humidity: float # Relative humidity (0-1) n_particles: int # Number of particlesHash Grids for Neighbor Search
Section titled “Hash Grids for Neighbor Search”Spatial Hashing for Coagulation
Section titled “Spatial Hashing for Coagulation”Efficient neighbor searches for particle-particle interactions:
# Create hash grid for spatial queriesgrid = wp.HashGrid(dim_x=64, dim_y=64, dim_z=64)
@wp.kerneldef build_particle_grid( positions: wp.array(dtype=wp.vec3), grid: wp.uint64,): """Build spatial hash grid from particle positions.""" tid = wp.tid() wp.hash_grid_point_id(grid, tid, positions[tid])
@wp.kerneldef find_collision_candidates( positions: wp.array(dtype=wp.vec3), diameters: wp.array(dtype=float), grid: wp.uint64, collision_pairs: wp.array(dtype=wp.vec2i), n_collisions: wp.array(dtype=int), search_radius: float,): """Find particle pairs within collision distance.""" tid = wp.tid() pos_i = positions[tid] d_i = diameters[tid]
# Query neighbors within search radius query = wp.hash_grid_query(grid, pos_i, search_radius) neighbor_idx = wp.hash_grid_query_next(query, grid)
while neighbor_idx >= 0: if neighbor_idx > tid: # Avoid double counting pos_j = positions[neighbor_idx] d_j = diameters[neighbor_idx]
# Check if particles overlap dist = wp.length(pos_j - pos_i) collision_dist = 0.5 * (d_i + d_j)
if dist < collision_dist: # Record collision pair idx = wp.atomic_add(n_collisions, 0, 1) collision_pairs[idx] = wp.vec2i(tid, neighbor_idx)
neighbor_idx = wp.hash_grid_query_next(query, grid)Chamber Geometry
Section titled “Chamber Geometry”Mesh for Wall Loss Calculations
Section titled “Mesh for Wall Loss Calculations”# Define chamber walls as triangulated meshvertices = wp.array(vertex_data, dtype=wp.vec3)indices = wp.array(index_data, dtype=int)
chamber_mesh = wp.Mesh(vertices, indices)
@wp.kerneldef compute_wall_distances( positions: wp.array(dtype=wp.vec3), mesh: wp.uint64, wall_distances: wp.array(dtype=float),): """Compute distance from each particle to nearest wall.""" tid = wp.tid() pos = positions[tid]
# Find closest point on mesh face_idx = int(0) face_u = float(0.0) face_v = float(0.0) sign = float(0.0)
if wp.mesh_query_point(mesh, pos, 1e6, sign, face_idx, face_u, face_v): # Get closest point on face closest = wp.mesh_eval_position(mesh, face_idx, face_u, face_v) wall_distances[tid] = wp.length(pos - closest) else: wall_distances[tid] = 1e6 # No wall foundPerformance Tips
Section titled “Performance Tips”Structure of Arrays vs Array of Structures
Section titled “Structure of Arrays vs Array of Structures”# Structure of Arrays (SoA) - Better for GPU# Each property is a separate arraypositions = wp.zeros(n_particles, dtype=wp.vec3)diameters = wp.zeros(n_particles, dtype=float)masses = wp.zeros(n_particles, dtype=float)concentrations = wp.zeros(n_particles, dtype=float)
# Array of Structures (AoS) - More convenient# Single array of Particle structsparticles = wp.zeros(n_particles, dtype=Particle)Recommendation: Use SoA for large particle populations (>10,000) where performance matters. Use AoS for smaller simulations where code clarity is more important.
Data Transfer Optimization
Section titled “Data Transfer Optimization”# BAD: Multiple CPU-GPU transfers per timestepfor step in range(n_steps): data = gpu_array.numpy() # Transfer to CPU # ... process on CPU gpu_array.assign(data) # Transfer back to GPU
# GOOD: Keep data on GPU, transfer only when neededfor step in range(n_steps): wp.launch(process_kernel, dim=n, inputs=[gpu_array])
# Transfer only for output/analysisif step % output_interval == 0: result = gpu_array.numpy()For environment state, the same rule applies through explicit helper APIs only.
particula.gpu.WarpEnvironmentData is the Warp-side mirror of
particula.gas.EnvironmentData: the CPU object owns the host-side
thermodynamic state, while the Warp object keeps the same logical fields in
Warp arrays on the selected device. Callers choose when to cross the CPU↔GPU
boundary with to_warp_environment_data() and
from_warp_environment_data(). Kernels and runnables do not perform hidden
CPU↔GPU environment transfers or synchronization for you, and CUDA support is
optional rather than required for this helper workflow.
EnvironmentData Round-Trip Example
Section titled “EnvironmentData Round-Trip Example”This explicit round trip keeps the same shape contract on both sides of the transfer:
temperature:(n_boxes,)pressure:(n_boxes,)saturation_ratio:(n_boxes, n_species)
import numpy as np
from particula.gas import EnvironmentDatafrom particula.gpu import ( WarpEnvironmentData, from_warp_environment_data, to_warp_environment_data,)
environment = EnvironmentData( temperature=np.array([298.15, 305.0]), pressure=np.array([101325.0, 90000.0]), saturation_ratio=np.array( [[0.95, 1.05, 0.75], [0.8, 0.9, 1.1]], ),)
gpu_environment: WarpEnvironmentData = to_warp_environment_data( environment, device="cpu",)restored = from_warp_environment_data(gpu_environment)
assert restored.temperature.shape == (2,)assert restored.pressure.shape == (2,)assert restored.saturation_ratio.shape == (2, 3)assert np.array_equal(restored.temperature, environment.temperature)assert np.array_equal(restored.pressure, environment.pressure)assert np.array_equal( restored.saturation_ratio, environment.saturation_ratio,)Use device="cpu" for a portable round trip on any Warp installation.
device="cuda" is optional and should be used only when Warp CUDA support is
available. The important design rule is that transfer boundaries stay visible:
build EnvironmentData, convert explicitly to WarpEnvironmentData, let
kernels or runnables consume that mirror in place, and convert back to
EnvironmentData only when CPU-side analysis or control flow actually needs
the data.
Pre-allocation
Section titled “Pre-allocation”# Pre-allocate all arrays before simulation looppositions = wp.zeros(n_particles, dtype=wp.vec3)velocities = wp.zeros(n_particles, dtype=wp.vec3)diameters = wp.zeros(n_particles, dtype=float)temp_buffer = wp.zeros(n_particles, dtype=float) # For intermediate results
# Reuse arrays across timestepsfor step in range(n_steps): wp.launch(compute_kernel, dim=n, inputs=[positions, velocities, temp_buffer]) # temp_buffer is reused each stepSee Also
Section titled “See Also”- Kernels and Function Inlining - Writing parallel particle computations
- Aerosol Dynamics Example - Coagulation, condensation
- Particle Interactions Example - Collisions, wall loss
Explore this topic: Warp implementation