pyrcel: cloud parcel model

pyrcel is a simple, adiabatic cloud parcel model for use in
aerosol-cloud interaction studies. Rothenberg and Wang (2016) discuss the model in detail and its improvements over Nenes et al (2001):

• Implementation of κ-Köhler theory for condensation physics (Petters and Kreidenweis, 2007)
• Extension of model to handle arbitrary sectional representations of aerosol populations, based on user-controlled empirical or parameterized size distributions
• JAX/diffrax-based numerical core — differentiable, batchable, GPU-ready, with no Fortran/SUNDIALS dependency

Detailed documentation is available, including a scientific description, installation details, and a basic example.

[!WARNING]
Version 2.0 Notice

This is pyrcel v2.0, a major new release with more features, greater flexibility, and a JAX-based differentiable kernel. However, there are several breaking changes compared to version 1.3.x.

Please review the migration guide to update your code.

If you wish to continue using the legacy (v1.3.x) model, you can install it from PyPI by pinning the version:

pip install "pyrcel<2"

Quick Start

The easiest way to run pyrcel from source is with uv:

$ git clone https://github.com/darothen/pyrcel.git && cd pyrcel
$ uv run python examples/basic_run.py

uv will automatically create an isolated environment and install all dependencies.
The first call compiles JAX kernels; subsequent calls are fast.

Usage

import pyrcel as pm

sulfate = pm.AerosolSpecies(
    "sulfate", pm.Lognorm(mu=0.05, sigma=2.0, N=1000.0), kappa=0.54, bins=50
)
model = pm.ParcelModel([sulfate], V=1.0, T0=283.0, S0=-0.02, P0=85000.0, console=True)
output = model.run(t_end=300.0, output_dt=10.0, terminate=True, live=True)

print(f"S_max  = {output.summary['S_max']*100:.3f} %")
print(f"N_act  = {output.Nd:.3e} m⁻³")

Key capabilities:

• Autodiff — exact gradients of S_max w.r.t. updraft speed, initial conditions,
  accommodation coefficient, and aerosol properties via jax.grad.
• Batching / GPU — jax.vmap runs ensembles of parcels in one compiled call;
  pass device="gpu" to ParcelModel for CUDA acceleration.
• Time-varying updraft — pass a pyrcel.InterpolatedUpdraft(ts=..., vs=...) as V.
• Flexible output — output.to_pandas(), .to_xarray(), .to_netcdf(), .to_parquet().

The differentiable core (pyrcel.integrator, pyrcel.equilibrate) is usable directly
for jit/grad/vmap; ParcelModel is the interactive convenience layer (console
output, progress meter, post-solve summary table).

Installation

From PyPI (recommended):

$ pip install pyrcel

JAX (CPU) is included by default. No extras needed for standard use.

From source:

$ git clone https://github.com/darothen/pyrcel.git && cd pyrcel
$ uv sync
$ uv run python examples/basic_run.py

GPU support (CUDA 12):

$ pip install "pyrcel[gpu]"

Requirements

• Python >= 3.11
• JAX >= 0.4.38
• diffrax >= 0.6.2
• equinox >= 0.11.10
• optimistix >= 0.0.7
• NumPy, SciPy, pandas, polars, xarray

Development

Clone the repo and install with dev dependencies:

$ git clone https://github.com/darothen/pyrcel.git && cd pyrcel
$ uv sync --extra test
$ prek install   # installs the git pre-commit hook (requires prek: https://prek.j178.dev)

Run the fast test suite:

$ uv run pytest tests/ -m "not slow"

Lint and format are handled automatically by prek on commit, or run manually:

$ prek run --all-files

Please fork this repository if you intend to develop the model further so that the
code's provenance can be maintained.

License / Usage

All scientific code should be licensed. This code is released under the New BSD (3-clause) license.

If you use this for any scientific work resulting in a publication, please cite our
original publication detailing the model:

@article {
      author = "Daniel Rothenberg and Chien Wang",
      title = "Metamodeling of Droplet Activation for Global Climate Models",
      journal = "Journal of the Atmospheric Sciences",
      year = "2016",
      publisher = "American Meteorological Society",
      address = "Boston MA, USA",
      volume = "73",
      number = "3",
      doi = "10.1175/JAS-D-15-0223.1",
      pages= "1255 - 1272",
      url = "https://journals.ametsoc.org/view/journals/atsc/73/3/jas-d-15-0223.1.xml"
}

Additionally, please consider citing the bespoke DOI for the
specific release version of pyrcel
that you used during your research (or the base version you modified). This
allows us to track adoption and use of specific model versions over time.