Examples
July 29, 2026 · View on GitHub
Welcome to the Particula Examples Gallery! Here you’ll find a curated collection of notebooks and step‑by‑step tutorials designed to help you explore, learn, and extend the core functionality of Particula. Whether you’re looking for a full end‑to‑end simulation, a focused how‑to guide, or a deep dive into individual components, each card below links to a ready‑to‑run example with contextual explanations and code snippets.
Use the End‑to‑End Simulations to see complete workflows in action, then explore the How‑To Guides for targeted recipes that tackle specific processes (e.g., chamber wall losses, thermodynamic equilibria, or nucleation events). Finally, the Tutorials section breaks down the building blocks of Particula’s architecture—Aerosol objects, Dynamics modules, Gas Phase definitions, and Particle Phase representations—so you can customize and combine them in your own research.
Jump in by selecting any card below and follow along in your browser or local environment. Happy modeling!
End-to-End Simulations
-
Biomass burning aerosols that activate into cloud droplets, simulating the interactions between aerosols and clouds.
-
Organic Partitioning and Coagulation
Simulation of organic partitioning on to seed particles and coagulation.
-
Simulates the evaporation of cough droplets, tracking size distribution and composition changes over time.
-
Simulates soot formation in a cooling combustion plume, tracking particle growth and chemical speciation.
-
Single activation-deactivation cycle with κ-theory hygroscopicity and wall loss in a rectangular chamber.
-
Four-cycle simulation comparing κ-dependent activation across ammonium sulfate, sucrose, and mixed seed scenarios.
How-To Guides
-
How to setup python and install
Particulavia pip. -
How to simulate experiments for the loss of particles to the chamber walls, including the strategy-based wall loss API (
WallLossStrategy,SphericalWallLossStrategy, andRectangularWallLossStrategy).- Wall Loss Tutorial — Geometry comparison plus coagulation/condensation chaining
-
How to simulate aerosol thermodynamic equilibria using the Binary Activity Thermodynamic
BATModel. Useful for water uptake and cloud droplet activation. -
Run the supported CPU single-box nucleation runnable, or review an illustrative custom workflow.
-
Learn how to compute chemical activity in organic-water mixtures using ideal, kappa, and BAT (non-ideal) models. Includes examples for equilibria calculations.
Tutorials
-
Learn what goes into the Aerosol object and why it is used.
-
Dynamics is a collection of classes that processes
Aerosolobjects, to perform coagulation, condensation, and other processes.Key examples:
- Wall Loss Builders and Factory
- Dilution Strategy System — public CPU-only scalar dilution API, contract, and boundaries
- CPU dilution source
— deterministic standalone example; run
python docs/Examples/cpu_dilution.py
-
Learn how to represent the Gas Phase, including vapor pressures and atmospheric properties.
-
Learn the shipped
ParticleDataandGasDatashapes, then run the canonical local example commandpython docs/Examples/data_containers_and_gpu_foundations.pyfor the documented CPU-only and optional Warp CPU-backend flow.Key examples:
- Data containers and GPU foundations —
ParticleData/GasDatashapes plus explicit transfer helpers - Direct GPU kernels quick-start source — a low-level explicit-transfer direct-condensation path with a Warp CPU default when installed, lazy direct and concrete imports, caller-owned fixed-shape fp64 scratch/latent/energy sidecars reused across explicit calls, gas coupling, and explicit final checkpoint restoration
- Direct GPU coagulation source — a standalone explicit-transfer, Warp CPU-default, low-level particle-resolved Brownian path: two supported direct calls reuse caller-owned collision and persistent RNG sidecars before an explicit CPU checkpoint restore. When Warp is unavailable or disabled, it does no conversion or kernel work and has no CPU fallback.
- GPU-resident session lifecycle source — a lazy, concrete-only lifecycle and in-memory checkpoint walkthrough. It demonstrates resident ownership, explicit same-device restart, and terminal finalization without scheduling, transport, fallback, or physics orchestration. Run
python docs/Examples/gpu_resident_session.py; setPARTICULA_EXAMPLE_FORCE_NO_WARP=1to verify its no-Warp path. - GPU coagulation strategy guide — supported direct-kernel mechanisms, validation boundaries, and release evidence.
- Canonical low-level direct-condensation contract — supported low-level scope and boundaries
- GPU condensation parity walkthrough — explicit-transfer, fixed-four-substep low-level direct-kernel evidence with separately reported physics, conservation, and energy results
- condensation parity walkthrough ownership record — deferred-capability ownership without expanding production support
Run
python docs/Examples/gpu_condensation_parity_walkthrough.py, thenpytest particula/gpu/tests/gpu_condensation_parity_walkthrough_test.py -q -Werrorandpytest particula/tests/condensation_parity_walkthrough_docs_test.py -q -Werror. Warp CPU is the installed-Warp baseline; CUDA is optional additive evidence. Its caller-owned, write-onlyenergy_transferoutput is a diagnostic, not a return value or temperature feedback (kg * J/kg = J). This direct-kernel example does not add high-level integration, adaptive execution, graph replay, broad autodiff, or performance claims. - Data containers and GPU foundations —
-
Learn about how to represent the Particle Phase, including different particle representations; radius bins, speciated mass bins, and particle resolved.