CliMA/CloudMicrophysics.jl: bulk microphysics parameterizations for Julia climate models

What CloudMicrophysics.jl actually provides, and to whom

This is a parameterization library, not a model. The README describes it as "a library of cloud microphysics and aerosol parameterizations for the CliMA Earth System Model" and lists bulk schemes for cloud formation, precipitation and aerosol processes. That framing matters: you do not run CloudMicrophysics.jl on a grid. You call its functions from something that already has a grid, a time step and a thermodynamic state.

The intended audience is narrow and identifiable. The README points to ClimaAtmos as the atmospheric model, KinematicDriver as a 1D/2D kinematic framework, and Thermodynamics.jl for moist thermodynamics. If you are working inside that ecosystem, the package is the physics layer you would otherwise write yourself. If you are outside it, you are borrowing kernels and supplying your own driver.

The feature list is the useful part of the README. Four bulk microphysics schemes are named: a 0-moment scheme for simple precipitation removal, a 1-moment scheme using Marshall-Palmer distributions for rain and snow, a 2-moment scheme following Seifert & Beheng (2006) with mass and number concentration, and the P3 scheme from Morrison & Milbrandt (2015), which predicts particle properties for ice. Ice nucleation covers heterogeneous pathways (deposition, immersion freezing via ABIFM), homogeneous nucleation following Koop et al. (2000), and INP distributions from Frostenberg et al. (2023). Aerosol processes cover activation via Abdul-Razzak & Ghan (2000), H2SO4 and organic nucleation pathways, and a modal aerosol model using kappa-Kohler theory.

That is a specific menu. The 0-moment scheme exists because sometimes you want precipitation removed and nothing else; the P3 scheme exists because ice shape and density evolution matter in cirrus work. Choosing between them is the first decision a user makes.

How the parameterization kernels are structured

The architecture visible from the repository is a split between parameters and functions. Parameters live under CloudMicrophysics.Parameters, and the physics lives in scheme-specific modules such as Microphysics1M. The quick example in the README shows the pattern: you construct a parameter set for a hydrometeor category, then pass it into a function that computes a physical quantity.

The top-level layout reinforces this. There is src/ for the schemes, test/ for the suite, docs/ for the guides and API reference, and several directories that look like research scaffolding rather than shipped code: p3_sandbox/, parcel/, box/ and papers/. The presence of p3_sandbox/ alongside a P3 scheme in the feature list suggests the P3 implementation has an exploratory component, which is worth knowing before you treat it as settled.

The performance claims in the README are stated as design properties, not measured results. It says the code is type-stable and GPU-compatible through CUDA.jl and AMDGPU.jl, AD-compatible through ForwardDiff.jl, and optimized for minimal allocations. Type stability in Julia is what makes GPU kernels and forward-mode differentiation possible at all; without it, the compiler cannot generate the specialized code either path needs. So these three claims are really one claim, and it is the reason this package is written in Julia rather than Fortran.

The integration story follows from that. ClimaAtmos, KinematicDriver and Thermodynamics.jl are separate packages that consume these kernels. CloudMicrophysics.jl does not own the state vector, the grid, or the time integration; it owns the rate calculations.

Installing CloudMicrophysics.jl and computing a first terminal velocity

The README gives installation as two Pkg.add calls. ClimaParams is a separate package, so a working environment needs both.

using Pkg
Pkg.add("CloudMicrophysics")
Pkg.add("ClimaParams")

After that, the quick example computes rain terminal velocity. It imports the 1-moment microphysics module and the parameters module under short aliases, builds a Rain parameter set for Float64, and selects the rain branch of the bulk 1-moment velocity type.

import CloudMicrophysics.Microphysics1M as CM1
import CloudMicrophysics.Parameters as CMP

rain = CMP.Rain(Float64)
vel = CMP.Blk1MVelType(Float64).rain

With those in hand, the call takes air density and rain specific content. The README uses 1.2 kg/m3 for air density and 1e-3 kg/kg for rain specific content.

ρ = 1.2      # air density [kg/m³]
q_rai = 1e-3 # rain specific content [kg/kg]
v_term = CM1.terminal_velocity(rain, vel, ρ, q_rai)

The result is a scalar terminal velocity for the given state. Nothing here allocates a grid or advances time; this is the smallest possible demonstration that the parameter plumbing and the kernel agree.

If you want to run the test suite locally, the README gives a Julia REPL sequence rather than a shell command. You start Julia with the test project, enter package mode, dev the current directory, instantiate, then include the test runner.

julia --project=test
julia>]
pkg> dev .
pkg> instantiate
julia> include("test/runtests.jl")

The README does not document expected runtimes or hardware requirements for that suite, so treat a first run as a build-and-verify step rather than a benchmark.

Where CloudMicrophysics.jl is the wrong tool

The most important limitation is stated by omission. The README never describes how to run a simulation. There is no executable, no configuration file format, no command that produces output. If you arrive expecting a model you can point at a domain and run, you will not find one, and the documentation will not tell you that directly. You will have to infer it from the phrase "library of parameterizations" and from the integration section, which lists other packages as the things that use it.

A second constraint is the coupling to ClimaParams. Installation requires it, and the parameter sets are constructed from it. That means version drift between the two packages is a real failure mode, and the README does not document a compatibility matrix. If a parameter struct changes shape, the example above stops compiling, and the error will point at the parameter constructor rather than at anything obviously version-related.

A third issue is the API surface. The package is at v0.38.3, and the release history shows three patch releases within August 2026. A 0.x version with frequent patch releases is a signal that interfaces are still moving. The README does not promise API stability, and nothing in it describes a deprecation policy. If you are pinning this as a dependency of a long-lived model, plan to track releases.

The GPU and AD claims also come with unstated prerequisites. The README says GPU-compatible via CUDA.jl and AMDGPU.jl, but it does not document which schemes have been exercised on which backends, nor how to select a backend. Type stability is a property of the code; a working GPU path also depends on your driver, your Julia version and the extension packages, and the repository has an ext/ directory that the README does not explain.

How it differs from a Fortran microphysics package

The natural alternative for a bulk microphysics library is a long-established Fortran package, typically wrapped for use in a host model. The difference in approach is not the physics. Seifert & Beheng (2006) and Morrison & Milbrandt (2015) are published schemes, and a Fortran implementation and a Julia implementation of the same scheme should agree on the equations.

The difference is in how the code is consumed. A Fortran package is compiled once and linked; its parameterization choices are often fixed at build time or selected through namelist options. CloudMicrophysics.jl is a Julia package where the scheme is selected by which module you import and which parameter struct you construct, and where the same source can be compiled for a CPU or, per the README, for CUDA.jl and AMDGPU.jl targets without a separate code path. ForwardDiff.jl compatibility is the other divergence: a Fortran kernel is not differentiable without hand-written tangent code, and the README lists AD-compatibility as a design property of this package.

The trade-off runs the other way too. A Fortran library has a stable ABI, decades of deployment, and callers in C, Python and Fortran. CloudMicrophysics.jl has a Julia API at v0.38.3, requires ClimaParams, and its documented consumers are all other CliMA packages. If your host model is written in Fortran or C++, the interop cost is real and the README does not address it. If your host model is Julia and you want gradients or GPU execution, the calculus flips.

Licence, maintenance and the cost of tracking releases

The licence is Apache-2.0, per the README badge and the LICENSE file at the repository root. There is also a NOTICE file, which Apache-2.0 uses for attribution of bundled or derived work. If you redistribute CloudMicrophysics.jl inside a larger product, the NOTICE file is the thing to read alongside the licence text, because it may carry attribution obligations the licence body does not spell out. That is a description of what the files are, not legal advice; a lawyer should review redistribution.

On maintenance, the last push was on 2026-08-26, and v0.38.3 carries the same timestamp. The repository is not archived. The recent release cadence is high: v0.38.1 on 2026-08-07, v0.38.2 and v0.38.3 both on 2026-08-26. For a user, that cadence cuts both ways. Fixes arrive quickly, and so do changes you may need to absorb.

The upgrade cost is mostly the ClimaParams coupling plus whatever your own code does with parameter structs. The README documents no migration guide, no changelog location, and no rollback procedure. The release notes are the only record, and the README does not link to them. If you depend on this package, pinning a version and reading the diff between pins is the practical approach, because there is no documented compatibility window to rely on.

Contributions are accepted. The README points to a Developer's Guide and to AGENTS.md, which it says points to shared CliMA developer guides under docs/dev-guides/. That is a more structured contribution path than many research packages offer.

Editorial conclusion

Adopt CloudMicrophysics.jl if you are building a Julia atmospheric model, a parcel or kinematic driver, or a differentiable-physics experiment, and you want published bulk schemes with GPU kernels rather than a full model. Do not adopt it if you need a runnable forecast, a Python or Fortran interface, or a stable API you will not have to track; the README documents no compatibility guarantee. Before committing, read the Getting Started guide, check whether your ClimaParams version matches the one the package expects, and run the test suite locally with julia --project=test to confirm the kernels build on your hardware.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes