Kinematic driver: cloud formation in an idealized updraft

In atmospheric modeling, we sometimes want to isolate microphysics and thermodynamics from dynamics. Kinematic models prescribe the velocity field rather than solving momentum equations, letting us focus purely on tracer transport and phase changes.

This example demonstrates Breeze's PrescribedDynamics formulation by simulating cloud formation in an idealized updraft. A uniform vertical velocity lifts moist air through a realistic temperature profile. As air rises and cools, water vapor condenses to form clouds — a fundamental process driving all precipitation on Earth.

Physical setup

We simulate a 1D column representing a rising air parcel with:

• A realistic potential temperature profile (troposphere + stratosphere)
• Uniform upward velocity W₀ = 2 m/s (a gentle cumulus updraft)
• Moist boundary layer air entering from below

The divergence correction option compensates for the non-zero mass flux divergence ∇·(ρU) that arises when velocity doesn't vary with the reference density profile. This is essential for physically consistent tracer advection in kinematic models.

using Breeze
using CairoMakie
using Printf

Grid and reference state

We construct a 20 km tall column extending from the surface through the tropopause into the lower stratosphere. The reference state establishes the background pressure and density profile based on a hydrostatically-balanced atmosphere.

Nz = 100
Lz = 20000 # 20 km domain height
grid = RectilinearGrid(CPU(); size=Nz, x=0, y=0, z=(0, Lz),
                       topology=(Flat, Flat, Bounded))

constants = ThermodynamicConstants()
θ₀ = 300   # Surface potential temperature (K)
p₀ = 1e5   # Surface pressure (Pa)
reference_state = ReferenceState(grid, constants;
                                 surface_pressure=p₀,
                                 potential_temperature=θ₀)

ReferenceState{Float64}(p₀=100000.0, θ₀=300.0, pˢᵗ=100000.0)

Prescribing dynamics with divergence correction

The key feature of kinematic models is PrescribedDynamics, which fixes the density and pressure fields from a reference state. We enable divergence_correction=true because our constant vertical velocity doesn't satisfy the anelastic continuity constraint ∇·(ρU) = 0.

Without this correction, the tracer equation would see spurious sources/sinks from the non-zero velocity divergence. The correction adds a term c ∇·(ρU) that compensates for the prescribed velocity field's divergence.

W₀ = 2 # Vertical velocity (m/s) — a gentle updraft
dynamics = PrescribedDynamics(reference_state; divergence_correction=true)

PrescribedDynamics
├── density: PrescribedDensity
├── pressure: 1×1×100 Field{Nothing, Nothing, Oceananigans.Grids.Center} reduced over dims = (1, 2) on Oceananigans.Grids.RectilinearGrid on CPU
├── surface_pressure: 100000.0
└── standard_pressure: 100000.0

Boundary conditions

The key boundary condition is at the surface: we prescribe incoming moist air with constant potential temperature and specific humidity. This represents the boundary layer air being lifted into the updraft.

ρ₀ = surface_density(reference_state)

1.161430041883997

Surface boundary conditions for tracers

qᵗ₀ = 0.018 # Incoming specific humidity (18 g/kg) — typical tropical boundary layer
ρθ_bcs = FieldBoundaryConditions(bottom=ValueBoundaryCondition(ρ₀ * θ₀))
ρqᵗ_bcs = FieldBoundaryConditions(bottom=ValueBoundaryCondition(ρ₀ * qᵗ₀))
w_bcs = FieldBoundaryConditions(bottom=OpenBoundaryCondition(W₀), top=OpenBoundaryCondition(W₀))

Oceananigans.FieldBoundaryConditions, with boundary conditions
├── west: DefaultBoundaryCondition (FluxBoundaryCondition: Nothing)
├── east: DefaultBoundaryCondition (FluxBoundaryCondition: Nothing)
├── south: DefaultBoundaryCondition (FluxBoundaryCondition: Nothing)
├── north: DefaultBoundaryCondition (FluxBoundaryCondition: Nothing)
├── bottom: OpenBoundaryCondition{Nothing}: 2
├── top: OpenBoundaryCondition{Nothing}: 2
└── immersed: DefaultBoundaryCondition (FluxBoundaryCondition: Nothing)

Microphysics: warm-phase saturation adjustment

We use SaturationAdjustment with WarmPhaseEquilibrium, which instantaneously partitions total water between vapor and liquid based on saturation. When air becomes supersaturated, excess vapor condenses to cloud liquid, releasing latent heat. This captures the essence of cloud formation without explicit condensation timescales.

microphysics = SaturationAdjustment(equilibrium=WarmPhaseEquilibrium())

Breeze.Microphysics.SaturationAdjustment{Breeze.Thermodynamics.WarmPhaseEquilibrium, Float64}(0.001, Inf, Breeze.Thermodynamics.WarmPhaseEquilibrium())

Building the atmosphere model

We assemble all components into an AtmosphereModel. The combination of PrescribedDynamics with microphysics creates a powerful tool for understanding cloud processes in isolation from dynamics.

model = AtmosphereModel(grid; dynamics, microphysics,
                        advection = WENO(order=5),
                        boundary_conditions = (ρθ=ρθ_bcs, ρqᵗ=ρqᵗ_bcs, w=w_bcs),
                        thermodynamic_constants = constants)

AtmosphereModel{CPU, RectilinearGrid}(time = 0 seconds, iteration = 0)
├── grid: 1×1×100 RectilinearGrid{Float64, Flat, Flat, Bounded} on CPU with 0×0×3 halo
├── dynamics: PrescribedDynamics
├── formulation: LiquidIcePotentialTemperatureFormulation
├── thermodynamic_constants: ThermodynamicConstants{Float64}
├── timestepper: SSPRungeKutta3
├── advection scheme: 
│   ├── momentum: WENO{3, Float64, Float32}(order=5)
│   ├── ρθ: WENO{3, Float64, Float32}(order=5)
│   └── ρqᵗ: WENO{3, Float64, Float32}(order=5)
├── forcing: @NamedTuple{ρθ::Returns{Float64}, ρqᵗ::Returns{Float64}, ρe::Returns{Float64}}
├── tracers: ()
├── coriolis: Nothing
└── microphysics: SaturationAdjustment

Initial conditions

We initialize with a realistic tropospheric potential temperature profile that increases with height (stable stratification). Above the tropopause at 12 km, we switch to a stratospheric profile. The initial moisture decreases with height, typical of a real atmosphere.

zᵗʳ = 12000 # Tropopause height (m)
θᵗʳ = 343   # Potential temperature at tropopause (K)
Tᵗʳ = 213   # Temperature at tropopause (K)
g = constants.gravitational_acceleration
cᵖᵈ = constants.dry_air.heat_capacity

function θ_initial(z)
    θ_troposphere = θ₀ + (θᵗʳ - θ₀) * (z / zᵗʳ)^(5/4)
    θ_stratosphere = θᵗʳ * exp(g / (cᵖᵈ * Tᵗʳ) * (z - zᵗʳ))
    return ifelse(z <= zᵗʳ, θ_troposphere, θ_stratosphere)
end

θ_initial (generic function with 1 method)

Moisture profile: high in the boundary layer, decreasing with height

function qᵗ_initial(z)
    z_scale = 3000 # Scale height for moisture (m)
    return qᵗ₀ * exp(-z / z_scale)
end

set!(model; θ=θ_initial, qᵗ=qᵗ_initial, w=W₀)

Running the simulation

We run for 60 minutes, enough time for air parcels to rise several kilometers and for a quasi-steady cloud layer to develop.

simulation = Simulation(model; Δt=1, stop_time=60*60, verbose=false)

θ = model.formulation.potential_temperature
qˡ = model.microphysical_fields.qˡ
qᵛ = model.microphysical_fields.qᵛ

times = Float64[]
θ_data, qˡ_data, qᵛ_data = [], [], []

function record_profiles(sim)
    push!(times, time(sim))
    push!(θ_data, Array(interior(θ, 1, 1, :)))
    push!(qˡ_data, Array(interior(qˡ, 1, 1, :)))
    push!(qᵛ_data, Array(interior(qᵛ, 1, 1, :)))
end

add_callback!(simulation, record_profiles, TimeInterval(10*60))

function progress(sim)
    qˡ_max = maximum(qˡ)
    θ_surf = θ[1, 1, 1]
    @info @sprintf("t = %s, θ_surface = %.1f K, max(qˡ) = %.2e kg/kg",
                   prettytime(sim), θ_surf, qˡ_max)
end

add_callback!(simulation, progress, TimeInterval(10*60))

@info "Running kinematic updraft simulation with cloud microphysics..."
run!(simulation)

[ Info: Running kinematic updraft simulation with cloud microphysics...
[ Info: t = 0 seconds, θ_surface = 300.1 K, max(qˡ) = 4.35e-04 kg/kg
[ Info: t = 10 minutes, θ_surface = 299.9 K, max(qˡ) = 1.78e-03 kg/kg
[ Info: t = 20 minutes, θ_surface = 299.9 K, max(qˡ) = 4.31e-03 kg/kg
[ Info: t = 30 minutes, θ_surface = 299.9 K, max(qˡ) = 6.69e-03 kg/kg
[ Info: t = 40 minutes, θ_surface = 299.9 K, max(qˡ) = 8.93e-03 kg/kg
[ Info: t = 50 minutes, θ_surface = 299.9 K, max(qˡ) = 1.10e-02 kg/kg
[ Info: t = 1 hour, θ_surface = 299.9 K, max(qˡ) = 1.28e-02 kg/kg

Visualization

The results reveal the physics of adiabatic cloud formation. The left panel shows how potential temperature evolves — influenced by latent heat release where clouds form. The center panel shows cloud liquid mixing ratio, clearly revealing the cloud base and cloud layer. The right panel shows water vapor, which decreases sharply above the cloud base where condensation occurs.

z_km = znodes(grid, Center()) ./ 1000
fig = Figure(size=(1000, 450))

ax_θ = Axis(fig[1, 1]; xlabel="θ (K)", ylabel="z (km)",
            title="Potential temperature")
ax_qˡ = Axis(fig[1, 2]; xlabel="qˡ (g/kg)", ylabel="z (km)",
             title="Cloud liquid", yticklabelsvisible=false)
ax_qᵛ = Axis(fig[1, 3]; xlabel="qᵛ (g/kg)", ylabel="z (km)",
             title="Water vapor", yticklabelsvisible=false)

colors = cgrad(:viridis, length(times), categorical=true)

for (n, t) in enumerate(times)
    t_min = Int(t / 60)
    lines!(ax_θ, θ_data[n], z_km; color=colors[n], linewidth=2, label="t = $t_min min")
    lines!(ax_qˡ, qˡ_data[n] .* 1000, z_km; color=colors[n], linewidth=2)
    lines!(ax_qᵛ, qᵛ_data[n] .* 1000, z_km; color=colors[n], linewidth=2)
end

Add tropopause marker

for ax in [ax_θ, ax_qˡ, ax_qᵛ]
    hlines!(ax, [zᵗʳ/1000]; color=:gray, linestyle=:dash, linewidth=1.5, label="Tropopause")
end

Legend(fig[1, 4], ax_θ; framevisible=false)

Label(fig[0, :], "Kinematic updraft (W₀ = $W₀ m/s) with warm-phase saturation adjustment";
      fontsize=18, tellwidth=false)

save("kinematic_driver.png", fig)
fig

Discussion

The kinematic driver framework enables focused study of cloud microphysics by decoupling them from dynamical feedbacks. Key observations from this simulation:

1. Cloud base formation: Moist boundary layer air rises and cools adiabatically. When it reaches its Lifting Condensation Level (LCL), condensation begins and cloud liquid appears. The sharp transition in qˡ marks the cloud base.

2. Moisture partitioning: Above the cloud base, total water is partitioned between vapor (at saturation) and liquid (the excess). Water vapor decreases with height because saturation vapor pressure decreases with temperature.

3. Potential temperature: Initially, θ increases with height. As the simulation progresses, latent heat release from condensation modifies the temperature profile within the cloud layer.

4. Divergence correction: Without divergence_correction=true, the constant velocity field would create spurious tracer sources because ∇·(ρW) ≠ 0. The correction adds a compensating term to the tracer equations.

This setup is analogous to classic parcel theory experiments in cloud physics, but resolved on a grid. It's particularly useful for:

• Testing and validating microphysics schemes in isolation
• Understanding sensitivities to initial moisture and temperature
• Pedagogical demonstrations of cloud formation physics

Julia version and environment information

This example was executed with the following version of Julia:

using InteractiveUtils: versioninfo
versioninfo()

Julia Version 1.12.4
Commit 01a2eadb047 (2026-01-06 16:56 UTC)
Build Info:
  Official https://julialang.org release
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 8 × AMD EPYC 7R13 Processor
  WORD_SIZE: 64
  LLVM: libLLVM-18.1.7 (ORCJIT, znver3)
  GC: Built with stock GC
Threads: 1 default, 1 interactive, 1 GC (on 8 virtual cores)
Environment:
  JULIA_GPG = 3673DF529D9049477F76B37566E3C7DC03D6E495
  JULIA_LOAD_PATH = :@breeze
  JULIA_VERSION = 1.12.4
  JULIA_DEPOT_PATH = /usr/local/share/julia:
  JULIA_PATH = /usr/local/julia
  JULIA_PROJECT = @breeze

These were the top-level packages installed in the environment:

import Pkg
Pkg.status()

Status `/__w/Breeze.jl/Breeze.jl/docs/Project.toml`
  [86bc3604] AtmosphericProfilesLibrary v0.1.7
  [660aa2fb] Breeze v0.3.3 `.`
  [052768ef] CUDA v5.9.6
  [13f3f980] CairoMakie v0.15.8
⌅ [6a9e3e04] CloudMicrophysics v0.29.1
  [e30172f5] Documenter v1.16.1
  [daee34ce] DocumenterCitations v1.4.1
  [98b081ad] Literate v2.21.0
  [85f8d34a] NCDatasets v0.14.11
  [9e8cae18] Oceananigans v0.104.5
  [a01a1ee8] RRTMGP v0.21.7
  [b77e0a4c] InteractiveUtils v1.11.0
  [44cfe95a] Pkg v1.12.1
  [9a3f8284] Random v1.11.0
Info Packages marked with ⌅ have new versions available but compatibility constraints restrict them from upgrading. To see why use `status --outdated`

This page was generated using Literate.jl.