Skip to content

Examples

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

How-To Guides

  • Setup Particula

    How to setup python and install Particula via pip.

    Tutorial

  • Chamber Wall Loss

    How to simulate experiments for the loss of particles to the chamber walls, including the strategy-based wall loss API (WallLossStrategy, SphericalWallLossStrategy, and RectangularWallLossStrategy). - Wall Loss Tutorial — Geometry comparison plus coagulation/condensation chaining

    Tutorial

  • Equilibria

    How to simulate aerosol thermodynamic equilibria using the Binary Activity Thermodynamic BAT Model. Useful for water uptake and cloud droplet activation.

    Tutorial

  • Nucleation

    How to simulate aerosol nucleation by adding particles during simulations. Showing how to add a nucleation event.

    Tutorial

  • Activity Calculations

    Learn how to compute chemical activity in organic-water mixtures using ideal, kappa, and BAT (non-ideal) models. Includes examples for equilibria calculations.

    Tutorial

Tutorials

  • Aerosol

    Learn what goes into the Aerosol object and why it is used.

    Tutorial

  • Dynamics

    Dynamics is a collection of classes that processes Aerosol objects, 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

    Tutorial

  • Gas Phase

    Learn how to represent the Gas Phase, including vapor pressures and atmospheric properties.

    Tutorial

  • Data Containers

    Learn the shipped ParticleData and GasData shapes, then run the canonical local example command python docs/Examples/data_containers_and_gpu_foundations.py for the documented CPU-only and optional Warp CPU-backend flow.

    Key examples: - Data containers and GPU foundations — ParticleData / GasData shapes 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 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, then pytest particula/gpu/tests/gpu_condensation_parity_walkthrough_test.py -q -Werror and pytest 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-only energy_transfer output 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.

    Guide

  • Particle Phase

    Learn about how to represent the Particle Phase, including different particle representations; radius bins, speciated mass bins, and particle resolved.

    Tutorial