MicrophysicsNonEq

Non-equilibrium bulk microphysics scheme for cloud condensate formation.

Implements relaxation-to-equilibrium approach for:

• Condensation and evaporation of cloud liquid water
• Deposition and sublimation of cloud ice

See also: Microphysics1M for precipitating hydrometeor processes.

τ_relax(ice, air_properties, q_icl, ρ)
τ_relax(ice, air_properties, frostenberg, q_icl, T, ρ)
τ_relax(ice, air_properties, fit, q_icl, T, ρ)

Computes the deposition/sublimation relaxation timescale.

The first method uses the prescribed cloud-ice number concentration N_0 from CloudIce; the second derives the ice-crystal number from the Frostenberg et al. (2023) INP parameterization (see DOI: 10.5194/acp-23-10883-2023); the third uses the prescribed temperature fit N_ice(T) of ice_number_concentration.

Arguments:

• cloud microphysics and air parameters
• q_icl [kg/kg] - cloud ice specific humidity
• T [K] - air temperature (Frostenberg and temperature-fit methods only)
• ρ [kg/m³] - air density

conv_q_vap_to_q_lcl(opt::CloudLiquidFormation, mp, tps, micro, thermo)
conv_q_vap_to_q_lcl(::Nothing, mp, tps, micro, thermo)

Computes cloud liquid tendency from condensation and evaporation using the formulation from Morrison & Grabowski (2008), https://doi.org/10.1175/2007JAS2374.1, and Morrison & Milbrandt (2015), https://doi.org/10.1175/JAS-D-14-0065.1.

Arguments

• opt: CloudLiquidFormation() or nothing (disabled)
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

Returns

• Cloud condensate tendency [kg/kg/s]

conv_q_vap_to_q_icl(opt::ConstantTimescale, mp, tps, micro, thermo)
conv_q_vap_to_q_icl(opt::PrescribedIceNumber, mp, tps, micro, thermo)
conv_q_vap_to_q_icl(opt::TemperatureDependent, mp, tps, micro, thermo)
conv_q_vap_to_q_icl(opt::TemperatureDependentIceNumber, mp, tps, micro, thermo)
conv_q_vap_to_q_icl(::Nothing, mp, tps, micro, thermo)

Computes cloud ice tendency from deposition and sublimation using the formulation from Morrison & Grabowski (2008), https://doi.org/10.1175/2007JAS2374.1, and Morrison & Milbrandt (2015), https://doi.org/10.1175/JAS-D-14-0065.1.

Arguments

• opt: ConstantTimescale(), PrescribedIceNumber(), TemperatureDependent(), TemperatureDependentIceNumber(), or nothing (disabled)
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

Returns

• Cloud condensate tendency [kg/kg/s]

τ_vap_to_q_lcl(opt, mp, tps, micro, thermo)

Return the relaxation timescale τ [s] used by the matching conv_q_vap_to_q_lcl method for the given state, excluding the thermodynamic factor Γ (which is already contained in the returned tendency), or Inf when the process is disabled (opt === nothing).

Together with the tendency S this defines the equilibrium condensate q* = q + S τ toward which the phase change relaxes at rate 1/τ, so that a caller can use the time average of the exact relaxation over a step, Δq = S τ (1 - exp(-Δt/τ)) (Morrison & Milbrandt 2015, Appendix C), instead of treating S as a constant. This matters when τ is much shorter than the step, e.g. for PrescribedIceNumber with a large prescribed ice number concentration (τ of a few seconds).

Arguments

• opt: CloudLiquidFormation() or nothing
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

τ_vap_to_q_icl(opt, mp, tps, micro, thermo)

Return the relaxation timescale τ [s] used by the matching conv_q_vap_to_q_icl method for the given state, excluding the thermodynamic factor Γ, or Inf when the process is disabled (opt === nothing). For TemperatureDependent this is the sublimation timescale when the air is subsaturated over ice and the Frostenberg deposition timescale otherwise, matching the tendency. See τ_vap_to_q_lcl for how the timescale is used.

Arguments

• opt: ConstantTimescale(), PrescribedIceNumber(), TemperatureDependent(), TemperatureDependentIceNumber(), or nothing
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

ice_number_concentration(fit::IceNumberTemperatureFit, T)

Cloud ice number concentration [1/m³] prescribed as a function of temperature T [K]: N_ice(T) = min(N_ref exp(a + b ΔT), N_max) with ΔT = max(T_freeze - T, 0), i.e. the fit is held at its freezing-point value above T_freeze and capped at N_max at cold temperatures. With the default parameters (N_ref = 1000 m⁻³, a = -2.80, b = 0.262 K⁻¹, N_max = 1e7 m⁻³) this gives about 6e1 m⁻³ at 0 °C, 8e2 at -10 °C, 1e4 at -20 °C, 2e6 at -40 °C and the cap below about -46 °C.

INP_limiter(tendency, tps, T)

Returns true when ice deposition should be suppressed: positive tendency (deposition) at T > T_freeze (no INPs available).

terminal_velocity(sediment::CloudLiquid, vel::StokesRegimeVelType, ρₐ, q)
terminal_velocity(sediment::CloudIce, vel::Chen2022VelTypeSmallIce, ρₐ, q)

Computes mass-weighted average terminal velocity for cloud droplets or ice crystals assuming a monodisperse size distribution.

• Cloud Liquid: Uses Stokes Law (v ∝ D²), valid for small droplets (Re < 1).
• Cloud Ice: Uses Chen et al. (2022) parameterization, DOI: 10.1016/j.atmosres.2022.106171

Arguments

• sediment - cloud liquid or ice parameters struct (provides density and N_0)
• vel - velocity parameters (StokesRegimeVelType for liquid, Chen2022VelTypeSmallIce for ice)
• ρₐ - air density [kg/m³]
• q - cloud liquid water or ice specific content [kg/kg]

Returns

• Mass-weighted terminal velocity [m/s]

dqcld_dT(qᵥ_sat, L, Rᵥ, T)

Computes the derivative of the saturation specific humidity with respect to temperature for a given phase of water.

Arguments

• qᵥ_sat - saturation specific humidity [kg/kg]
• L - latent heat [J/kg]
• Rᵥ - gas constant for water vapor [J/kg/K]
• T - temperature [K]

gamma_helper(L, cₚ_air, dqcld_dT)

Computes the thermodynamic adjustment factor Γ.

Arguments

• L - latent heat [J/kg]
• cₚ_air - specific heat capacity of air [J/kg/K]
• dqcld_dT - derivative of saturation specific humidity with respect to temperature [kg/kg/K]

Microphysics0M

Zero-moment bulk microphysics scheme that removes cloud condensate above a threshold, equivalent to instantaneous conversion to precipitation with infinite terminal velocity.

remove_precipitation(params_0M::Parameters0M, q_lcl, q_icl)
remove_precipitation(params_0M::Parameters0M, q_lcl, q_icl, q_vap_sat)

Returns the total water tendency due to precipitation removal (kg/kg/s).

The tendency assumes relaxation with constant timescale to a state with condensate above a threshold removed. The threshold is defined by either fixed condensate specific humidity (qc_0) or fixed supersaturation (S_0), along with the relaxation timescale, specified in the Parameters0M struct.

Arguments

• params_0M: 0-moment microphysics parameters (contains τ_precip and either qc_0 or S_0)
• q_lcl: cloud liquid water specific humidity (kg/kg)
• q_icl: cloud ice specific humidity (kg/kg)
• q_vap_sat: (second method only) saturation specific humidity (kg/kg)

∂remove_precipitation_∂q_tot(params_0M::Parameters0M, q_lcl, q_icl)
∂remove_precipitation_∂q_tot(params_0M::Parameters0M, q_lcl, q_icl, q_vap_sat)

Returns the derivative of remove_precipitation with respect to q_tot.

In the 0-moment scheme q_tot is the only prognostic variable and q_lcl and q_icl are diagnosed. The derivative is −1/τ_precip whenever precipitation is actively being removed, and 0 otherwise.

Arguments

• params_0M: 0-moment microphysics parameters (contains τ_precip and either qc_0 or S_0)
• q_lcl: cloud liquid water specific humidity (kg/kg)
• q_icl: cloud ice specific humidity (kg/kg)
• q_vap_sat: (second method only) saturation specific humidity (kg/kg)

Parameters0M{FT}

Parameters for zero-moment bulk microphysics scheme

Fields

• τ_precip: precipitation timescale [s]

• qc_0: condensate specific content precipitation threshold [-]

• S_0: supersaturation precipitation threshold [-]

Microphysics0MParams{P}

Unified parameter container for 0-moment microphysics.

Fields

• precip: Precipitation removal parameters

Constructors

Microphysics0MParams(FT)
Microphysics0MParams(toml_dict::ClimaParams.ParamDict)

where

• FT::Type: A floating point type, e.g. Float32
• toml_dict::ParamDict: A ClimaParams parameter TOML dictionary (ParamDict)

make_params(td::CP.ParamDict, nm::NamedTuple)

Read the parameters of the name map nm (see name_map) from td, tag them as used by CloudMicrophysics, and return them as a NamedTuple keyed by the local names, converted to the float type of td (with Vector values converted to Tuples for GPU compatibility). The field order of the result is not the order of nm, so construct structs by keyword (T(; make_params(td, name_map(T))...)), never positionally.

name_map(::Type{T})
name_map(::Type{ParticleMass}, ::Type{Rain})    # and the other type-dispatched constructors

Return the NamedTuple (; :climaparams_name => :local_name, ...) of the ClimaParams parameters that the CP.ParamDict constructor of T reads. The local names are the struct fields, or the inputs of derived fields (e.g. the power-law exponents that enter the gamma-function factors of Blk1MVelTypeRain). For a 1-moment process option T, the map of the parameters returned by process_params_for(T(), td).

name_map_summary()

Dict(label => name_map(key)) over every registered name map (see parameter_groups); the label is the struct or option name, or e.g. Symbol("ParticleMass(Rain)") for type-dispatched constructors. Used by the documentation and by the parameter tests.

parameter_groups()

Ordered title => keys pairs listing every registered name map by documentation section. A key is a parameter struct or option type, or a (Constructor, Type) tuple for the type-dispatched constructors such as (ParticleMass, Rain).

process_field(::MicrophysicsOption)

The field of Microphysics1MOptions / mp.process_params that holds the option and its parameters.

process_params(mp, opt::MicrophysicsOption)

Return the parameters for opt from mp.process_params, checking that mp was built with an option compatible with opt.

The option argument selects the parameterization, but the shape of mp.process_params is fixed by the options mp was constructed with. This guard turns an option/parameter mismatch into an actionable ArgumentError instead of an obscure field-access failure (or a silent success when an unrelated parameter set happens to share a field name).

All checks fold away at compile time when the types are consistent; the throwing branch is @noinline so its string formatting stays out of the caller.

Microphysics1M

One-moment bulk microphysics scheme, which includes:

• terminal velocity of precipitation
• autoconversion of cloud liquid water into rain and of cloud ice into snow
• accretion due to collisions between categories of condensed species
• evaporation and sublimation of hydrometeors
• melting of snow into rain

Mathematical Approach

Particle size distributions are assumed to follow the Marshall-Palmer exponential distribution. Microphysical process rates are derived by integrating particle-scale physics (terminal velocities, collision kernels, mass transfer) over these assumed distributions.

Common argument conventions

All option-dispatched process functions share the signature process(opt, mp, tps, micro, thermo[, sd]), where:

• opt: process option type (dispatches which parameterization to use)
• mp: Microphysics1MParams — unified parameter container
• tps: thermodynamics parameters (from Thermodynamics.jl)
• micro: NamedTuple of specific humidities (kg/kg):
  • q_tot — total water specific humidity
  • q_lcl — cloud liquid water specific humidity
  • q_icl — cloud ice specific humidity
  • q_rai — rain specific humidity
  • q_sno — snow specific humidity
• thermo: NamedTuple of thermodynamic state:
  • ρ — air density (kg/m³)
  • T — temperature (K)
• sd: (optional) precomputed size-distribution and fall-speed parameters, default size_distr_parameters(mp, micro, thermo)

Not all processes use every field; each extracts only the fields it needs. When a process is disabled (option = nothing), it returns zero.

Based on:

• Kessler (1995) - https://doi.org/10.1016/0169-8095(94)00090-Z
• Grabowski (1998) - https://doi.org/10.1175/1520-0469(1998)055<3283:TCRMOL>2.0.CO;2
• Kaul et al. (2015) - https://doi.org/10.1175/MWR-D-14-00319.1

get_v0(vel::Blk1MVelTypeRain, ρ)
get_v0(vel::Blk1MVelTypeSnow, args...)

Returns the proportionality coefficient in terminal velocity(r/r0).

Guards against unphysical density ratios (ρ > ρw) that would cause sqrt of negative.

Arguments

• vel: terminal velocity parameters (contains C_drag, ρw, grav, r0, gamma_term for rain; v0, gamma_term for snow)
• ρ: air density (rain only)

get_n0(pdf::ParticlePDFSnow, q_sno, ρ)
get_n0(pdf::ParticlePDFIceRain, args...)

Returns the intercept parameter of the assumed Marshall-Palmer distribution (Marshall and Palmer, 1948).

Arguments

• pdf: size distribution parameters (contains ν, μ for snow; n0 for rain/ice)
• q_sno: snow specific content (snow only)
• ρ: air density (snow only)

lambda_inverse(pdf, mass::ParticleMass, q, ρ)

Returns the inverse of the rate parameter (λ⁻¹) of the assumed Marshall-Palmer size distribution of particles (rain drops, ice crystals, snow crystals).

The rate parameter λ is related to the mean particle size: larger λ means smaller average particles. The value is clipped at r0 * 1e-5 to prevent numerical issues.

Arguments

• pdf: size distribution parameters (ParticlePDFIceRain or ParticlePDFSnow)
• mass: mass(radius) parameters (contains r0, m0, me, Δm, χm, gamma_coeff)
• q: specific content of rain, cloud ice, or snow [kg/kg]
• ρ: air density [kg/m³]

Returns

• λ⁻¹: inverse rate parameter [m]

terminal_velocity(precip::Rain, vel::Blk1MVelTypeRain, ρ, q)
terminal_velocity(precip::Snow, vel::Blk1MVelTypeSnow, ρ, q)
terminal_velocity(precip::Rain, vel::Chen2022VelTypeRain, ρ, q)
terminal_velocity(precip::Snow, vel::Chen2022VelTypeLargeIce, ρ, q)
terminal_velocity(precip::Snow, vel::Chen2022VelTypeLargeIce, ρ, q, snow_shape)
terminal_velocity(precip, vel::Union{Blk1MVelTypeRain, Blk1MVelTypeSnow}, ρ, q, v0, λ_inv)

Returns the mass-weighted average terminal velocity assuming a Marshall-Palmer distribution of particles (Ogura and Takahashi, 1971).

The mass-weighted average velocity is computed by integrating the product of particle mass, terminal velocity, and size distribution, then dividing by the total mass. This represents the sedimentation velocity of the bulk hydrometeor field.

Fall velocity of individual particles is parameterized:

• using empirical power-law relations for Blk1MVelType
• following Chen et al. (2022), https://doi.org/10.1016/j.atmosres.2022.106171, for Chen2022VelType

Arguments

• precip: precipitation parameters (Rain or Snow, contains pdf, mass, and for snow: area, ρᵢ, aspr)
• vel: terminal velocity parameterization parameters
• ρ: air density [kg/m³]
• q: rain or snow specific content [kg/kg]
• snow_shape: (optional) assumed snow shape (Oblate or Prolate)
• v0, λ_inv: (kernel form only) precomputed fall-speed scale and inverse slope of the size distribution

Returns

• Mass-weighted terminal velocity [m/s]

Notes

• The q > ϵ_numerics presence gate returns exactly 0 for absent tracers, while the fall speed just above the gate is finite (about 0.4 m/s in Float32), so v_t is discontinuous there. The associated mass flux q v_t is below 1e-13 kg/kg m/s, so physically negligible, but treat v_t near the gate with care.

conv_q_lcl_to_q_rai(::Nothing, mp, tps, micro, thermo)
conv_q_lcl_to_q_rai(::Kessler1M, mp, tps, micro, thermo)
conv_q_lcl_to_q_rai(::PrescribedNd, mp, tps, micro, thermo)
conv_q_lcl_to_q_rai(::KK2000Autoconversion, mp, tps, micro, thermo)

Returns the rain tendency due to autoconversion of cloud liquid, dispatching on the option stored in Microphysics1MOptions.

Nothing: returns zero (autoconversion disabled).

Kessler1M: Kessler (1995) 1-moment threshold autoconversion (smooth logistic transition), https://doi.org/10.1016/0169-8095(94)00090-Z, with the threshold and the timescale given by rain_autoconversion_threshold and rain_autoconversion_timescale: each blends between a quiescent (stratiform) and a convective value with the vertical velocity thermo.w (see CMP.KesslerAcnv). With equal slow and fast values (the defaults) the rate is the classic velocity-independent Kessler rate; setting the timescales and/or the thresholds apart switches on the corresponding velocity dependence.

PrescribedNd: Variable-timescale autoconversion following Azimi (2023), using the prescribed cloud droplet number concentration.

KK2000Autoconversion: Khairoutdinov and Kogan (2000) autoconversion A_Nc q_lcl^a (ρ / ρ_ref)^c with q_lcl floored at zero (CO.KK2000_autoconversion, shared with the 2-moment scheme) and A_Nc = A (Nc / N_ref)^b evaluated once at construction from the prescribed cloud droplet number concentration Nc.

A mismatch between the option and the parameters stored in mp raises an ArgumentError.

Arguments

• opt: nothing, Kessler1M(), PrescribedNd(), or KK2000Autoconversion()
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters (unused, kept for uniform interface)
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T, w); w is the vertical velocity of the subdomain (updraft, environment, or grid mean) for which the rate is evaluated. It is required by Kessler1M and not read by PrescribedNd or KK2000Autoconversion.

Returns

• Rain autoconversion rate [kg/kg/s]

rain_autoconversion_timescale(option, mp, w = 0)

Return the effective autoconversion timescale τ in s for Kessler1M and PrescribedNd. Also a diagnostic helper for atmospheric models (e.g. ClimaAtmos). KK2000Autoconversion raises an ArgumentError: its rate is nonlinear in q_lcl, so no state-independent timescale exists.

Arguments

• option: rain autoconversion option (dispatches the variant)
• mp: Microphysics1MParams parameter container; its rain_autoconversion process parameters must belong to option, otherwise an ArgumentError is thrown
• w: vertical velocity of the subdomain in m/s; required by Kessler1M, where τ(w) = τ_slow + (τ_fast - τ_slow) w₊² / (w₊² + w_0²) with w₊ = max(w, 0), and ignored by PrescribedNd

Returns

• τ::FT: effective autoconversion timescale in s; Inf when autoconversion is disabled

rain_autoconversion_threshold(option, mp, w = 0)

Return the effective autoconversion threshold q_threshold in kg/kg for the selected RainAutoconversion variant. Also a diagnostic helper for atmospheric models (e.g. ClimaAtmos).

Arguments

• option: rain autoconversion option (dispatches the variant)
• mp: Microphysics1MParams parameter container; its rain_autoconversion process parameters must belong to option, otherwise an ArgumentError is thrown
• w: vertical velocity of the subdomain in m/s; required by Kessler1M, where q_threshold(w) = q_threshold_slow + (q_threshold_fast - q_threshold_slow) w₊² / (w₊² + w_0²) with w₊ = max(w, 0), and ignored by PrescribedNd

Returns

• q_threshold::FT: effective autoconversion threshold in kg/kg; Inf when autoconversion is disabled, 0 for PrescribedNd and KK2000Autoconversion, which convert all cloud liquid

conv_q_icl_to_q_sno(::Nothing, mp, tps, micro, thermo)
conv_q_icl_to_q_sno(opt::NoSupersaturation, mp, tps, micro, thermo)
conv_q_icl_to_q_sno(opt::WithSupersaturation, mp, tps, micro, thermo)

Returns the snow tendency due to autoconversion from cloud ice.

Nothing: returns zero (snow autoconversion disabled).

NoSupersaturation: Simplified Kessler-type threshold autoconversion, for use in simulations without supersaturation (e.g., with saturation adjustment).

WithSupersaturation: Supersaturation-dependent autoconversion following Harrington et al. (1995) and Kaul et al. (2015).

Arguments

• opt: nothing, NoSupersaturation(), or WithSupersaturation()
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

accretion(cloud, precip, vel, E, q_clo, q_pre, ρ, n0, v0, λ_inv)
accretion(cloud, precip, vel, E, q_clo, q_pre, ρ)

Returns the source of precipitating water (rain or snow) due to collisions with cloud water (liquid or ice).

Internal low-level kernel. Prefer the option-dispatched API. The 7-argument form computes n0, v0, and λ_inv from the size distribution before calling the 10-argument kernel.

Arguments

• cloud: type for cloud water or cloud ice
• precip: type for rain or snow
• vel: terminal velocity parameters
• E: collision efficiency
• q_clo: cloud liquid water or cloud ice specific content
• q_pre: rain or snow specific content
• ρ: air density
• n0, v0, λ_inv: (kernel form only) precomputed size-distribution intercept, fall-speed scale, and inverse slope

accretion_snow_rain(
    type_i, type_j, blk1mveltype_ti, blk1mveltype_tj,
    E_ij, coeff_disp, q_i, q_j, ρ,
    n0_i, n0_j, v0_i, v0_j, λ_i_inv, λ_j_inv,
)
accretion_snow_rain(
    type_i, type_j, blk1mveltype_ti, blk1mveltype_tj,
    E_ij, coeff_disp, q_i, q_j, ρ,
)

Returns the accretion rate when rain and snow collide. Collisions result in snow for T < Tfreeze and rain for T > Tfreeze. The 9-argument form computes the size-distribution and fall-speed parameters before calling the full kernel.

Uses geometric collision kernel assumption: a(ri, rj) = π(ri + rj)², with a velocity dispersion correction that assumes that fall velocity standard deviations are proportional to the mean fall velocities, with coefficient coeff_disp.

Arguments

• type_i: snow (T < Tfreeze) or rain (T > Tfreeze)
• type_j: rain (T < Tfreeze) or snow (T > Tfreeze)
• blk1mveltype_ti, blk1mveltype_tj: 1M terminal velocity parameters
• E_ij: collision efficiency
• coeff_disp: velocity dispersion coefficient
• q_i, q_j: specific contents of snow or rain [kg/kg]
• ρ: air density [kg/m³]
• n0_i, n0_j, v0_i, v0_j, λ_i_inv, λ_j_inv: (kernel form only) precomputed size-distribution intercepts, fall-speed scales, and inverse slopes for both species

conv_q_rai_to_q_vap(::Nothing, mp, tps, micro, thermo)
conv_q_rai_to_q_vap(opt::RainEvaporation, mp, tps, micro, thermo)

Returns the tendency due to rain evaporation. Ventilation factor parameterization follows Seifert and Beheng (2006).

Only evaporation is considered (sub-saturated over liquid); result is clamped ≤ 0.

Arguments

• opt: RainEvaporation() or nothing
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

conv_q_sno_to_q_vap(::Nothing, mp, tps, micro, thermo)
conv_q_sno_to_q_vap(::SublimationOnly, mp, tps, micro, thermo)
conv_q_sno_to_q_vap(::DepositionAndSublimation, mp, tps, micro, thermo)

Returns the tendency due to snow sublimation or sublimation+deposition. Ventilation factor parameterization follows Seifert and Beheng (2006).

Arguments

• opt: nothing, SublimationOnly(), or DepositionAndSublimation()
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

conv_q_icl_to_q_lcl(::Nothing, mp, tps, micro, thermo)
conv_q_icl_to_q_lcl(::CloudIceMelt, mp, tps, micro, thermo)

Returns the tendency due to cloud ice melt.

Arguments

• opt: CloudIceMelt() or nothing
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

conv_q_sno_to_q_rai(::Nothing, mp, tps, micro, thermo)
conv_q_sno_to_q_rai(::SnowMelt, mp, tps, micro, thermo)

Returns the tendency due to snow melt.

Arguments

• opt: SnowMelt() or nothing
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

conv_q_lcl_to_q_icl(::Nothing, mp, tps, micro, thermo)
conv_q_lcl_to_q_icl(::Homogeneous, mp, tps, micro, thermo)
conv_q_lcl_to_q_icl(::Heterogeneous, mp, tps, micro, thermo)
conv_q_lcl_to_q_icl(::HomogeneousAndHeterogeneous, mp, tps, micro, thermo)

Returns the tendency to cloud ice from freezing of cloud liquid.

Arguments

• opt: Homogeneous(), Heterogeneous(), HomogeneousAndHereogeneous() ornothing`
• mp: 1-moment microphysics parameters
• tps: thermodynamics parameters
• micro: microphysics state (; q_tot, q_lcl, q_icl, q_rai, q_sno)
• thermo: thermodynamic state (; ρ, T)

Homogeneous freezing: all cloud liquid freezes to ice below Thom on a short relaxation timescale τhom.

Heterogeneous freezing is based on Bigg 1953 immersion freezing: cloud liquid freezes to ice between Thom and Tfreeze. Droplet volume is based on prescribed cloud droplet number concentration.

Acnv1M{FT}

A struct with threshold autoconversion parameters (used for the snow autoconversion of cloud ice, NoSupersaturation). Rain autoconversion (Kessler1M) uses KesslerAcnv.

Fields

• τ: autoconversion timescale [s]

• q_threshold: condensate specific content autoconversion threshold [-]

• k: threshold smooth transition steepness [-]

CloudIce{FT, PD, MS}

The parameters and type for cloud ice condensate

Fields

• pdf: a struct with size distribution parameters

• mass: a struct with mass size relation parameters

• ρᵢ: cloud ice apparent density [kg/m³]

• r_eff: effective radius [m]

• N_0: assumed number concentration for cloud sedimentation [1/m³]

CloudLiquid{FT}

The parameters and type for cloud liquid water condensate

Fields

• ρw: water density [kg/m³]

• r_eff: effective radius [m]

• N_0: assumed number concentration for cloud sedimentation [1/m³]

IceNumberTemperatureFit{FT}

Parameters of the prescribed exponential temperature dependence of the cloud ice number concentration used by the TemperatureDependentIceNumber cloud ice formation option (see MicrophysicsNonEq.ice_number_concentration):

N_ice(T) = min(N_ref exp(a + b max(T_freeze - T, 0)), N_max)

Fields

• N_ref: prefactor of the fit [1/m³]

• a: intercept of the exponent [-]

• b: slope of the exponent [1/K]

• N_max: upper bound of the ice number concentration [1/m³]

• T_freeze: freezing temperature [K]

KesslerAcnv{FT}

Parameters of the 1-moment Kessler rain autoconversion. Active when Kessler1M is selected in in Microphysics1MOptions.

Fields

• τ_slow: Autoconversion timescale for quiescent (stratiform) conditions [s]

• τ_fast: Autoconversion timescale for strong vertical motions (convective) [s]

• q_threshold_slow: Autoconversion threshold for quiescent (stratiform) conditions [kg/kg]

• q_threshold_fast: Autoconversion threshold for strong vertical motions (convective) [kg/kg]

• w_0: Velocity scale of the blending [m/s]

• k: Threshold smooth transition steepness [-]

ParticleArea{FT}

A struct with coefficients of the assumed crosssectionarea(size) relationship for particles

a(r) = a0 χa (r/r0)^(ae + Δa)

Fields

• a0: cross section size relation coefficient [m²]

• ae: cross section size relation coefficient [-]

• Δa: cross section size relation coefficient [-]

• χa: cross section size relation coefficient [-]

ParticleMass{FT}

A struct with coefficients of the assumed mass(size) relationship for particles

m(r) = m0 χm (r/r0)^(me + Δm)

Fields

• r0: particle length scale [m]

• m0: mass size relation coefficient [kg]

• me: mass size relation coefficient [-]

• Δm: mass size relation coefficient [-]

• χm: mass size relation coefficient [-]

• gamma_coeff: pre-computed gamma(me + Δm + 1) for performance [-]

ParticlePDFIceRain{FT}

A struct with cloud ice or rain size distribution parameters

Fields

• n0: size distribution coefficient [1/m⁴]

ParticlePDFSnow{FT}

A struct with snow size distribution parameters

Fields

• μ: snow size distribution coefficient [1/m4]

• ν: snow size distribution coefficient [-]

Rain{PD, MS, AR, VT}

The parameters and type for rain

Fields

• pdf: a struct with size distribution parameters

• mass: a struct with mass size relation parameters

• area: a struct with cross section size relation parameters

• vent: a struct with ventilation coefficients

Snow{FT, PD, MS, AR, VT, AP}

The parameters and type for snow

Fields

• pdf: a struct with size distribution parameters

• mass: a struct with mass size relation parameters

• area: a struct with cross section size relation parameters

• vent: a struct with ventilation coefficients

• aspr: a struct with aspect ratio parameters

• ρᵢ: snow apparent density [kg/m³], used in the Chen et al. (2022) coefficients

• ρᵢ_bulk: bulk ice density [kg/m³], used in the spheroid aspect-ratio relation

• gamma_aspect_oblate: pre-computed gamma(α+4)/6 for oblate aspect ratio [-]

• gamma_aspect_prolate: pre-computed gamma(α+4)/6 for prolate aspect ratio [-]

SnowAspectRatio{FT}

A struct with aspect ratio coefficients

Fields

• ϕ: aspect ratio [-]

• κ: power law coefficient in terminal velocity parameterization from Chen et al 2022 [-]

VarTimescaleAcnv{FT}

Parameters for the variable-timescale rain autoconversion scheme used in the 1-moment microphysics scheme, following Azimi et al. (2023). Active when PrescribedNd is selected in Microphysics1MOptions.

Fields

• τ: Autoconversion timescale [s]

• α: Powerlaw coefficient relating timescale to droplet number [-]

• Nc: Prescribed cloud droplet number concentration [1/m³]

Ventilation{FT}

A struct with ventilation coefficients

Fields

• a: ventilation coefficient a [-]

• b: ventilation coefficient b [-]

prescribed_cloud_droplet_number(td)

The prescribed cloud droplet number concentration Nc [1/m³] (ClimaParams prescribed_cloud_droplet_number_concentration) used by the 1-moment rain autoconversion options PrescribedNd and KK2000Autoconversion; an ArgumentError rejects a value that is not positive.

CloudIceFormation <: MicrophysicsOption

Abstract type for cloud ice formation (deposition/sublimation) methods. See subtypes: ConstantTimescale, PrescribedIceNumber, TemperatureDependent, TemperatureDependentIceNumber.

Cloud ice melts to cloud liquid above freezing.

CloudIceRainAccretion <: MicrophysicsOption

Cloud ice + rain → snow (Marshall-Palmer kernel). The coupled rain-sink arm (rain + cloud ice → snow) is toggled automatically. Parameters (collision efficiency e) are stored in process_params.cloud_ice_rain_accretion in Microphysics1MParams.

CloudIceSnowAccretion <: MicrophysicsOption

Cloud ice + snow → snow (Marshall-Palmer kernel). Parameters (collision efficiency e) are stored in process_params.cloud_ice_snow_accretion in Microphysics1MParams.

CloudLiquidFormation <: MicrophysicsOption

Constant relaxation timescale for liquid condensation and evaporation. Parameters (τ_relax) are stored in process_params.cloud_liquid_formation in Microphysics1MParams.

CloudLiquidRainAccretion <: MicrophysicsOption

Cloud liquid + rain → rain (Marshall-Palmer kernel). Parameters (collision efficiency e) are stored in process_params.cloud_liquid_rain_accretion in Microphysics1MParams.

CloudLiquidSnowAccretion <: MicrophysicsOption

Cloud liquid + snow → snow/rain depending on temperature (includes warm-rain melt contribution). Parameters (collision efficiency e) are stored in process_params.cloud_liquid_snow_accretion in Microphysics1MParams.

ConstantTimescale <: CloudIceFormation

Constant relaxation timescale for ice deposition and sublimation. Parameters (τ_relax) are stored in process_params.cloud_ice_formation in Microphysics1MParams.

Both sublimation (S < 0) and deposition (S > 0) in the Marshall-Palmer integral.

Heterogeneous <: MicrophysicsOption

Cloud liquid freezing to cloud ice via Bigg (1953) immersion freezing for T < T_freeze, using the Reisner et al. (1998) parameterization. Droplet volume is based on prescribed cloud droplet number concentration.

Homogeneous <: MicrophysicsOption

All cloud liquid freezes to ice below the homogeneous nucleation temperature (T < T_hom ≈ 233 K) on a short relaxation timescale.

HomogeneousAndHeterogeneous <: MicrophysicsOption

Both homogeneous and heterogeneous cloud liquid freezing are active.

JointVaporRelaxation <: MicrophysicsOption

The four vapor-driven phase changes relax the shared vapor excess together, with the latent heat and vapor uptake of all of them (Morrison & Milbrandt 2015, Appendix C); the default.

KK2000Accretion <: MicrophysicsOption

Cloud liquid + rain → rain with the Khairoutdinov and Kogan (2000) accretion rate A (q_lcl q_rai)^a (ρ / ρ_ref)^b (see Common.KK2000_accretion). Parameters (an AccrKK2000, shared with the 2-moment scheme) are stored in process_params.cloud_liquid_rain_accretion in Microphysics1MParams.

KK2000Autoconversion <: RainAutoconversion

Khairoutdinov and Kogan (2000) autoconversion of cloud liquid to rain, A q_lcl^a (Nc / N_ref)^b (ρ / ρ_ref)^c (see Common.KK2000_autoconversion), with the cloud droplet number concentration Nc prescribed (ClimaParams prescribed_cloud_droplet_number_concentration, positive). Parameters (; acnv::AcnvKK2000, Nc, A_Nc), where A_Nc = A (Nc / N_ref)^b is the rate coefficient evaluated once at construction, are stored in process_params.rain_autoconversion in Microphysics1MParams.

Kessler1M <: RainAutoconversion

1-moment Kessler autoconversion of cloud liquid to rain: the smooth logistic transition of q_lcl across a threshold, divided by a timescale. The threshold and the timescale may each depend on the air vertical velocity w. Parameters (a KesslerAcnv with τ_slow, τ_fast, q_threshold_slow, q_threshold_fast, w_0, k) are stored in process_params.rain_autoconversion in Microphysics1MParams.

Microphysics1MOptions{CLF, CIF, CIM, CLFr, RA, SA, RCE, SDS, SM, CLRA, CLSA, CIRA, CISA, RSA, VRC}

Process configuration for 1-moment microphysics.

Each field selects a process variant (a concrete MicrophysicsOption subtype). Set any field to nothing to disable that process entirely. The last field, vapor_relaxation, selects how the substep solver couples the vapor-driven phase changes (JointVaporRelaxation or PerProcessVaporRelaxation).

Example

using CloudMicrophysics.Parameters as CMP

# Default options
opts = CMP.Microphysics1MOptions()

# Disable cloud ice melt and snow melt:
opts = CMP.Microphysics1MOptions(;
    cloud_ice_melt = nothing,
    snow_melt = nothing,
)

# Switch rain autoconversion to the prescribed-Nd variant:
opts = CMP.Microphysics1MOptions(; rain_autoconversion = CMP.PrescribedNd())

# Khairoutdinov and Kogan (2000) warm-rain collision rates with a prescribed droplet number:
opts = CMP.Microphysics1MOptions(;
    rain_autoconversion = CMP.KK2000Autoconversion(),
    cloud_liquid_rain_accretion = CMP.KK2000Accretion(),
)

MicrophysicsOption

Abstract type for all microphysics process options.

Option types are empty singletons that select which variant of a process runs. The parameter values a variant needs live in the process_params field of Microphysics1MParams, built by process_params_for.

NoSupersaturation <: SnowAutoconversion

Simplified autoconversion of cloud ice to snow without supersaturation dependence. Parameters (an Acnv1M with τ, q_threshold, k) are stored in process_params.snow_autoconversion in Microphysics1MParams.

PerProcessVaporRelaxation <: MicrophysicsOption

Each vapor-driven phase change relaxes on its own from the initial excess.

PrescribedIceNumber <: CloudIceFormation

Ice deposition/sublimation timescale derived from the prescribed cloud-ice number concentration N_0 in CloudIce (the same N_0 used for sedimentation). Both deposition and sublimation use the dynamically computed timescale. No additional process parameters are required.

PrescribedNd <: RainAutoconversion

Variable-timescale autoconversion using prescribed cloud droplet number Nc. Parameters (a VarTimescaleAcnv with τ, α, Nc) are stored in process_params.rain_autoconversion in Microphysics1MParams.

RainAutoconversion <: MicrophysicsOption

Abstract type for rain autoconversion methods. See subtypes: Kessler1M, PrescribedNd, KK2000Autoconversion.

Rain evaporation (sub-saturated conditions over liquid).

RainSnowAccretion <: MicrophysicsOption

Snow-rain collisions: both temperature pathways (cold: rain→snow, warm: snow→rain) plus thermal melt. Parameters (collision efficiency e, velocity dispersion coeff_disp) are stored in process_params.rain_snow_accretion in Microphysics1MParams.

SnowAutoconversion <: MicrophysicsOption

Abstract type for snow autoconversion methods. See subtypes: NoSupersaturation, WithSupersaturation.

SnowDepositionSublimation <: MicrophysicsOption

Abstract type for snow deposition/sublimation methods. See subtypes: SublimationOnly, DepositionAndSublimation.

Snow melts to rain above freezing.

Only sublimation (S < 0 over ice); deposition handled separately by non-equilibrium.

TemperatureDependent <: CloudIceFormation

INP-dependent Frostenberg (2023) timescale for deposition, with constant timescale for sublimation. Parameters (τ_relax, frostenberg) are stored in process_params.cloud_ice_formation in Microphysics1MParams.

TemperatureDependentIceNumber <: CloudIceFormation

Ice deposition/sublimation timescale derived, as for PrescribedIceNumber, from a cloud-ice number concentration and the resulting mean crystal radius, but with the number concentration a prescribed function of temperature, N_ice(T) = min(N_ref exp(a + b max(T_freeze - T, 0)), N_max), instead of the constant sedimentation number N_0. Both deposition and sublimation use the same timescale. Parameters (IceNumberTemperatureFit) are stored in process_params.cloud_ice_formation in Microphysics1MParams.

WithSupersaturation <: SnowAutoconversion

Harrington/Kaul autoconversion of cloud ice to snow with supersaturation dependence. Parameters (r_ice_snow) are stored in process_params.snow_autoconversion in Microphysics1MParams.

microphysics_1m_process_params(toml_dict, options)

Assemble the process_params container for Microphysics1MParams by mapping each field of options through process_params_for. The result mirrors the options fields one-to-one.

process_params_for(option, toml_dict)

Return the parameter data that the selected process option needs, read from toml_dict. Returns nothing for disabled processes (option === nothing) and for options that carry no parameters. The result is stored in the matching field of Microphysics1MParams.process_params and read back at call time by the process's tendency function.

CloudPhaseParams1M{LCL, ICL}

Parameters for cloud-phase (non-precipitating) hydrometeors in 1-moment scheme.

Fields

• liquid::LCL: CloudLiquid — cloud liquid water parameters
• ice::ICL: CloudIce — cloud ice parameters

Microphysics1MParams{OPT, PPR, CP, PP, AP, VL, FT}

Unified parameter container for 1-moment bulk microphysics.

processes selects which variant of each process runs. The parameter values each selected variant needs live in process_params, whose fields mirror processes one-to-one. For example, processes.rain_autoconversion = Kessler1M() picks the Kessler scheme, and its timescales, thresholds, velocity scale, and k live in process_params.rain_autoconversion. Turning a process off with nothing (e.g. processes.cloud_ice_melt = nothing) gives it a nothing slot in process_params, as does any option that needs no parameters. Shared parameters (particle size distributions, air properties, terminal velocities) are stored directly.

Fields

• processes::OPT: Microphysics1MOptions — process selection
• process_params::PPR: parameter data for each selected process, mirroring processes (nothing when a process is disabled with nothing or needs no parameters)
• cloud::CP: CloudPhaseParams1M — cloud liquid and ice parameters
• precip::PP: PrecipPhaseParams1M — rain and snow parameters
• air_properties::AP: AirProperties — air properties (diffusivities, thermal conductivity)
• terminal_velocity::VL: Blk1MVelType — terminal velocity parameters for rain and snow
• max_latent_heating_rate::FT: bound on the latent heating or cooling rate of the phase changes within a substep of the LinearizedAverage solver [K/s], from ClimaParams microphysics_max_latent_heating_rate (inf disables the limiter; must be positive)

Constructors

Microphysics1MParams(::Type{FT}; options_kwargs...)
Microphysics1MParams(toml_dict::CP.ParamDict; options_kwargs...)

Create a Microphysics1MParams from a float type or a ClimaParams TOML dictionary. Pass keyword arguments to override individual options.

Example

using CloudMicrophysics.Parameters as CMP

# Create 1M parameters with default (baseline) settings
mp = CMP.Microphysics1MParams(Float64)

# Create with temperature-dependent ice formation and cloud ice melt disabled
mp = CMP.Microphysics1MParams(Float64;
    cloud_ice_formation = CMP.TemperatureDependent(),
    cloud_ice_melt = nothing,
)

Microphysics1MParams(toml_dict::CP.ParamDict; options_kwargs...)

Create a Microphysics1MParams object from a ClimaParams TOML dictionary.

Arguments

• toml_dict: ClimaParams parameter dictionary
• options_kwargs...: Keyword arguments forwarded to Microphysics1MOptions

PrecipPhaseParams1M{RAI, SNO}

Parameters for precipitating hydrometeors in 1-moment scheme.

Fields

• rain::RAI: Rain — rain parameters
• snow::SNO: Snow — snow parameters

Double-moment bulk microphysics parametrizations including:

• autoconversion, accretion, self-collection, breakup, mean terminal velocity of raindrops, and rain evaporation rates from Seifert and Beheng 2006.
• number concentration adjustment from Horn 2012.
• additional double-moment bulk microphysics autoconversion and accretion rates from: Khairoutdinov and Kogan 2000, Beheng 1994, Tripoli and Cotton 1980, and Liu and Daum 2004.

AccrB1994

Beheng (1994) accretion parameters

Fields

• A: Accretion coefficient A

AccrKK2000

Khairoutdinov and Kogan (2000) accretion parameters of the rate A (q_lcl q_rai)^a (ρ / ρ_ref)^b (see Common.KK2000_accretion).

Fields

• A: Rate coefficient A [1/s]

• a: Exponent a of the product of cloud liquid and rain specific contents [-]

• b: Exponent b of the air density normalized by ρ_ref [-]

• ρ_ref: Reference air density ρ_ref [kg/m³]

AccrSB2006

Accretion parameters from SB2006

Fields

• kcr: Collection kernel coefficient Kcr

• τ0: Accretion correcting function coefficient τ_0

• ρ0: Reference air density [kg/m3]

• c: Accretion correcting function coefficient c

AccrTC1980

Tripoli and Cotton (1980) accretion parameters

Fields

• A: Accretion coefficient A

AcnvB1994

Beheng (1994) autoconversion parameters

Fields

• C: Autoconversion coeff C

• a: Autoconversion coeff a

• b: Autoconversion coeff b

• c: Autoconversion coeff c

• N_0: Autoconversion coeff N_0

• d_low: Autoconversion coeff d_low

• d_high: Autoconversion coeff d_high

• k: Threshold for smooth transition steepness

AcnvKK2000

Khairoutdinov and Kogan (2000) autoconversion parameters of the rate A q_lcl^a (N_d / N_ref)^b (ρ / ρ_ref)^c (see Common.KK2000_autoconversion).

Fields

• A: Rate coefficient A [1/s]

• a: Exponent a of the cloud liquid specific content [-]

• b: Exponent b of the droplet number concentration normalized by N_ref [-]

• c: Exponent c of the air density normalized by ρ_ref [-]

• N_ref: Reference cloud droplet number concentration N_ref [1/m³]

• ρ_ref: Reference air density ρ_ref [kg/m³]

AcnvSB2006

Autoconversion parameters from SB2006

Fields

• kcc: Collection kernel coefficient

• x_star: Minimum mass of rain droplets

• ρ0: Reference air density [kg/m3]

• A: Autoconversion correcting function coeff A

• a: Autoconversion correcting function coeff a

• b: Autoconversion correcting function coeff b

AcnvTC1980

Tripoli and Cotton (1980) autoconversion parameters

Fields

• a: Autoconversion coefficient a

• b: Autoconversion coefficient b

• D: Autoconversion coefficient D

• r_0: Autoconversion coefficient r_0

• me_liq: Autoconversion coefficient me_liq

• m0_liq_coeff: Autoconversion coefficient m0liqcoeff

• k: Threshold for smooth transition steepness

B1994

The type and parameter for 2-moment precipitation formation by Beheng (1994) DOI: 10.1016/0169-8095(94)90020-5

Fields

• acnv: Autoconversion parameters

• accr: Accretion parameters

BreakupSB2006

Rain breakup parameters from SB2006

Fields

• Deq: Raindrop equilibrium mean diameter

• Dr_th: Raindrop breakup mean diameter threshold

• kbr: Raindrops breakup coefficient kbr

• κbr: Raindrops breakup coefficient kappa br

CloudParticlePDF_SB2006

Cloud droplets size distribution parameters from SB2006

Fields

• νc: Cloud droplet size distribution coefficient νc

• μc: Cloud droplet size distribution coefficient μc

• xc_min: Cloud droplets minimum mass

• xc_max: Cloud droplets maximum mass (equals the SB2006 minimum raindrop mass)

• ρw: Cloud liquid water density [kg/m3]

• loggamma_z1: pre-computed loggamma((νc + 1) / μc)

• loggamma_z2: pre-computed loggamma((νc + 2) / μc)

CondEvap2M{FT}

Relaxation parameters for 2-moment vapor condensation / liquid evaporation

Fields

• τ_relax: condensation/evaporation relaxation timescale [s]

EvaporationSB2006

Rain evaporation parameters from SB2006

Fields

• av: Ventilation coefficient a

• bv: Ventilation coefficient b

• α: Rain evaporation coefficient α

• β: Rain evaporation coefficient β

• ρ0: Reference air density [kg/m3]

• a_vent_1: pre-computed av * Γ(2) / 6^(1/3) = av / cbrt(6)

• b_vent_1: pre-computed bv * Γ(5/2 + 3β/2) / 6^(β/2 + 1/2)

• a_vent_0_coeff: pre-computed av * 6^(2/3) = av * cbrt(36)

• b_vent_0_coeff: pre-computed bv / 6^(β/2 - 1/2)

• β_vent_0: pre-computed incomplete-gamma exponent for the 0th ventilation moment: -1/2 + 3β/2

KK2000

The type and parameters for 2-moment precipitation formation by Khairoutdinov and Kogan (2000)

DOI:10.1175/1520-0493(2000)128<0229:ANCPPI>2.0.CO;2

Fields

• acnv: Autoconversion parameters

• accr: Accretion parameters

LD2004

The type and parameters for 2-moment precipitation formation by Liu and Daum (2004)

DOI: 10.1175/1520-0469(2004)061<1539:POTAPI>2.0.CO;2

Fields

• R_6C_0: Autoconversion coefficient R6C0

• E_0: Autoconversion coefficient E_0

• ρ_w: liquid water density [kg/m3]

• k: Threshold for smooth transition steepness

NumberAdjustmentHorn2012

Number concentration adjustment parameter from Horn (2012, DOI: 10.5194/gmd-5-345-2012)

Fields

• τ: Number concentration adjustment timescale [s]

RainParticlePDF_SB2006

Abstract type for the size distribution parameters of rain particles

See RainParticlePDF_SB2006_limited and RainParticlePDF_SB2006_notlimited for the concrete types. These can be constructed with:

RainParticlePDF_SB2006(toml_dict; is_limited = true) # -> RainParticlePDF_SB2006_limited

RainParticlePDF_SB2006(toml_dict; is_limited = false) # -> RainParticlePDF_SB2006_notlimited

where toml_dict is a CP.ParamDict containing the parameters for the size distribution, and is_limited is a boolean indicating whether to use the limited or not limited version of the size distribution.

RainParticlePDF_SB2006_limited

Rain size distribution parameters from SB2006 including the limiters on drop maximum mass and the size distribution coefficients N0 and lambda

Fields

• νr: Raindrop size distribution coefficient νr

• μr: Raindrop size distribution coefficient μr

• xr_min: Raindrop minimal mass

• xr_max: Raindrop maximum mass

• N0_min: Raindrop size distribution coefficient N0 min

• N0_max: Raindrop size distribution coefficient N0 max

• λ_min: Raindrop size distribution coefficient lambda min

• λ_max: Raindrop size distribution coefficient lambda max

• ρw: Cloud liquid water density [kg/m3]

• ρ0: Reference air density [kg/m3]

RainParticlePDF_SB2006_notlimited

Rain size distribution parameters from SB2006 but without the limiters

Fields

• νr: Raindrop size distribution coefficient νr

• μr: Raindrop size distribution coefficient μr

• xr_min: Raindrop minimum mass

• xr_max: Raindrop maximum mass

• ρw: Cloud liquid water density [kg/m3]

• ρ0: Reference air density [kg/m3]

SB2006

The type and parameters for 2-moment precipitation formation by Seifert and Beheng (2006). The pdf_r type chooses between running with or without limiters on raindrop size distribution parameters

DOI: 10.1007/s00703-005-0112-4

Fields

• pdf_c: Cloud particle size distribution parameters

• pdf_r: Rain particle size distribution parameters

• acnv: Autoconversion parameters

• accr: Accretion parameters

• self: Rain selfcollection parameters

• brek: Rain breakup parameters

• evap: Rain evaporation parameters

• numadj: Number concentration adjustment parameter

SelfColSB2006

Rain selfcollection parameters from SB2006

Fields

• krr: Collection kernel coefficient krr

• κrr: Collection kernel coefficient kappa rr

• d: Raindrop self collection coefficient d

SubDep2M{FT}

Relaxation parameters for 2-moment vapor deposition / ice sublimation

Fields

• τ_relax: deposition/sublimation relaxation timescale [s]

TC1980

The type and parameters for 2-moment precipitation formation by Tripoli and Cotton (1980)

DOI: 10.1175/1520-0450(1980)019<1037:ANIOSF>2.0.CO;2

Fields

• acnv: Autoconversion parameters

• accr: Accretion parameters

KK2000_autoconversion_coefficient(acnv::AcnvKK2000, N_d)

Rate coefficient A (N_d / N_ref)^b of the Khairoutdinov and Kogan (2000) autoconversion rate (Common.KK2000_autoconversion). It lives with the parameters so that Microphysics1MParams can evaluate it once at construction for a prescribed N_d.

Arguments

• acnv: AcnvKK2000 parameters (A, b, N_ref)
• N_d: cloud droplet number concentration [1/m³]

Returns

• Rate coefficient [1/s]

Microphysics2MParams{WR, ICE}

Unified parameter container for 2-moment microphysics.

Supports:

• Warm rain only (SB2006): when ice is nothing
• Warm rain + P3 ice: when ice is P3IceParams

Fields

• warm_rain::WR: WarmRainParams2M — SB2006 parameters + air properties
• ice::ICE: P3IceParams or Nothing — optional P3 ice parameters

Example

using CloudMicrophysics.Parameters as CMP

# Warm rain only
mp_warm = CMP.Microphysics2MParams(Float64; with_ice = false)

# Warm rain + P3 ice
mp_p3 = CMP.Microphysics2MParams(Float64; with_ice = true)

Microphysics2MParams(toml_dict::CP.ParamDict; with_ice = false, is_limited = true,
    quadrature_order = 16, integration = Quadrature.GaussLegendre(FT, quadrature_order),
    inp_depletion_model = NIceProxyDepletion(τ_act = 300))

Create a Microphysics2MParams object from a ClimaParams TOML dictionary.

Arguments

• toml_dict: ClimaParams parameter dictionary
• with_ice: Include P3 ice-phase parameters (default: false)
• is_limited: Use limited rain size distribution parameters (default: true)
• quadrature_order: order of the default Quadrature.GaussLegendre rule passed to P3IceParams when with_ice (default: 16)
• integration: the evaluation of the size-distribution integrals passed to P3IceParams when with_ice (default: Quadrature.GaussLegendre(FT, quadrature_order))
• inp_depletion_model: the INP depletion model passed to P3IceParams when with_ice (default: NIceProxyDepletion(τ_act = 300))

P3IceParams

Parameters for P3 ice-phase processes.

Fields

• scheme: The core P3 scheme parameters

• terminal_velocity: The terminal velocity parameterization

• cloud_pdf: The cloud droplet size distribution

• rain_pdf: The rain drop size distribution

• ice_nucleation: The ice nucleation parameters (empirical INP closure)

• rain_freezing: The rain freezing parameters (Bigg-type immersion freezing)

• inp_depletion_model: Model for F23 INP-activation depletion. Currently only NIceProxyDepletion (n_ice-as-proxy form) is provided; it sets the value subtracted from INPC(T)/ρ in the F23 deposition + immersion-cap rates.

• integration: How the size-distribution integrals are evaluated, a quadrature rule such as Quadrature.GaussLegendre

Constructor

The main constructor is

P3IceParams(toml_dict::CP.ParamDict; is_limited = true, quadrature_order = 16,
    integration = Quadrature.GaussLegendre(FT, quadrature_order),
    inp_depletion_model = NIceProxyDepletion(τ_act = 300))

which constructs the parameterization with components:

• scheme = ParametersP3
• terminal_velocity = Chen2022VelType
• cloud_pdf = CloudParticlePDF_SB2006
• rain_pdf = RainParticlePDF_SB2006
• ice_nucleation = Frostenberg2023
• rain_freezing = RainFreezing

Keyword arguments

• is_limited: use limited rain size-distribution parameters (default: true)
• quadrature_order: order of the default Quadrature.GaussLegendre rule (default: 16)
• integration: how the size-distribution integrals are evaluated, a Quadrature.QuadratureRule (default: Quadrature.GaussLegendre(FT, quadrature_order)). Pass this to use a rule other than Gauss-Legendre.
• inp_depletion_model: the INP depletion model (default: NIceProxyDepletion(τ_act = 300))

WarmRainParams2M

Parameters for 2-moment warm rain processes (Seifert-Beheng 2006).

Fields

• seifert_beheng::SB: SB2006 — all warm rain parameters (autoconversion, accretion, etc.)
• air_properties::AP: AirProperties — air properties for evaporation
• condevap::CE: MM2015 cond-evap relaxation timescale
• subdep::SD: MM2015 sub-dep relaxation timescale

pdf_cloud_parameters(pdf_c, q, ρₐ, N)

Return the parameters of the size distribution of cloud particles in terms of diameter.

The size distribution is given by:

n(D) = N₀c * D^νcD * exp(-λc * D^μcD)

where

• νcD = 3νc + 2
• μcD = 3μc

Arguments

• pdf_c: Size distribution parameters for cloud droplets, CMP.CloudParticlePDF_SB2006
• q: Liquid mass content [kg/kg]
• ρₐ: Air density [kg/m³]
• N: Number concentration of the particle [1/m³]

Returns

• A NamedTuple with the fields (; logN₀c, λc, νcD, μcD): Parameters of the generalized gamma distribution in terms of diameter

pdf_rain_parameters(pdf_r, qᵣ, ρₐ, Nᵣ)

Return the parameters of the rain drop diameter distribution

n_r(D) = N_0 * exp(- D / Dr_mean)

where

• D is the diameter of the raindrop,
• N_0 [1/m⁴] is the intercept parameter of the distribution,
• Dr_mean [m] is the mean diameter of the raindrops.

Note: in SB2006, Eq. (83) the distribution is given as:

f(D) = N_0 * exp(- λ_r D)

where λ_r ≡ 1 / Dr_mean [1/m] is the inverse of the mean diameter of the raindrops.

Arguments

• pdf_r: struct containing size distribution parameters for rain. Can either be CMP.RainParticlePDF_SB2006_notlimited or CMP.RainParticlePDF_SB2006_limited. For the latter, the values for N_0, Dr_mean, and xr_mean are limited to be within provided ranges.
• qᵣ: rain water specific content [kg/kg]
• ρₐ: air density [kg/m³]
• Nᵣ: number of rain drops [1/m³]

Returns

• A NamedTuple with the fields (; N₀r, Dr_mean, xr_mean)

pdf_cloud_parameters_mass(pdf_c, q, ρₐ, N)

Return the parameters of the size distribution of cloud particles in terms of mass.

See log_pdf_cloud_parameters_mass for more details.

pdf_rain_parameters_mass(pdf_r::CMP.RainParticlePDF_SB2006, qᵣ, ρₐ, Nᵣ)

Return the parameters of the rain drop diameter distribution in terms of mass.

As a function of diameter, the size distribution is given by:

n(D) = N₀r * exp(-D / Dr_mean)

In terms of mass (x), the size distribution is given by:

f(x) = n(D(x)) * ∂D∂x(x)
     = N₀ * exp(-D(x) / Dr_mean) * (6 / (π * ρw))^(1/3) / 3 * x^(-2/3)
     = N₀ / 3 * (6 / (π * ρw))^(1/3) * x^(-2/3) * exp(- (6 / (π * ρw))^(1/3) / Dr_mean * x^(1/3))

where

• D(x) = (6x / (π * ρw))^(1/3) is the diameter of a raindrop of mass x.
• ∂D∂x(x) = (6 / (π * ρw))^(1/3) / 3 * x^(-2/3) is the derivative of the diameter with respect to the mass.

If we write the general form of the size distribution as:

f(x) = A * x^ν * exp(-B * x^μ)

then we have that:

• A = N₀ / 3 * (6 / (π * ρw))^(1/3)
• B = (6 / (π * ρw))^(1/3) / Dr_mean
• ν = -2/3
• μ = 1/3

Returns

• A NamedTuple with the fields (; Ar, Br), where Ar = A and Br = B expressed via the mean raindrop mass: Ar = Nᵣ * (6 / xr_mean)^(1/3) / 3 and Br = (6 / xr_mean)^(1/3).

log_pdf_cloud_parameters_mass(pdf_c, q, ρₐ, N)

Return the log of the parameters of the generalized gamma distribution of the form

f(x) = A * x^ν * exp(-B * x^μ),  [Eq. (79) in Seifert and Beheng 2006, but using the symbol `B` instead of `λ`]

where

B = [  x̄ Γ(z₁) / Γ(z₂) ]^(-μ)
A = μ N B^(z₁) / Γ(z₁)
z₁ = (ν + 1) / μ
z₂ = (ν + 2) / μ

That is,

log(B) = - μ [ log(x̄) + logΓ(z₁) - logΓ(z₂) ]
log(A) = log(μ) + log(N) + z₁ * log(B) - logΓ(z₁)

Arguments

• pdf_c: Size distribution parameters for cloud droplets, CMP.CloudParticlePDF_SB2006
• q: Liquid mass content [kg/kg]
• ρₐ: Air density [kg/m³]
• N: Number concentration of the particle [1/m³]

Returns

• (logA, logB): Log of the parameters of the generalized gamma distribution

size_distribution(pdf::CMP.RainParticlePDF_SB2006, q, ρₐ, N)

Return n(D), a function that computes the size distribution for rain particles at diameter D

Arguments

• pdf: Rain size distribution parameters, CMP.RainParticlePDF_SB2006
• q: Rain water specific content [kg/kg]
• ρₐ: Density of air [kg/m³]
• N: Rain water number concentration [1/m³]

size_distribution(pdf::CMP.CloudParticlePDF_SB2006, q, ρₐ, N)

Return n(D), a function that computes the size distribution for cloud particles at diameter D

The size distribution is given by:

n(D) = N₀c * D^(3νc + 2) * exp(-λc * D^(3μc))

Arguments

• pdf: Cloud size distribution parameters, CMP.CloudParticlePDF_SB2006
• q: Cloud water specific content [kg/kg]
• ρₐ: Density of air [kg/m³]
• N: Cloud water number concentration [1/m³]

size_distribution_value(pdf, q, ρₐ, N, D)

Return the size distribution value for a cloud or rain particle of diameter D.

See size_distribution for more details.

get_size_distribution_bounds(pdf, q, ρₐ, N, p = eps(eltype(q)))

Return the minimum and maximum diameters of a cloud or rain particle, set at the p-th and (1 - p)-th quantiles of the size distribution.

Arguments

• pdf: Size distribution parameters for cloud or rain, CMP.RainParticlePDF_SB2006 or CMP.CloudParticlePDF_SB2006
• q: specific content of cloud or rain water [kg/kg]
• ρₐ: density of air
• N: number concentration of cloud or rain drops [1/m³]
• p: probability level (0 ≤ p ≤ 1), default is eps(eltype(q))

Returns

• D_min, D_max: minimum and maximum diameters of a cloud or rain particle, at the p-th and (1 - p)-th quantiles of the size distribution. All inputs and output diameters are in base SI units. The bounds are calculated through quantile functions of the size distribution.

A structure containing the rates of change of the specific contents and number densities of cloud liquid water and rain water.

autoconversion(acnv, pdf_c, q_lcl, q_rai, ρ, N_lcl)

Compute autoconversion rates

Arguments

• acnv: Autoconversion parameters, CMP.AcnvSB2006
• pdf_c: Cloud size distribution parameters, CMP.CloudParticlePDF_SB2006
• q_lcl: Cloud liquid water specific content [kg/kg]
• q_rai: Rain water specific content [kg/kg]
• ρ: Air density [kg/m³]
• N_lcl: Cloud droplet number density [1/m³]

Returns

• LclRaiRates with q_lcl, N_lcl, q_rai, N_rai tendencies due to collisions between cloud droplets (autoconversion)

accretion(scheme::CMP.SB2006, q_lcl, q_rai, ρ, N_lcl)

Compute accretion rate

Arguments

• scheme: CMP.SB2006 2-moment scheme parameters (the accretion parameters CMP.AccrSB2006 are taken from its accr field)
• q_lcl: Cloud liquid water specific content [kg/kg]
• q_rai: Rain water specific content [kg/kg]
• ρ: Air density [kg/m³]
• N_lcl: Cloud droplet number density [1/m³]

Returns

• LclRaiRates with q_lcl, N_lcl, q_rai, N_rai tendencies due to collisions between raindrops and cloud droplets (accretion)

accretion(scheme::CMP.KK2000, q_lcl, q_rai, ρ)
accretion(scheme::CMP.B1994, q_lcl, q_rai, ρ)
accretion(scheme::CMP.TC1980, q_lcl, q_rai)

Compute the accretion rate of rain.

Arguments

• scheme - accretion scheme parameters (the accretion parameters are taken from its accr field):
  • Khairoutdinov and Kogan (2000) for scheme::CMP.KK2000
  • Beheng (1994) for scheme::CMP.B1994
  • Tripoli and Cotton (1980) for scheme::CMP.TC1980
• q_lcl - cloud liquid water specific content
• q_rai - rain water specific content
• ρ - air density (for CMP.KK2000 and CMP.B1994 only)

cloud_liquid_self_collection(acnv, pdf_c, q_lcl, ρ, dN_lcl_dt_au)

Compute cloud liquid self-collection rate

Arguments

• acnv: 2-moment autoconversion parameterization, CMP.AcnvSB2006
• pdf_c: Cloud size distribution parameters, CMP.CloudParticlePDF_SB2006
• q_lcl: Cloud liquid water specific content [kg/kg]
• ρ: Air density [kg/m³]
• dN_lcl_dt_au: Rate of change of cloud droplets number density due to autoconversion [1/m³/s]

Returns

• The cloud droplets number density tendency due to collisions of cloud droplets that produce larger cloud droplets (self-collection)

autoconversion_and_cloud_liquid_self_collection(scheme, q_lcl, q_rai, ρ, N_lcl)

Compute autoconversion and cloud liquid self-collection rates

Arguments

• scheme: 2-moment rain autoconversion parameterization, CMP.SB2006
• q_lcl: Cloud liquid water specific content [kg/kg]
• q_rai: Rain water specific content [kg/kg]
• ρ: Air density [kg/m³]
• N_lcl: Cloud droplet number density [1/m³]

Returns

• (au, sc): A NamedTuple containing the autoconversion rate and the cloud liquid self-collection rate.

rain_self_collection(pdf, self, q_rai, ρ, N_rai)

Compute the rain self-collection rate

Arguments

• pdf: Rain size distribution parameters, CMP.RainParticlePDF_SB2006
• self: Rain self-collection parameters, CMP.SelfColSB2006
• q_rai: Rain water specific content [kg/kg]
• ρ: Air density [kg/m³]
• N_rai: Raindrops number density [1/m³]

Returns

• The raindrops number density tendency due to collisions of raindrops that produce larger raindrops (self-collection).

rain_breakup(pdf, brek, q_rai, ρ, N_rai, dN_rai_dt_sc)

Compute the raindrops number density tendency due to breakup of raindrops

Arguments

• pdf: Rain size distribution parameters, CMP.RainParticlePDF_SB2006
• brek: Rain breakup parameters, CMP.BreakupSB2006
• q_rai: Rain water specific content
• ρ: Air density
• N_rai: Raindrops number density
• dN_rai_dt_sc: Rate of change of raindrops number density due to self-collection

The mean raindrop mass is limited to the maximum mass pdf.xr_max, as in Eq. (94) of Seifert and Beheng (2006), also for the size distribution without limiters.

Returns

• The raindrops number density tendency due to breakup of raindrops that produce smaller raindrops

rain_self_collection_and_breakup(params, q_rai, ρ, N_rai)

Compute the raindrops self-collection and breakup rates.

Arguments

• params: 2-moment rain size distribution parameters, CMP.SB2006 including raindrop size distribution, self collection, and breakup parameters
• q_rai: Rain water specific content
• ρ: Air density
• N_rai: Raindrops number density

Returns

• (sc, br): A NamedTuple containing the raindrops self-collection and breakup rates, respectively.

rain_terminal_velocity(scheme::CMP.SB2006, vel, q_rai, ρ, N_rai)

Compute the raindrops terminal velocity.

Arguments

• scheme: CMP.SB2006 2-moment scheme parameters (the rain size distribution parameters are taken from its pdf_r field)
• vel: Terminal velocity parameters, CMP.SB2006VelType or CMP.Chen2022VelTypeRain
• q_rai: Rain water specific content
• ρ: Air density
• N_rai: Raindrops number density

Returns

A tuple containing the number and mass weighted mean fall velocities of raindrops in [m/s], assuming an exponential size distribution from Seifert and Beheng 2006. The fall velocity of individual rain drops is parameterized:

• assuming an empirical relation similar to Rogers (1993) for vel::CMP.SB2006VelType,
• following Chen et. al 2022, DOI: 10.1016/j.atmosres.2022.106171 for vel::CMP.Chen2022VelTypeRain.

rain_evaporation(scheme, aps, tps, q_tot, q_lcl, q_icl, q_rai, q_sno, ρ, N_rai, T)

Compute the evaporation of raindrop number and mass.

Arguments

• scheme: precipitation formation scheme, CMP.SB2006. Notably, need the fields:
  • pdf_r: Raindrop size distribution parameters, CMP.RainParticlePDF_SB2006
  • evap: evaporation parameterization scheme, CMP.EvaporationSB2006
• aps: air properties, CMP.AirProperties
• tps: thermodynamics parameters, ThermodynamicsParameters
• q_tot, q_lcl, q_icl, q_rai, q_sno: total water, cloud liquid water, cloud ice, rain and snow specific contents, [kg kg⁻¹]
• ρ: air density [kg m⁻³]
• ρn_rai: raindrops number density [m⁻³]
• T: air temperature [K]

Returns

• A NamedTuple (; ∂ₜρn_rai, ∂ₜq_rai) with
  • ∂ₜρn_rai: tendency of raindrops number density [m⁻³ s⁻¹]
  • ∂ₜq_rai: tendency of rain water specific content [kg kg⁻¹ s⁻¹]

These are computed assuming a power law velocity relation for the fall velocity of individual drops and an exponential drop size distribution.

∂rain_evaporation_∂N_rai_∂q_rai(sb, aps, tps, q_tot, q_lcl, q_icl, q_rai, q_sno, ρ, N_rai, T)

Returns the leading-order derivatives of the rain evaporation tendencies with respect to rain specific content q_rai and rain number concentration N_rai.

Uses a donor-based leading-order approximation:

• ∂(∂ₜρnrai/ρ)/∂Nrai ≈ ∂ₜρnrai / Nrai (number tendency, first)
• ∂(∂ₜqrai)/∂qrai ≈ ∂ₜqrai / qrai (mass tendency, second)

Returns

NamedTuple with fields (; ∂N_rai, ∂q_rai).

conv_q_lcl_to_q_rai(scheme, q_lcl, ρ, N_d, smooth_transition = false)

Compute the q_rai tendency due to collisions between cloud droplets (autoconversion).

Arguments

• scheme - autoconversion scheme parameters (the autoconversion parameters are taken from its acnv field):
  • Khairoutdinov and Kogan (2000) for scheme::CMP.KK2000
  • Beheng (1994) for scheme::CMP.B1994
  • Tripoli and Cotton (1980) for scheme::CMP.TC1980
  • Liu and Daum (2004) for scheme::CMP.LD2004
• q_lcl - cloud liquid water specific content
• ρ - air density
• N_d - prescribed cloud droplet number concentration
• smooth_transition - for the CMP.B1994, CMP.TC1980 and CMP.LD2004 schemes, an optional flag that smoothes their threshold behavior if set to true. The default value is false.

number_tendency_from_mass_limits(params, q, n)

Compute the specific number tendency (rate of change) to relax the mean particle mass, x = q / n [kg], towards the physical bounds [x_min, x_max] [kg].

The relaxation tendency is given by

∂n/∂t = (n_target - n) / τ

where n_target is the specific number that corresponds to the nearest valid mean particle mass,

n_target = q / clamp(x, x_min, x_max)

Arguments

• params: Number concentration adjustment parameters, a NamedTuple with fields:
  • x_min: Minimum allowed mean particle mass [kg]
  • x_max: Maximum allowed mean particle mass [kg]
  • τ: Relaxation timescale [s]
• q: Specific mass (mass mixing ratio) [kg/kg]
• n: Specific number (number mixing ratio) [1/kg]

Returns

• The rate of change of specific number [1/(kg·s)] needed to bring the mean mass within the valid bounds.

DistributionTools

A module containing tools for working with size distributions.

Currently, it contains tools for working with the generalized gamma distribution and the exponential distribution.

Mostly used for the 2-moment microphysics.

generalized_gamma_quantile(ν, μ, B, Y)

Calculate the quantile (inverse cumulative distribution function) for a generalized gamma distribution parameterized in the form:

g(x) = A ⋅ x^ν ⋅ exp(-B ⋅ x^μ)

Arguments

• ν, μ, B: The PDF parameters
• Y: The probability level (0 ≤ Y ≤ 1) for which to compute the quantile

Returns

• x: The value x such that P(X ≤ x) = Y

generalized_gamma_cdf(ν, μ, B, x)

Calculate the cumulative distribution function (CDF) for a generalized gamma distribution parameterized in the form:

g(x) = A * x^ν * exp(-B * x^μ)

The CDF gives the probability P(X ≤ x).

Arguments

• ν, μ, B: The PDF parameters
• x: The value at which to evaluate the CDF

Returns

• p: The probability P(X ≤ x)

exponential_cdf(D_mean, D)

Calculate the cumulative distribution function (CDF) for an exponential distribution parameterized in the form:

n(D) = N₀ * exp(-D / D_mean)

where N₀ is a normalizing constant such that the total probability is 1.

Arguments

• D_mean: The mean value of the distribution
• D: The point at which to evaluate the CDF (must be ≥ 0)

Returns

• p: The probability P(X ≤ D)

exponential_quantile(D_mean, Y)

Calculate the quantile (inverse cumulative distribution function) for an exponential distribution parameterized in the form:

n(D) = N₀ * exp(-D / D_mean)

where N₀ is a normalizing constant such that the total probability is 1.

Arguments

• D_mean: The mean value of the distribution
• Y: The probability level (0 ≤ Y ≤ 1) for which to compute the quantile

Returns

• D: The value D such that P(X ≤ D) = Y

BulkMicrophysicsTendencies

Fused bulk microphysics source terms for atmospheric models.

Provides a dispatch-based API to compute all microphysics tendencies in a single function call, enabling:

• Simplified integration in atmospheric models
• Point-evaluation suitable for quadrature over subgrid-scale fluctuations
• GPU-friendly pure function design

Usage

using CloudMicrophysics.BulkMicrophysicsTendencies

# For 1-moment microphysics
tendencies = bulk_microphysics_tendencies(
    Instantaneous(), Microphysics1Moment(), mp, tps,
    ρ, T, q_tot, q_lcl, q_icl, q_rai, q_sno
)
(; dq_lcl_dt, dq_icl_dt, dq_rai_dt, dq_sno_dt) = tendencies

MicrophysicsScheme

Abstract type for microphysics scheme dispatch.

Microphysics0Moment <: MicrophysicsScheme

Singleton type for 0-moment microphysics scheme dispatch.

Microphysics1Moment <: MicrophysicsScheme

Singleton type for 1-moment microphysics scheme dispatch.

Microphysics2Moment <: MicrophysicsScheme

Singleton type for 2-moment microphysics scheme dispatch.

This unified scheme handles:

• Warm rain only (Seifert-Beheng 2006) when ice parameters are not provided
• Warm rain + P3 ice when ice state is provided

TendencyMode

Abstract type for selecting the output mode of bulk_microphysics_tendencies.

Instantaneous <: TendencyMode

Return raw nonlinear tendencies from a single evaluation of all microphysical processes (no linearization, no time-averaging).

InstantaneousVerbose <: TendencyMode

Return all individual source terms alongside aggregated dq_*_dt tendencies. Useful for model diagnostics. Only works with instantaneous (nonlinear) evaluation.

LinearizedAverage <: TendencyMode

Return time-averaged tendencies computed via repeated linearized implicit substeps. This is the mode used operationally by ClimaAtmos.

LinearizedAverageVerbose <: TendencyMode

Return the time-averaged tendencies of LinearizedAverage and the time-averaged rate of each process, with the S_* names of InstantaneousVerbose.

bulk_microphysics_tendencies(
    ::Union{Instantaneous, InstantaneousVerbose}, ::Microphysics1Moment, mp, tps,
    ρ, T, w, q_tot, q_lcl, q_icl, q_rai, q_sno,
)

Compute all 1-moment microphysics tendencies in one fused call.

This is a pure function of local thermodynamic state, suitable for:

• Point quadrature over subgrid-scale (T, q_tot) distributions
• GPU kernel evaluation
• Unit testing in isolation

Arguments

• mp: Microphysics1MParams parameter container
• tps: Thermodynamics parameters
• ρ: Air density [kg/m³]
• T: Temperature [K]
• w: air vertical velocity [m/s]
• q_tot: Total water specific content [kg/kg]
• q_lcl: Cloud liquid water specific content [kg/kg]
• q_icl: Cloud ice specific content [kg/kg]
• q_rai: Rain specific content [kg/kg]
• q_sno: Snow specific content [kg/kg]

Returns

NamedTuple with fields:

• dq_lcl_dt: Cloud liquid tendency [kg/kg/s]
• dq_icl_dt: Cloud ice tendency [kg/kg/s]
• dq_rai_dt: Rain tendency [kg/kg/s]
• dq_sno_dt: Snow tendency [kg/kg/s]
• With InstantaneousVerbose, also the rate of each process, such as S_acnv_lcl_rai [kg/kg/s], positive in the direction of the process.

Notes

• Negative specific contents are clamped to zero for robustness.
• Does NOT apply timestep-dependent limiters.

bulk_microphysics_tendencies(
    ::Union{LinearizedAverage, LinearizedAverageVerbose}, ::Microphysics1Moment, mp, tps,
    ρ, T, w, q_tot, q_lcl, q_icl, q_rai, q_sno, Δt, nsub = 1,
)

Compute average 1-moment microphysics tendencies over Δt using repeated linearized implicit substeps.

The interval Δt is divided into nsub equal substeps. At each substep, the linearized tendency is rebuilt from the current state and solved implicitly for cloud liquid, cloud ice, rain, and snow, with a vapor limiter and a latent-heating limiter (linearized_step_1m), the vapor-driven phase changes relaxed jointly unless the option vapor_relaxation = PerProcessVaporRelaxation() is selected. Temperature is then updated from the latent heating implied by the substep tendencies. Increasing nsub improves how well the method captures nonlinear changes in the active microphysical processes, including regime changes near freezing.

Returns

• NamedTuple with the net change of each species over Δt divided by Δt [kg/kg/s]: dq_lcl_dt, dq_icl_dt, dq_rai_dt and dq_sno_dt.
• With LinearizedAverageVerbose, also the average rate of each process over Δt, with the names of InstantaneousVerbose [kg/kg/s].

bulk_microphysics_tendencies(::Microphysics0Moment, mp, tps, T, q_lcl, q_icl)
bulk_microphysics_tendencies(::Microphysics0Moment, mp, tps, T, q_lcl, q_icl, q_vap_sat)

Compute 0-moment microphysics tendencies in one fused call.

Returns the total water tendency dq_tot_dt (a scalar, in kg/kg/s) from precipitation removal.

The first form uses the fixed condensate threshold qc_0; the second form uses the supersaturation threshold S_0 * q_vap_sat.

Arguments

• mp: Microphysics0MParams (contains τprecip, qc0, S_0)
• tps: Thermodynamics parameters
• T: Temperature [K]
• q_lcl: Cloud liquid specific content [kg/kg]
• q_icl: Cloud ice specific content [kg/kg]
• q_vap_sat: (second method only) Saturation specific humidity [kg/kg]

Notes

• Does NOT apply limiters (caller applies based on timestep)

bulk_microphysics_tendencies(
    ::Microphysics2Moment,
    mp::Microphysics2MParams{WR, Nothing}, tps,
    ρ, T, q_tot, q_lcl, n_lcl, q_rai, n_rai,
    q_ice = 0, n_ice = 0, q_rim = 0, b_rim = 0,
    inpc_log_shift = 0, w = 0, p = 0,
)

Compute 2-moment warm rain only microphysics tendencies (Seifert-Beheng 2006).

This method is type-stable and GPU-optimized for warm rain processes only. For warm rain + P3 ice, see the method that accepts Microphysics2MParams{WR, <:P3IceParams}.

Arguments

• mp: Microphysics2MParams with mp.ice == nothing (warm rain only)
• tps: Thermodynamics parameters
• ρ: Air density (kg/m³)
• T: Temperature (K)
• q_tot: Total water specific content (kg/kg)
• q_lcl: Cloud liquid specific content (kg/kg)
• n_lcl: Cloud droplet number per kg air (1/kg)
• q_rai: Rain specific content (kg/kg)
• n_rai: Rain number per kg air (1/kg)
• q_ice, n_ice, q_rim, b_rim: (optional, default 0) ice-state placeholders, accepted for interface uniformity and unused here
• inpc_log_shift, w, p: (optional, default 0) INP-concentration log shift, vertical velocity (m/s), and air pressure (Pa)

Returns

NamedTuple with warm rain tendency fields:

• dq_lcl_dt: Cloud liquid tendency (kg/kg/s)
• dn_lcl_dt: Cloud number tendency (1/kg/s)
• dq_rai_dt: Rain tendency (kg/kg/s)
• dn_rai_dt: Rain number tendency (1/kg/s)
• dq_ice_dt: Ice tendency (always zero for warm-only)
• dq_rim_dt: Rime mass tendency (always zero for warm-only)
• db_rim_dt: Rime volume tendency (always zero for warm-only)
• dn_lcl_activation_dt: Cloud number activation tendency (1/kg/s)

bulk_microphysics_tendencies(
    ::Microphysics2Moment,
    mp::Microphysics2MParams{WR, <:P3IceParams}, tps,
    ρ, T, q_tot, q_lcl, n_lcl, q_rai, n_rai,
    q_ice, n_ice, q_rim, b_rim,
    inpc_log_shift = 0, w = 0, p = 0,
)

Compute 2-moment warm rain + P3 ice microphysics tendencies.

This method is type-stable and GPU-optimized. The P3 ice parameters are guaranteed to be non-Nothing, eliminating runtime type checks and dynamic dispatch.

Arguments

Required

• mp: Microphysics2MParams with P3 ice parameters present
• tps: Thermodynamics parameters
• ρ: Air density (kg/m³)
• T: Temperature (K)
• q_tot: Total water specific content (kg/kg)
• q_lcl: Cloud liquid specific content (kg/kg)
• n_lcl: Cloud droplet number per kg air (1/kg)
• q_rai: Rain specific content (kg/kg)
• n_rai: Rain number per kg air (1/kg)
• q_ice: Ice specific content (kg/kg)
• n_ice: Ice number per kg air (1/kg)
• q_rim: Rime mass (kg/kg)
• b_rim: Rime volume (m³/kg)

Optional

• inpc_log_shift: Additive shift to log(INPC) (default 0)
• w: Vertical velocity (m/s), default 0
• p: Air pressure (Pa), default 0

Returns

NamedTuple with all tendency fields:

• dq_lcl_dt: Cloud liquid tendency (kg/kg/s)
• dn_lcl_dt: Cloud number tendency (1/kg/s)
• dq_rai_dt: Rain tendency (kg/kg/s)
• dn_rai_dt: Rain number tendency (1/kg/s)
• dq_ice_dt: Ice tendency (kg/kg/s)
• dn_ice_dt: Ice number tendency (1/kg/s)
• dq_rim_dt: Rime mass tendency (kg/kg/s)
• db_rim_dt: Rime volume tendency (m³/kg/s)
• dn_lcl_activation_dt: Cloud number activation tendency (1/kg/s)

Predicted particle properties scheme P3 for ice [25].

See online docs for more information.

ParametersP3

Parameters for P3 bulk microphysics scheme.

From Morrison and Milbrandt (2015) [25]

Fields

• mass: Mass-size relation, e.g. MassPowerLaw

• area: Area-size relation, e.g. AreaPowerLaw

• slope: Slope relation, e.g. SlopePowerLaw or SlopeConstant

• vent: Ventilation relation, e.g. VentilationFactor

• ρ_rim_local: Local rime density, e.g. LocalRimeDensity

• τ_wet: Wet growth time scale [s]

• D_nuc: Diameter of a newly nucleated ice crystal [m]

• m_max: Largest mean ice particle mass [kg]

• ρ_i: Cloud ice density [kg m⁻³]

• ρ_l: Cloud liquid water density [kg m⁻³]

• T_freeze: Water freeze temperature [K]

• aspect_ratio: Terminal-velocity aspect-ratio treatment, an AspectRatio

MassPowerLaw{FT}

Parameters for mass(size) relation.

From measurements of mass grown by vapor diffusion and aggregation in midlatitude cirrus by Brown and Francis (1995) [26]

A part of the ParametersP3 parameter set.

Fields

• α_va: Coefficient in mass(size) relation [kg m^(-β_va)]

• β_va: Coefficient in mass(size) relation [-]

AreaPowerLaw{FT}

Parameters for area(size) relation.

\[A(D) = γ D^σ\]

where γ and σ are coefficients in area(size) for ice side plane, column, bullet, and planar polycrystal aggregates. Values are from Mitchell (1996) [27]

A part of the ParametersP3 parameter set.

Fields

• γ: Scale [m^(2-σ)]

• σ: Power [-]

SlopeLaw

The top-level super-type for slope parameterizations.

See SlopePowerLaw and SlopeConstant for concrete implementations.

SlopePowerLaw{FT}

Slope parameter μ as a power law in shape parameter λ:

\[μ(λ) = a λ^b - c\]

and is limited to:

\[0 ≤ μ ≤ μ_{max}\]

See also Eq. 3 in Morrison and Milbrandt (2015) [25]

A part of the ParametersP3 parameter set.

Fields

• a: Scale [m^b]

• b: Power [-]

• c: Offset [-]

• μ_max: Upper limiter [-]

SlopeConstant{FT}

Slope parameter μ as a constant:

\[μ(λ) = μ_{const}\]

A part of the ParametersP3 parameter set.

Fields

• μ: Slope parameter μ [-]

VentilationFactor{FT}

Parameters for ventilation factor:

\[F(D) = a_{v} + b_{v} N_{Sc}^{1/3} N_{Re}(D)^{1/2}\]

where N_{Sc} is the Schmidt number and N_{Re}(D) is the Reynolds number for a particle with diameter D.

From Seifert and Beheng (2006) [10], see also Eq. (13-61) in Pruppacher and Klett (2010) [66]

A part of the ParametersP3 parameter set.

Fields

• aᵥ: Constant coefficient in ventilation factor [-]

• bᵥ: Linear coefficient in ventilation factor [-]

LocalRimeDensity{FT}
(ρ′_rim::LocalRimeDensity)(Rᵢ)

Local rime density parameterization of Cober and List (1993) [34], Eq. 16 and 17.

Given an instance ρ′_rim::LocalRimeDensity, obtain the local rime density for a given Rᵢ [μm m s⁻¹ °C⁻¹] by calling ρ′_rim(Rᵢ).

The parameterization is given by:

\[ρ'_{rim} = a + b R_i + c R_i^2, \quad 1 ≤ R_i ≤ 8,\]

The range is extended to R_i ≤ 12, by linearly interpolating between ρ′_rim(8) and ρ_ice = 916.7 kg/m³. The latter is the solid bulk ice density.

For calculating Rᵢ, see compute_local_rime_density.

Fields

• a: Constant coefficient

• b: Linear coefficient

• c: Quadratic coefficient

• ρ_ice: Density of solid bulk ice [kg m⁻³]

AspectRatio

Aspect-ratio treatment for the ice terminal-velocity correction.

Each subtype is a functor (particles, D) returning the multiplicative velocity factor: Oblate returns cbrt(ϕᵢ(particles, D)), NoAspectRatio returns 1. The functor methods are defined in P3Scheme, where ϕᵢ is available.

SmoothSlopePowerLaw{FT}

Slope parameter μ as a power law in slope λ, with smooth limiters.

It is identical to SlopePowerLaw but with the 0 ≤ μ ≤ μ_max limiters applied as smooth transitions of sharpness κ:

\[μ(λ) = M_{μ_{max}}\big(M_0(a λ^b - c)\big)\]

where M_0(x) = κ^{-1} \log(1 + e^{κ x}) is a smooth max(x, 0) and M_{μ_{max}}(x) = μ_{max} - κ^{-1} \log(1 + e^{κ (μ_{max} - x)}) is a smooth min(x, μ_{max}). The corner width in μ is of order 1/κ; as κ → ∞, μ(λ) converges to the hard-clamped SlopePowerLaw.

A part of the ParametersP3 parameter set.

Fields

• a: Scale [m^b]

• b: Power [-]

• c: Offset [-]

• μ_max: Upper limiter [-]

• κ: Corner sharpness [-]

P3State{FT}

State of the P3 ice in one cell.

The struct holds:

• the P3Particles particles,
• the evaluation of the size-distribution integrals, integration,
• the ice mass ρq_ice, the prognostic ice number ρn_ice, and the prognostic rime volume ρb_rim,
• the P3Distribution dist.

Construction

P3State(params, integration, ρq_ice, ρn_ice, ρq_rim, ρb_rim)

The constructor builds each part once:

1. The prognostic variables are clamped to be nonnegative.
2. The particles are built from the rime mass fraction F_rim = ρq_rim / ρq_ice and the rime density ρ_rim. For ρ_rim, the rime volume is moved to the nearest value for which ρq_rim / ρb_rim lies within rime_density_bounds, see UT.nearest_admissible_b.
3. The distribution is P3Distribution(particles, integration, ρq_ice, ρn_ice).

The field ρb_rim keeps the prognostic rime volume, not the moved one.

Arguments

• params: CMP.ParametersP3
• integration: how the size-distribution integrals are evaluated, a QuadratureRule
• ρq_ice: ice mass concentration [kg/m³]
• ρn_ice: ice number concentration [1/m³]
• ρq_rim: rime mass concentration [kg/m³]
• ρb_rim: rime volume concentration [m³/m³]

Fields

• particles: P3Particles of the ice

• integration: How the size-distribution integrals are evaluated

• ρq_ice: Volumetric ice mass concentration [kg/m³]

• ρn_ice: Volumetric prognostic ice number concentration [1/m³]

• ρb_rim: Volumetric prognostic rime volume [m³/m³]

• dist: Size distribution, a P3Distribution for a QuadratureRule integration

P3Particles{FT}

Properties of a P3 ice particle, which depend on its maximum dimension D but not on the amount of ice.

The struct holds:

• the P3 parameterizations params,
• the rime mass fraction F_rim and the rime density ρ_rim,
• the derived graupel density ρ_g,
• the size thresholds D_th, D_gr, and D_cr of the mass regimes.

Together they define the mass ice_mass, the area ice_area, and the aspect ratio ϕᵢ of a particle.

Construction

P3Particles(params, F_rim, ρ_rim)

Arguments

• params: CMP.ParametersP3
• F_rim: rime mass fraction [-]
• ρ_rim: rime density [kg/m³]

Fields

• params: CMP.ParametersP3 object

• F_rim: Rime mass fraction

• ρ_rim: Rime density [kg/m³]

• ρ_g: Graupel density [kg/m³] — NaN when F_rim = 0 (no graupel regime)

• D_th: Critical size separating spherical and nonspherical ice [m]

• D_gr: Size of equal mass for graupel and unrimed ice [m] — Inf when F_rim = 0

• D_cr: Size of equal mass for graupel and partially rimed ice [m] — Inf when F_rim = 0

P3Distribution{FT, PT}

Size distribution of the P3 ice, N′(D) = N₀ D^μ e^{-λD}.

Construction

P3Distribution(particles, integration, ρq_ice, ρn_ice)

The construction has three steps:

1. The ice number is bounded by bounded_ice_number, so the mean particle mass lies within the scheme limits.
2. The slope logλ is solved by get_distribution_logλ from the ice mass, the bounded number, and the mass relation of the particles.
3. The shape parameter μ follows from the slope law of particles.params, and the intercept logN₀ from the bounded number.

The method dispatches on the type of integration; for a QuadratureRule it returns the distribution above.

Arguments

• particles: P3Particles
• integration: how the size-distribution integrals are evaluated, a QuadratureRule
• ρq_ice: ice mass concentration [kg/m³]
• ρn_ice: ice number concentration [1/m³]

Automatic differentiation

logλ and μ are solved from the primal values and stored as primal values, so they are constant under differentiation with respect to the state; ρn and logN₀ are not.

Fields

• ρn: Volumetric ice number concentration [1/m³], with the mean particle mass bounded

• μ: Shape parameter [-], a primal value

• logλ: Log of the slope parameter [log(1/m)], a primal value

• logN₀: Log of the intercept parameter [log(1/m⁴)]

bounded_ice_number(params, ρq_ice, ρn_ice)

Return the ice number concentration [1/m³] with the mean particle mass bounded.

The bounds are ice_mean_particle_mass_min and ice_mean_particle_mass_max. Without ice mass or without ice number, the result is zero.

Arguments

• params: CMP.ParametersP3
• ρq_ice: ice mass concentration [kg/m³]
• ρn_ice: ice number concentration [1/m³]

ice_mean_particle_mass_min(params)

Return the smallest mean ice particle mass [kg].

It is the mass of a newly nucleated crystal, a solid-ice sphere of diameter D_nuc.

Arguments

• params: CMP.ParametersP3

ice_mean_particle_mass_max(params)

Return the largest mean ice particle mass [kg], params.m_max.

Arguments

• params: CMP.ParametersP3

ice_moments_are_admissible(params, ρq_ice, ρn_ice)

Return whether the ice mass [kg/m³] and number [1/m³] describe a population the scheme can represent.

Both must be positive, with the mean particle mass between ice_mean_particle_mass_min and ice_mean_particle_mass_max, the limits that bounded_ice_number applies.

Arguments

• params: CMP.ParametersP3
• ρq_ice: ice mass concentration [kg/m³]
• ρn_ice: ice number concentration [1/m³]

rime_density_bounds(params)

Return the bounds (ρ_rim_min, ρ_rim_max) [kg/m³] of the bulk rime density.

The lower bound is ρ′_rim(1), the smallest Cober and List (1993) local rime density, and the upper bound is the solid-ice density ρ_i. The P3State construction moves the rime volume so that the rime density lies between them.

Arguments

• params: CMP.ParametersP3

ice_mass(particles, D)

Return the mass of a particle with diameter D

Arguments

• particles: The P3Particles
• D: maximum particle dimension [m]

ice_density(particles, D)

Return the density of a particle with diameter D

Arguments

• particles: The P3Particles
• D: maximum particle dimension [m]

Notes:

The density of nonspherical particles is assumed to be the particle mass divided by the volume of a sphere with the same D [25].

ice_area(particles, D)

Return the cross-sectional area of a particle of maximum dimension D [m²].

The area follows the mass regime that D falls in.

Arguments

• particles: P3Particles
• D: maximum particle dimension [m]

ϕᵢ(particles, D)

Return the oblate aspect ratio of an ice particle of maximum dimension D.

The aspect ratio is ϕ = 3√π mᵢ / (4 ρ aᵢ^{3/2}) (κ = 1/3), with mass mᵢ = ice_mass(particles, D), projected area aᵢ = ice_area(particles, D), and material density ρ = ϕ_material_density(particles, D). Assumes zero liquid fraction.

Arguments

• particles: The P3Particles
• D: maximum dimension of ice particle [m]

See also ϕ_material_density and the aspect-ratio section of the P3 documentation for the spheroid derivation and the residual ϕ > 1 band above D_th.

ice_particle_terminal_velocity(velocity_params, particles, ρₐ)

Return the Chen 2022 terminal velocity v_term(D) of an ice particle of maximum dimension D.

The velocity is scaled by the aspect-ratio factor selected by particles.params.aspect_ratio.

Arguments

• velocity_params: A CMP.Chen2022VelType
• particles: A P3Particles
• ρₐ: Air density [kg/m³]

size_distribution(dist::P3Distribution)

Return n(D), the ice size distribution of the P3Distribution dist at diameter D.

integral_bounds(particles, dist; p, moment_order = 0)

Compute the integration bounds for the P3 size distribution,

Mⁿ = ∫_a^b Dⁿ * N′(D) dD = N₀ * ∫_a^b Dⁿ D^μ * exp(-λ * D) dD

where Mⁿ is the n-th moment of the size distribution. Here n ≡ moment_order and a and b are the integration bounds. For a proper moment, a=0 and b=∞. For the numerical integration, a and b are determined by this function.

Arguments

• particles: P3Particles
• dist: P3Distribution
• p: The integration bounds are set to the p-th and 1-p-th quantiles of the size distribution.
• moment_order: For integrands proportional to moments of the size distribution, moment_order can be used to indicate the order of the moment. May provide more accurate bounds; thus more accurate integration. Default: moment_order = 0.

Returns

• bnds: The integration bounds (a Tuple), for use in numerical integration (c.f. integrate).

D_m(particles, dist)

Compute the mass-weighted mean particle size [m] of a P3 size distribution.

The size is ∫ D m(D) N′(D) dD / ∫ m(D) N′(D) dD for the P3Distribution dist and the P3Particles particles, or zero without ice number.

Arguments

• particles: P3Particles
• dist: P3Distribution

ice_terminal_velocities(velocity_params, state, ρₐ; [p])

Return the number- and mass-weighted mean terminal velocities of the ice size distribution.

The velocities are

• v_n = ∫ n(D) v(D) dD / ∫ n(D) dD, the number-weighted velocity [m/s],
• v_m = ∫ n(D) m(D) v(D) dD / ∫ n(D) m(D) dD, the mass-weighted velocity [m/s].

All four integrals come from one quadrature over the size distribution, so each velocity is a weighted mean of v(D) over the quadrature nodes. Both are zero without ice number.

Arguments

• velocity_params: CMP.Chen2022VelType
• state: P3State
• ρₐ: air density [kg/m³]

Keyword arguments

• p: tolerance parameter for the integral bounds, see integral_bounds. Default is 1e-6.

Returns

• (; v_n, v_m): the number- and mass-weighted velocities [m/s]

het_ice_nucleation(aerosol, tps, q_lcl, N_lcl, RH, T, ρₐ)

Calculate the ice nucleation rate from heterogeneous freezing due to some aerosol

Arguments

• aerosol: aerosol parameters (supported types: desert dust, illite, kaolinite)
• tps: thermodynamics parameters
• q_lcl: cloud liquid water specific content
• N_lcl: cloud droplet number concentration
• RH: relative humidity
• T: temperature
• ρₐ: air density

Returns

• A NamedTuple with the fields:
  • dNdt: ice number concentration change rate [m⁻³ s⁻¹]
  • dLdt: ice content change rate [kg m⁻³ s⁻¹]

ice_melt(velocity_params, aps, tps, state, ρₐ, Tₐ)

Compute the melting rates of ice content and number concentration.

The rates are QIMLT in [25].

Arguments

• velocity_params: CMP.Chen2022VelType
• aps: CMP.AirProperties
• tps: thermodynamics parameters
• state: a P3State object
• ρₐ: air density
• Tₐ: temperature (K)

Returns

A NamedTuple (; dNdt, dLdt) with the melting rates of ice number concentration [1/m³/s] and ice content [kg/m³/s].

A particle melts by heat conduction at dm/dt = 2π D K_therm (Tₐ - T_freeze) F_v(D) / L_f, for capacitance $C = D/2$ and without the vapor diffusion contribution in subsaturated air. Mass and number melt at the same fractional rate, that of the size distribution,

\[f = \frac{∫ \frac{dm}{dt} N'(D) \, dD}{∫ m(D) N'(D) \, dD}, \qquad \frac{dL}{dt} = L f, \qquad \frac{dN}{dt} = N f,\]

with N the prognostic ice number.

bulk_liquid_ice_collision_sources(
    psd_c, psd_r, aps, tps, vel, state,
    L_c, N_c, L_r, N_r, ρₐ, T,
)

Computes the bulk rates for ice and liquid particle collisions.

Arguments

• psd_c: a CMP.CloudParticlePDF_SB2006
• psd_r: a CMP.RainParticlePDF_SB2006
• aps: CMP.AirProperties
• tps: thermodynamics parameters
• vel: the velocity parameterization, e.g. CMP.Chen2022VelType
• state: P3State
• L_c: cloud liquid water content [kg/m³]
• N_c: cloud liquid water number concentration [1/m³]
• L_r: rain water content [kg/m³]
• N_r: rain number concentration [1/m³]
• ρₐ: air density [kg/m³]
• T: temperature [K]

Returns

A NamedTuple of (; ∂ₜq_c, ∂ₜq_r, ∂ₜN_c, ∂ₜN_r, ∂ₜL_rim, ∂ₜL_ice, ∂ₜB_rim), where:

1. ∂ₜq_c: cloud liquid water content tendency [kg/kg/s]
2. ∂ₜq_r: rain water content tendency [kg/kg/s]
3. ∂ₜN_c: cloud number concentration tendency [1/m³/s]
4. ∂ₜN_r: rain number concentration tendency [1/m³/s]
5. ∂ₜL_rim: riming mass tendency [kg/m³/s]
6. ∂ₜL_ice: ice water content tendency [kg/m³/s]
7. ∂ₜB_rim: rime volume tendency [m³/m³/s]

ice_self_collection(vel, state, ρₐ)

Compute the ice self-collection (aggregation) rate.

Self-collection decreases the ice number concentration and leaves mass, rime mass, and rime volume unchanged.

Arguments

• vel: the velocity parameterization, e.g. CMP.Chen2022VelType
• state: P3State
• ρₐ: air density [kg/m³]

Returns

A NamedTuple of (; dNdt), where:

1. dNdt: ice number concentration tendency due to self-collection [1/m³/s] (always positive or zero, represents a loss rate), the fractional rate of the size distribution times the prognostic ice number

Quadrature

Numerical quadrature rules for the P3 size-distribution integrals.

Two rules are provided, both plugging into the same integrate machinery:

• ChebyshevGauss: Chebyshev-Gauss of the first kind. Nodes/weights have a closed form, so the rule is cheap to build for any order and carries only n::Int.
• GaussLegendre: Gauss-Legendre. Nodes/weights have no closed form; they are computed once at construction (host side, O(n) via FastGaussQuadrature) and stored in the rule as SVectors. The rule is isbits and ships to GPU kernels unchanged — only construction is host-side.

This module lives early in the include order (before Parameters) so that the constructed quadrature object can be stored on a parameter struct and shipped to the device, rather than being rebuilt inside a GPU kernel.

ChebyshevGauss(n)
ChebyshevGauss(FT, n)

Quadrature scheme for Chebyshev-Gauss quadrature of the first kind.

Arguments

• FT: float type of the nodes and weights; default Float64
• n: Number of quadrature points

Available methods

node(::ChebyshevGauss, i)
weight(::ChebyshevGauss, i)
inv_weight_fun(::ChebyshevGauss, y)

• node(quad, i): Return the i-th node of the Chebyshev-Gauss quadrature scheme.
• weight(quad, i): Return the i-th weight of the Chebyshev-Gauss quadrature scheme.
• inv_weight_fun(quad, y): Return the inverse of the weight function w(x).

Mathematical Background

A method to approximate the value of integrals of the kind

∫_{-1}^{1} f(x) w(x) dx ≈ ∑_1^n f(x_i) wᵢ(x_i)

where w(x) = 1 / √(1 - x^2) is the weight function, x_i are the nodes, and wᵢ are the weights.

If we are interested in only the integral of f(x), we can instead integrate g(x) = f(x) / w(x),

∫_{-1}^{1} g(x) w(x) dx ≈ ∑_1^n g(x_i) wᵢ(x_i) = ∑_1^n f(x_i) wᵢ(x_i) / w(x_i)

References

• https://en.wikipedia.org/wiki/Chebyshev–Gauss_quadrature
• https://en.wikipedia.org/wiki/Gaussian_quadrature

GaussLegendre(n)
GaussLegendre(FT, n)

Quadrature scheme for Gauss-Legendre quadrature, plugging into the same integrate machinery as ChebyshevGauss.

Unlike ChebyshevGauss (whose nodes/weights have a closed form), the Gauss-Legendre nodes/weights have no closed form. They are computed once, at construction, in Float64 via FastGaussQuadrature.gausslegendre (an O(n) host-side routine) and converted to FT. The constructed rule stores the nodes/weights as SVector{N, FT}, so per-integrate access is a static lookup — identical hot-path cost to ChebyshevGauss. Construction is intended to run once at initialization (e.g. when building a parameter struct), never inside a GPU kernel.

Arbitrary orders n ≥ 1 are supported (the order is the type parameter N).

GPU / type-stability

GaussLegendre{FT, N} stores SVector{N, FT} nodes/weights, so it is isbits (GPU-safe) and fully concrete. The order N is a type parameter, fixed at construction; the object is built host-side once and shipped to the device, so N never ripples a runtime value into a kernel.

Accuracy vs ChebyshevGauss

At matched n, Gauss-Legendre is more accurate on the smooth P3 size-distribution integrals (e.g. ~20× lower error than ChebyshevGauss(40) on the dominant ice-rain collision integral, verified against an adaptive QuadGK reference) at equal cost, and it is the default rule on the P3 parameters. ice_self_collection places the diagonal D_1 = D_2 on a subinterval boundary, so its integrand is smooth on each subinterval and Gauss-Legendre converges geometrically there too.

Available methods

node(::GaussLegendre, i)
weight(::GaussLegendre, i)
inv_weight_fun(::GaussLegendre, y)   # ≡ 1 (Legendre weight is 1 on [-1, 1])

References

• https://en.wikipedia.org/wiki/Gauss–Legendre_quadrature
• A. Townsend, FastGaussQuadrature.jl (MIT); Bogaert (2014) O(n) nodes/weights.

AerosolModel

A container for information on aerosol size distribution and chemical properties.

The size distribution is a sum of lognormal internally mixed modes. The chemical composition can be expressed using kappa parameter or hygroscopicity parameter B.

Mode_B

Represents the sizes and chemical composition of aerosol particles in one size distribution mode. The mode is assumed to be made up of internally mixed components and follow a lognormal size distribution. The chemical composition of aerosol particles in this mode is described using the parameters from Abdul-Razzak and Ghan 2000.

Mode_κ

Represents the sizes and chemical composition of aerosol particles in one size distribution mode. The mode is assumed to be made up of internally mixed components and follow a lognormal size distribution. The chemical composition of aerosol particles in this mode is described using the parameters from Petters and Kreidenweis 2007.

AerosolDistribution

Represents the aerosol size distribution as a tuple with different modes. All modes have to either be of type ModeB (Abdul-Razzak and Ghan 2000) or of type Modeκ (Petters and Kreidenweis 2007).

Constructors

AerosolDistribution(modes::T)
AerosolDistribution(modes::Union{Mode_κ, Mode_B}...)

ArizonaTestDust{FT}

Parameters for Arizona Test Dust from Mohler et al, 2006. DOI: 10.5194/acp-6-3007-2006

Fields

• S₀_warm: S₀ for T > T_thr [-]

• S₀_cold: S₀ for T < T_thr [-]

• a_warm: a for T > T_thr [-]

• a_cold: a for T < T_thr [-]

• deposition_m: m coefficient for deposition nucleation J [-]

• deposition_c: c coefficient for deposition nucleation J [-]

• ABIFM_m: m coefficient for immersion freezing J [-]

• ABIFM_c: c coefficient for immersion freezing J [-]

AsianDust{FT}

Parameters for Asian Dust

Fields

• deposition_m: m coefficient for deposition nucleation J [-]

• deposition_c: c coefficient for deposition nucleation J [-]

• ABIFM_m: m coefficient for immersion freezing J [-]

• ABIFM_c: c coefficient for immersion freezing J [-]

DesertDust{FT}

Parameters for desert dust from Knopf and Alpert 2013 DOI: 10.1039/C3FD00035D and from Mohler et al, 2006 DOI: 10.5194/acp-6-3007-2006

Fields

• S₀_warm: S₀ for T > T_thr [-]

• S₀_cold: S₀ for T < T_thr [-]

• a_warm: a for T > T_thr [-]

• a_cold: a for T < T_thr [-]

• ABIFM_m: m coefficient for immersion freezing J [-]

• ABIFM_c: c coefficient for immersion freezing J [-]

Dust{FT}

Parameters for generic dust.

Fields

• deposition_m: m coefficient for deposition nucleation J [-]

• deposition_c: c coefficient for deposition nucleation J [-]

• ABIFM_m: m coefficient for immersion freezing J [-]

• ABIFM_c: c coefficient for immersion freezing J [-]

Feldspar{FT}

Parameters for Feldspar from Alpert et al 2022 DOI: 10.1039/D1EA00077B

Fields

• deposition_m: m coefficient for deposition nucleation J [-]

• deposition_c: c coefficient for deposition nucleation J [-]

Ferrihydrite{FT}

Parameters for Ferrihydrite from Alpert et al 2022 DOI: 10.1039/D1EA00077B

Fields

• deposition_m: m coefficient for deposition nucleation J [-]

• deposition_c: c coefficient for deposition nucleation J [-]

Illite{FT}

Parameters for illite from Knopf and Alpert 2013 DOI: 10.1039/C3FD00035D

Fields

• deposition_m: m coefficient for deposition nucleation J [-]

• deposition_c: c coefficient for deposition nucleation J [-]

• ABIFM_m: m coefficient for immersion freezing J [-]

• ABIFM_c: c coefficient for immersion freezing J [-]

Kaolinite{FT}

Parameters for kaolinite from Knopf and Alpert 2013 DOI: 10.1039/C3FD00035D and China et al 2017 DOI: 10.1002/2016JD025817

Fields

• deposition_m: m coefficient for deposition nucleation J [-]

• deposition_c: c coefficient for deposition nucleation J [-]

• ABIFM_m: m coefficient for immersion freezing J [-]

• ABIFM_c: c coefficient for immersion freezing J [-]

MiddleEasternDust{FT}

Parameters for Middle Eastern Dust

Fields

• ABIFM_m: m coefficient for immersion freezing J [-]

• ABIFM_c: c coefficient for immersion freezing J [-]

SaharanDust{FT}

Parameters for Saharan Dust

Fields

• deposition_m: m coefficient for deposition nucleation J [-]

• deposition_c: c coefficient for deposition nucleation J [-]

Seasalt{FT}

Parameters for seasalt

Fields

• M: molar mass [kg/mol]

• ρ: density [kg/m3]

• ϕ: osmotic coefficient [-]

• ν: ion number [-]

• ϵ: water soluble mass fraction [-]

• κ: hygroscopicity parameter [-]

Sulfate{FT}

Parameters for sulfate aerosol

Fields

• M: molar mass [kg/mol]

• ρ: density [kg/m3]

• ϕ: osmotic coefficient [-]

• ν: ion number [-]

• ϵ: water soluble mass fraction [-]

• κ: hygroscopicity parameter [-]

H2SO4SolutionParameters{FT}

Parameters for water activity of H2SO4 solutions from Luo et al 1995. DOI: 10.1029/94GL02988

Fields

• T_max: max temperature for which the parameterization is valid [K]

• T_min: min temperature for which the parameterization is valid [K]

• w_2: coefficient [-]

• c1: coefficient [-]

• c2: coefficient [-]

• c3: coefficient [-]

• c4: coefficient [-]

• c5: coefficient [-]

• c6: coefficient [-]

• c7: coefficient [-]

AerosolActivation

Aerosol activation scheme, which includes:

• mean hygroscopicity for each mode of the aerosol size distribution
• critical supersaturation for each mode of the aerosol size distribution
• maximum supersaturation
• total number of particles activated
• total mass of particles activated

mean_hygroscopicity_parameter(ap, ad)

• ap - a struct with aerosol activation parameters
• ad - a struct with aerosol distribution (B or κ based)

Returns a tuple of hygroscopicity parameters (one tuple element for each aerosol size distribution mode). The tuple is computed either as mass-weighted B parameters (Abdul-Razzak and Ghan 2000) or volume weighted kappa parameters (Petters and Kreidenweis 2007). Implemented via a dispatch based on aerosol distribution mode type.

max_supersaturation(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice, N_liq, N_ice)
max_supersaturation(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice)

• ap - a struct with aerosol activation parameters
• ad - a struct with aerosol distribution
• aip - a struct with air parameters
• tps - a struct with thermodynamics parameters
• T - air temperature
• p - air pressure
• w - vertical velocity
• q_tot - total water specific content
• q_liq - liquid water specific content
• q_ice - ice water specific content
• N_liq - liquid water number concentration
• N_ice - ice water number concentration

Returns the maximum supersaturation.

N_activated_per_mode(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice, N_liq, N_ice)
N_activated_per_mode(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice)

• ap - a struct with aerosol activation parameters
• ad - aerosol distribution struct
• aip - a struct with air parameters
• tps - a struct with thermodynamics parameters
• T - air temperature
• p - air pressure
• w - vertical velocity
• q_tot - total water specific content
• q_liq - liquid water specific content
• q_ice - ice water specific content
• N_liq - liquid water number concentration
• N_ice - ice water number concentration

Returns the number of activated aerosol particles in each aerosol size distribution mode.

M_activated_per_mode(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice, N_liq, N_ice)
M_activated_per_mode(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice)

• ap - a struct with aerosol activation parameters
• ad - a struct with aerosol distribution parameters
• aip - a struct with air parameters
• tps - a struct with thermodynamics parameters
• T - air temperature
• p - air pressure
• w - vertical velocity
• q_tot - total water specific content
• q_liq - liquid water specific content
• q_ice - ice water specific content
• N_liq - liquid water number concentration
• N_ice - ice water number concentration

Returns the mass of activated aerosol particles per mode of the aerosol size distribution.

total_N_activated(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice, N_liq, N_ice)
total_N_activated(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice)

• ap - a struct with aerosol activation parameters
• ad - aerosol distribution struct
• aip - a struct with air properties
• tps - a struct with thermodynamics parameters
• T - air temperature
• p - air pressure
• w - vertical velocity
• q_tot - total water specific content
• q_liq - liquid water specific content
• q_ice - ice water specific content
• N_liq - liquid water number concentration
• N_ice - ice water number concentration

Returns the total number of activated aerosol particles.

total_M_activated(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice, N_liq, N_ice)
total_M_activated(ap, ad, aip, tps, T, p, w, q_tot, q_liq, q_ice)

• ap - a struct with aerosol activation parameters
• ad - aerosol distribution struct
• aip - a struct with air properties
• tps - a struct with thermodynamics parameters
• T - air temperature
• p - air pressure
• w - vertical velocity
• q_tot - total water specific content
• q_liq - liquid water specific content
• q_ice - ice water specific content
• N_liq - liquid water number concentration
• N_ice - ice water number concentration

Returns the total mass of activated aerosol particles.

AerosolActivationParameters{FT}

Parameters for Abdul-Razzak and Ghan 2000 aerosol activation scheme DOI: 10.1029/1999JD901161

Fields

• M_w: molar mass of water [kg/mol]

• R: gas constant [J/mol/K]

• ρ_w: cloud water density [kg/m3]

• ρ_i: cloud ice density [kg/m3]

• σ: surface tension of water [N/m]

• g: gravitational acceleration [m/s2]

• f1: scaling coefficient in Abdul-Razzak and Ghan 2000 [-]

• f2: scaling coefficient in Abdul-Razzak and Ghan 2000 [-]

• g1: scaling coefficient in Abdul-Razzak and Ghan 2000 [-]

• g2: scaling coefficient in Abdul-Razzak and Ghan 2000 [-]

• p1: power of (zeta / eta) in Abdul-Razzak and Ghan 2000 [-]

• p2: power of (S_m^2 / (zeta + 3 * eta)) in Abdul-Razzak and Ghan 2000 [-]

H2S04NucleationParameters{FT}

Parameters for pure sulfuric acid nucleation from Dunne et al 2016 DOI:10.1126/science.aaf2649

Fields

• p_b_n

• p_b_i

• u_b_n

• u_b_i

• v_b_n

• v_b_i

• w_b_n

• w_b_i

• p_t_n

• p_t_i

• u_t_n

• u_t_i

• v_t_n

• v_t_i

• w_t_n

• w_t_i

• p_A_n

• p_A_i

• a_n

• a_i

MixedNucleationParameters{FT}

Parameters for mixed organic and sulfuric acid nucleation from Riccobono et al 2014 DOI:10.1126/science.1243527

Fields

• k_H2SO4org

• k_MTOH

• exp_MTOH

OrganicNucleationParameters{FT}

Parameters for pure organic nucleation from Kirkby 2016 DOI: 10.1038/nature17953

Fields

• a_1

• a_2

• a_3

• a_4

• a_5

• Y_MTO3

• Y_MTOH

• k_MTO3

• k_MTOH

• exp_MTO3

• exp_MTOH

Call artifacts from Artifacts.toml

AIDA_ice_nucleation(data_file_name)

• data_file_name - name of the data file on Caltech box.

Returns the filepath of the data file in Caltech box.

Parameterization for heterogenous cloud ice nucleation.

dust_activated_number_fraction(dust, ip, Si, T)

Calculate the number fraction of mineral dust particles acting as deposition nuclei,

n ice nuclei / n dust particles

Arguments

• dust: a struct with dust parameters
• ip: a struct with cloud ice nucleation parameters
• Si: ice saturation ratio
• T: air temperature [K]

From [47] Table 2 (averages from different measurements excluding those where a was not measured), see doi.org/10.5194/acp-6-3007-2006

MohlerDepositionRate(dust, ip, Si, T, dSi_dt, N_aer)

Calculate the cloud ice nucleation rate from deposition.

Arguments

• dust: a struct with dust parameters
• ip: a struct with cloud ice nucleation parameters
• Si: ice saturation
• T: ambient temperature
• dSi_dt: change in ice saturation over time
• N_aer: number of unactivated aerosols

See [47] Equation 5; doi.org/10.5194/acp-6-3007-2006

deposition_J(dust, Δa_w)

Calculate the deposition nucleation rate coefficient, J [m⁻² s⁻¹], for water vapor deposition onto different dust and mineral aerosol types.

Arguments

• dust: a struct with dust parameters (supported types: feldspar, ferrihydrite, kaolinite, illite, Arizona Test Dust, Saharan dust, Asian dust, and generic dust)
• Δa_w: change in water activity [unitless].

Returns

• J [m⁻² s⁻¹]; zero for unsupported aerosol types.

See [48] for details on the parameterization.

ABIFM_J(dust, Δa_w)

Compute the heterogeneous ice nucleation rate coefficient, J [m⁻² s⁻¹] for the given dust type and solution water activity, Δa_w, using the "a_w based immersion freezing model" (ABIFM)

Arguments

• dust: The given mineral in liquid solution; currently supports:
  • DesertDust, Illite, Kaolinite, Dust, ArizonaTestDust, MiddleEasternDust, AsianDust
  • all other AerosolTypes are not supported and will return zero
• Δa_w: change in water activity [unitless].

Returns

• J: heterogeneous ice nucleation rate coefficient [m⁻² s⁻¹]

The free parameters m and c are taken from Knopf & Alpert 2013 see: doi.org/10.1039/C3FD00035D

P3_deposition_N_i(ip, T)

Calculate the number of ice crystals nucleated via deposition nucleation with units of m⁻³.

Arguments

• ip: a struct with ice nucleation parameters:
  • c₁: constant [L⁻¹]
  • c₂: constant [K⁻¹]
  • T₀: freezing temperature [K]
  • T_dep_thres: lower cutoff temperature [K]
• T: air temperature [K].

Returns

• Nᵢ: number of ice crystals nucleated via deposition nucleation with units of m⁻³.

From Thompson et al 2004 eqn 2 as used in Morrison & Milbrandt 2015,

Nᵢ = c₁ exp(c₂ (T₀ - T))

where, in Thompson et al 2004, c₁ = 0.005, c₂ = 0.304, T₀ = 273.15 K, and T is the air temperature [K]. The nucleation number is at most the value at T = T_dep_thres, and is zero above T₀ = 0°C.

P3_het_N_i(ip, T, Nₗ, Vₗ, Δt)

Compute number of ice crystals formed from heterogeneous condensation freezing

Arguments

• ip: The CMP.MorrisonMilbrandt2014 paramterization, where:
  • het_a: empirical parameter [K⁻¹]
  • het_B: water-type dependent parameter [m⁻³ s⁻¹]
  • T₀: freezing temperature [K]
• T: air temperature [K],
• Nₗ: number of droplets [m⁻³],
• Vₗ: volume of droplets to be frozen [m³],
• Δt: timestep [s].

Returns

• Nᵢ: number of ice crystals [m⁻³] heterogeneously nucleated from cloud droplets in Δt seconds.

From Pruppacher & Klett 1997 eqn (9-51) as used in [25]:

ln N₀ / Nᵤ(t) = B Vₗ [exp(aTₛ)] t

where N₀=Nᵤ(t=0) is the initial number of cloud droplets, a and B are empirical parameters, Tₛ is the temperature difference between the freezing point and the air temperature, and Vₗ is the volume of cloud droplets to be frozen. Rearranged in terms of Nᵤ(t):

Nᵤ(t) = N₀ exp(-B Vₗ [exp(aTₛ)] t)

INP_concentration_frequency(params, INPC, T)

Calculate the relative frequency of a given INP concentration as a function of temperature.

Arguments

• params: a struct with INPC(T) distribution parameters
• INPC: concentration of ice nucleating particles [m^-3]
• T: air temperature [K]

For details see: [37], doi.org/10.5194/acp-23-10883-2023

INP_concentration_mean(params, T)

Calculate the mean log(INPC) as a function of temperature.

Arguments

• params: The CMP.Frostenberg2023 INPC(T) distribution parameters, including
  • T_freeze: freezing temperature [K]
  • b: temperature normalization coefficient [°C⁻¹]
• T: air temperature [K]

Following Eq. (1) of [37], the mean log(INPC) is

μ(T) = 9 log(-b · T_celsius / 10)

with the corresponding INPC obtained by exponentiating. At the default b = 1 this is the marine-dataset curve log((-T_celsius / 10)^9).

For details see: [37], doi.org/10.5194/acp-23-10883-2023

deposition_rate(
    opt::CMP.Frostenberg2023, tps, T, ρ, q_tot, q_liq, q_ice, n_ice;
    m_nuc, T_thresh, S_i_thresh, τ_act, inpc_log_shift,
)

Compute the Frostenberg 2023 deposition nucleation rate

The rate is the Frostenberg 2023 INP concentration (treated as a budget) relaxed toward depletion at n_ice over timescale τ_act:

∂ₜn_frz = max(0, INPC(T)/ρ - n_ice) / τ_act

Each newly nucleated crystal is assigned the starter mass m_nuc (e.g. (π/6) · ρ_i · D_nuc³ ≈ 4.8e-13 kg for a 10 μm solid-ice crystal). The mass tendency is the implied mass injection, capped by half the local vapor excess over ice saturation per relaxation window:

q_excess = max(0, q_vap - q_sat_ice)
∂ₜq_frz  = min(m_nuc · ∂ₜn_frz,  ½ q_excess / τ_act)

Conditions for activation:

• T < T_thresh (default T_freeze - 15 K, i.e. -15 °C): below this temperature deposition nucleation is active.
• S_i ≡ q_vap/q_sat_ice - 1 > S_i_thresh (default 5 %): ice supersaturation is required for vapor to nucleate onto INPs.

Arguments

• opt: The CMP.Frostenberg2023 parameters.
• tps: Thermodynamics parameters (used for the ice-saturation curve).
• T: Air temperature [K].
• ρ: Air density [kg(air) m⁻³(air)].
• q_tot: Total water specific content [kg kg⁻¹(air)].
• q_liq: Liquid water specific content [kg kg⁻¹(air)].
• q_ice: Ice specific content [kg kg⁻¹(air)].
• n_ice: Specific ice-crystal number concentration [kg⁻¹(air)] (proxy for already-activated INPs).

Keyword arguments

• m_nuc: Starter mass assigned to each newly nucleated crystal [kg].
• T_thresh: Activation temperature threshold [K] (default opt.T_freeze - 15).
• S_i_thresh: Activation ice-supersaturation threshold (default 0.05).
• τ_act: Relaxation timescale [s] (default 300).
• inpc_log_shift: Additive shift to log(INPC) (default 0).

Returns

• A NamedTuple (; ∂ₜn_frz, ∂ₜq_frz) with the specific number rate [kg⁻¹(air) s⁻¹] and specific mass rate [kg(ice) kg⁻¹(air) s⁻¹]. Zero outside the activation window.

immersion_limit_rate(opt::CMP.Frostenberg2023, T, ρ; τ, inpc_log_shift, n_active)

Compute the F23-INPC-imposed upper limit on the cloud-droplet immersion freezing number rate.

The Frostenberg 2023 climatology specifies a target INP concentration INPC(T) in air [m⁻³(air)]. Treating that target as a budget that should be activated on a relaxation timescale τ, the maximum number of crystals nucleated per kg of air per second is

∂ₜn_lim = max(0, INPC(T)/ρ - n_active) / τ.

n_active is the depletion proxy; see n_active.

Arguments

• opt: The CMP.Frostenberg2023 parameters.
• T: Air temperature [K].
• ρ: Air density [kg(air) m⁻³(air)].

Keyword arguments

• τ: Relaxation timescale [s] (default 300).
• inpc_log_shift: Additive shift to log(INPC) (default 0).
• n_active: Depletion proxy [kg⁻¹(air)].

Returns

• A NamedTuple (; ∂ₜn_frz) — the specific number freezing-rate cap [kg⁻¹(air) s⁻¹]. Zero when T ≥ T_freeze.

liquid_freezing_rate(opt, pdf, tps, q, ρ, N, T)

Compute the rate of liquid water freezing into ice.

Arguments

• opt: The CMP.RainFreezing parameterization.
• pdf: The liquid water particle size distribution (PSD) PDF.
• tps: Thermodynamics parameters.
• q: Liquid water specific content [kg(water) kg⁻¹(air)].
• ρ: Air density [kg(air) m⁻³(air)].
• N: Liquid water number concentration [m⁻³(air)].
• T: Air temperature [K].

Returns

• A NamedTuple with the fields:
  • ∂ₜn_frz: Specific number freezing rate [kg⁻¹(air) s⁻¹].
  • ∂ₜq_frz: Specific mass freezing rate [kg(water) kg⁻¹(air) s⁻¹].

liquid_freezing_rate(
    opt::CMP.RainFreezing, pdf::CMP.CloudParticlePDF_SB2006,
    tps, q, ρ, N, T,
)

Compute the rate of cloud-droplet immersion freezing into ice using the same Bigg (1953) kinetics as the rain version, but integrated over the generalized-gamma cloud-droplet PSD (SB2006).

The cloud PSD in diameter is

n(D) = N₀c · D^νcD · exp(-λc · D^μcD)   ,   νcD = 3νc + 2,  μcD = 3μc.

Bigg's per-drop freezing probability is J_bigg(T) · (π/6) · D³. Integrating against the PSD gives closed-form number- and mass-freezing rates:

∂ₜn_frz = J_bigg ·      (π/6)  · M_D³(N₀c, λc, νcD, μcD)
∂ₜq_frz = J_bigg · ρw · (π/6)² · M_D⁶(N₀c, λc, νcD, μcD)

with M_Dᵏ the kth diameter moment computed by generalized_gamma_Mⁿ. Volume-weighting → bigger drops freeze first

Arguments

• opt: The CMP.RainFreezing parameterization (Bigg / Barklie-Gokhale parameters; despite the type name, the kinetics apply to any liquid-drop PSD).
• pdf: The CMP.CloudParticlePDF_SB2006 cloud-droplet PSD.
• tps: Thermodynamics parameters.
• q: Cloud-liquid specific content [kg(water) kg⁻¹(air)].
• ρ: Air density [kg(air) m⁻³(air)].
• N: Cloud-droplet number concentration [m⁻³(air)].
• T: Air temperature [K].

Returns

• A NamedTuple with the fields:
  • ∂ₜn_frz: Specific number freezing rate [kg⁻¹(air) s⁻¹].
  • ∂ₜq_frz: Specific mass freezing rate [kg(water) kg⁻¹(air) s⁻¹].

n_active(model::CMP.NIceProxyDepletion, n_ice)

Return the depletion proxy n_active to subtract from the F23 INPC target in deposition_rate and any analogous INPC-budgeted rate. For NIceProxyDepletion (the only model currently provided) this is the in-cell ice number n_ice.

Frostenberg2023{FT}

Parameters for frequency distribution of INP concentration DOI: 10.5194/acp-23-10883-2023

Fields

• σ: standard deviation

• b: coefficient

• T_freeze: freezing temperature [K]

IceNucleationParameters{DEP, HOM, P3_type}

Parameters for ice nucleation

Fields

• deposition: deposition nucleation parameters, e.g. Mohler2006

• homogeneous: homogeneous nucleation parameters, e.g. Koop2000

• p3: P3 ice nucleation parameters, e.g. MorrisonMilbrandt2014

Koop2000{FT}

Parameters for ice nucleation from Koop et al 2000 DOI: 10.1038/35020537

Fields

• Δa_w_min: min Δaw [-]

• Δa_w_max: max Δaw [-]

• c₁: coefficient [-]

• c₂: coefficient [-]

• c₃: coefficient [-]

• c₄: coefficient [-]

• linear_c₁: coefficient [-]

• linear_c₂: coefficient [-]

Mohler2006{FT}

Parameters for ice nucleation from Mohler et al 2006 DOI: 10.5194/acp-6-3007-2006

Fields

• Sᵢ_max: max allowed supersaturation [-]

• T_thr: threshold temperature [K]

MorrisonMilbrandt2014{FT}

Parameters for ice nucleation from Morrison & Milbrandt (2015) DOI: 10.1175/JAS-D-14-0065.1

Fields

• T_dep_thres: Cutoff temperature for deposition nucleation [K]; maps to the ClimaParams homogeneous nucleation temperature, 233 K

• c₁: coefficient [-]

• c₂: coefficient [-]

• T₀: freezing temperature of water [K]

• het_a: heterogeneous freezing parameter a [K⁻¹]

• het_B: heterogeneous freezing parameter B [m⁻³ s⁻¹]

NIceProxyDepletion{FT}

Use the in-cell ice number n_ice as the depletion proxy for F23 activation. In this form, a column with no ice sees the full INPC target; activation events do not by themselves deplete the budget on a memory timescale, but the ice they create proxies "INPs already used" downstream until that ice sublimates, sediments out, or melts.

Conflates two physically distinct counts: "ice in column" and "INPs already activated in this air parcel". Drop a fresh anvil into clean air below it and the F23 channel artificially shuts off.

Fields

• τ_act: F23 activation relaxation timescale [s] (default 300)

RainFreezing{FT}

Parameters for heterogeneous (Bigg-type) immersion freezing of rain drops.

Stores the empirical Barklie-Gokhale (1959) / Bigg (1953) parameters used by Morrison & Milbrandt (2015).

Fields

• het_a: empirical parameter [K⁻¹]

• het_B: water-type dependent parameter [m⁻³ s⁻¹]

Callable interface

(rf::RainFreezing)(T, T₀) → het_B * exp(het_a * (T₀ - T))

Compute the volumetric freezing rate [m⁻³ s⁻¹]

Parameterization for homogeneous cloud ice nucleation

homogeneous_J_cubic(ip, Δa_w)

Calculate the homogeneous freezing nucleation rate coefficient, J [m⁻³ s⁻¹], for sulphuric acid solutions.

Arguments

• ip: The CMP.Koop2000 struct with ice nucleation parameters,
  • c₁, c₂, c₃, c₄: cubic fit coefficients [-]
  • Δa_w_min: minimum change in water activity [-]
  • Δa_w_max: maximum change in water activity [-]
• Δa_w: change in water activity [-].

Returns the homogeneous freezing nucleation rate coefficient, J, in m⁻³ s⁻¹ for sulphuric acid solutions. Parameterization based on [44], see doi.org/10.1038/35020537.

homogeneous_J_linear(ip, Δa_w)

Calculate the homogeneous freezing nucleation rate coefficient, J [m⁻³ s⁻¹], for sulphuric acid solutions.

Arguments

• ip: The CMP.Koop2000 struct with ice nucleation parameters,
  • linear_c₁, linear_c₂: linear fit coefficients [-]
• Δa_w: change in water activity [-].

Model is a linear fit of the [44] parameterization. See: doi.org/10.1038/35020537

CloudDiagnostics

• radar reflectivity (1-moment and 2-moment)
• effective radius (1-moment and 2-moment)

radar_reflectivity_1M(precip, q, ρ)

• precip - struct with 1-moment microphysics rain free parameters
• q - specific content of rain
• ρ - air density

Returns logarithmic radar reflectivity for the 1-moment microphysics based on the assumed rain particle size distribution. Normalized by the reflectivity of a 1 millimeter drop in a volume of 1 m³. The values are clipped at -150 dBZ.

radar_reflectivity_2M(structs, q_lcl, q_rai, N_lcl, N_rai, ρ_air)

• structs - structs microphysics 2-moment with SB2006 cloud droplets and raindrops size distributions parameters
• q_lcl - cloud liquid water specific content
• q_rai - rain water specific content
• N_lcl - cloud droplet number density
• N_rai - rain droplet number density
• ρ_air - air density

Returns logarithmic radar reflectivity for the 2-moment microphysics SB2006 based on the assumed cloud and rain particle size distributions. Normalized by the reflectivity of a 1 millimeter drop in a volume of 1 m³. The values are clipped at -150 dBZ.

effective_radius_const(cloud_params)

• cloud_params - a struct with cloud liquid or cloud ice parameters

Returns a constant assumed effective radius for clouds

effective_radius_Liu_Hallet_97(wtr, ρ_air, q_lcl, N_lcl, q_rai, N_rai)
effective_radius_Liu_Hallet_97(wtr, ρ_air, q_lcl)

• wtr - a struct with water properties (contains the water density ρw)
• ρ_air - air density
• q_lcl - cloud water specific content
• N_lcl - cloud droplet number density
• q_rai - rain water specific content
• N_rai - rain droplet number density

Returns effective radius using the "1/3" power law from Liu and Hallett (1997). If not provided by the user, it is assumed that there is no rain present and that the cloud droplet number concentration is 1e8 1/m3 (100 1/cm3).

effective_radius_2M(structs, q_lcl, q_rai, N_lcl, N_rai, ρ_air)

• structs - structs with SB2006 cloud droplets and raindrops size distribution parameters
• q_lcl - cloud liquid water specific content
• q_rai - rain water specific content
• N_lcl - cloud droplet number density
• N_rai - rain droplet number density
• ρ_air - air density

Returns effective radius for the 2-moment microphysics scheme. Computed based on the assumed cloud and rain particle size distributions.

Parameters

A module for CloudMicrophysics.jl free parameters.

AerosolDistributionType

The top-level super-type for all aerosol distribution types

AerosolType

The top-level super-type for all aerosol properties

CloudCondensateType

The top-level super-type for cloud condensate types (liquid and ice)

ParametersType

The top-level super-type for all cloud microphysics parameters

Precipitation2MType

The top-level super-type for 2-moment precipitation parameterizations

PrecipitationType

The top-level super-type for precipitation types (rain and snow)

TerminalVelocityType

The top-level super-type for terminal velocity parameterizations

AirProperties{FT}

Parameters with air properties.

Fields

• K_therm: thermal conductivity of air [W/m/K]

• D_vapor: diffusivity of water vapor [m²/s]

• ν_air: kinematic viscosity of air [m²/s]

WaterProperties{FT}

Parameters with water properties.

Fields

• ρw: density of liquid water [kg/m3]

• ρi: density of ice [kg/m3]

Blk1MVelType

The type for precipitation terminal velocity from the simple 1-moment scheme (defined for rain and snow)

Fields

• rain

• snow

Blk1MVelTypeRain

The type for precipitation terminal velocity from the simple 1-moment scheme for rain

Fields

• r0: particle length scale [m]

• ve: rain terminal velocity size relation coefficient [-]

• Δv: rain terminal velocity size relation coefficient [-]

• χv: rain terminal velocity size relation coefficient [-]

• ρw: cloud water density [kg/m3]

• C_drag: rain drop drag coefficient [-]

• grav: gravitational acceleration [m/s2]

• gamma_vent: pre-computed gamma((ve + Δv + 5) / 2) for ventilation [-]

• gamma_term: pre-computed gamma(me + ve + Δm + Δv + 1) for terminal velocity [-]

• gamma_accr: pre-computed gamma(ae + ve + Δa + Δv + 1) for accretion [-]

• gamma_accr_rain_sink: pre-computed gamma(me + ae + ve + Δm + Δa + Δv + 1) for accretionrainsink [-]

Blk1MVelTypeSnow

The type for precipitation terminal velocity from the simple 1-moment scheme for snow

Fields

• r0: particle length scale [m]

• ve: snow terminal velocity size relation coefficient [-]

• Δv: snow terminal velocity size relation coefficient [-]

• χv: snow terminal velocity size relation coefficient [-]

• v0: snow terminal velocity size relation coefficient [m/s]

• gamma_vent: pre-computed gamma((ve + Δv + 5) / 2) for ventilation [-]

• gamma_term: pre-computed gamma(me + ve + Δm + Δv + 1) for terminal velocity [-]

• gamma_accr: pre-computed gamma(ae + ve + Δa + Δv + 1) for accretion [-]

Chen2022VelType

The type for precipitation terminal velocity from Chen et al 2022 DOI: 10.1016/j.atmosres.2022.106171 (defined for rain, small ice, and large ice)

Fields

• rain: rain terminal velocity parameters

• small_ice: small ice terminal velocity parameters

• large_ice: large ice terminal velocity parameters