Implement PredictedParticlePropertyMicrophysics

.gitignore

@@ -29,9 +29,12 @@ Manifest.toml
 *.jld2
 *.png
 *.mp4
+*.nc
 
 # other files we don't want
 *.swp
 *.DS_Store
 *.vscode
 *.code-workspace
+*.juliaup*
+

AGENTS.md

@@ -39,16 +39,19 @@ Breeze interfaces with ClimaOcean for coupled atmosphere-ocean simulations.
      with kernels launched via `launch!`. This ensures code works on both CPU and GPU.
    - **Use literal zeros**: Write `max(0, a)` instead of `max(zero(FT), a)`. Julia handles type
      promotion automatically, and `0` is more readable. The same applies to `min`, `clamp`, etc.
+   - **Use `sqrt` and `cbrt`**: Never use `^(1/2)` or `^(1/3)` for square roots or cube roots.
+     Always use `sqrt(x)` and `cbrt(x)` instead. These are faster, more precise, and more readable.
 
 4. **Documentation**:
    - Use DocStringExtensions.jl for consistent docstrings
    - Use `$(TYPEDSIGNATURES)` for automatic typed signature documentation (preferred over `$(SIGNATURES)`)
    - Never write explicit function signatures in docstrings; always use `$(TYPEDSIGNATURES)`
    - Add examples in docstrings when helpful
-   - **Citations in docstrings**: Use inline citations with `[Author1 and Author2 (year)](@cite Key)` or `[Author1 et al. (Year)](@cite Key)` syntax.
+   - **Citations in docstrings**: Use inline citations with `[Author1 and Author2 (year)](@cite Key)` or `[Author1 et al. (Year)](@cite Key)` syntax (`@citet Key` is invalid).
      Avoid separate "References" sections with bare `[Key](@cite)` - these just show citation keys in the REPL
      without context, which is not helpful. Instead, weave citations naturally into the prose, e.g.:
      "Tetens' formula [Tetens1930](@citet) is an empirical formula..."
+   - **Citations in the rest of documentation** (i.e. not docstrings in the source code): Use the `[Key](@cite)` or `[Key](@citet)` style, as appropriate, not the `[Author1 and Author2 (year)](@cite Key)` or `[Author1 et al. (Year)](@cite Key)` syntax, that's only necessary for docstrings.
 
 5. **Memory leanness**
    - Favor doing computations inline versus allocating temporary memory

Project.toml

@@ -16,6 +16,7 @@ JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
 Oceananigans = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 
 [weakdeps]
 ClimaComms = "3a4d1b5c-c61d-41fd-a00a-5873ba7a1b0d"
@@ -39,4 +40,5 @@ KernelAbstractions = "0.9"
 Oceananigans = "0.102.2, 0.103"
 Printf = "1"
 RRTMGP = "0.21"
+SpecialFunctions = "2"
 julia = "1.10.10"

docs/Project.toml

@@ -13,6 +13,7 @@ Oceananigans = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 RRTMGP = "a01a1ee8-cea4-48fc-987c-fc7878d79da1"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 
 [sources]
 Breeze = {path = ".."}
@@ -29,3 +30,4 @@ NCDatasets = "0.14"
 Oceananigans = "0.102, 0.103"
 Pkg = "<0.0.1, 1"
 Random = "<0.0.1, 1"
+SpecialFunctions = "2.6"

docs/make.jl

@@ -41,6 +41,8 @@ examples = [
     Example("Cloud formation in prescribed updraft", "kinematic_driver", true),
 ]
 
+examples = []
+
 # Filter out long-running example if necessary
 filter!(x -> x.build_always || get(ENV, "BREEZE_BUILD_ALL_EXAMPLES", "false") == "true", examples)
 example_pages = [ex.title => joinpath("literated", ex.basename * ".md") for ex in examples]
@@ -153,7 +155,7 @@ makedocs(
     ),
     pages=[
         "Home" => "index.md",
-        "Examples" => example_pages,
+        # "Examples" => example_pages,
         "Thermodynamics" => "thermodynamics.md",
         "AtmosphereModel" => Any[
             "Diagnostics" => "atmosphere_model/diagnostics.md",
@@ -178,7 +180,7 @@ makedocs(
         "API" => "api.md",
         "Contributors guide" => "contributing.md",
     ],
-    linkcheck = true,
+    linkcheck = false,  # Disabled due to GitHub rate limiting (429 errors)
     draft = false,
     doctest = true
 )

docs/src/appendix/notation.md

@@ -116,3 +116,76 @@ The following table also uses a few conventions that suffuse the source code and
 | ``τˡʷ``                             | `τˡʷ`  |                                     | Atmosphere optical thickness for longwave                                      |
 | ``τˢʷ``                             | `τˢʷ`  |                                     | Atmosphere optical thickness for shortwave                                     |
 | ``N_A``                             | `ℕᴬ`   |                                     | Avogadro's number, molecules per mole                                          |
+
+## P3 Microphysics Notation
+
+The following notation is specific to the [Predicted Particle Properties (P3)](@ref Breeze.Microphysics.PredictedParticleProperties) microphysics scheme.
+
+### Size Distribution Parameters
+
+| math symbol                         | code   | property name                       | description                                                                    |
+| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ |
+| ``N_0``                             | `N₀`   | `intercept`                         | Intercept parameter of gamma size distribution [m⁻⁴⁻μ]                         |
+| ``\mu``                             | `μ`    | `shape`                             | Shape parameter of gamma size distribution [-]                                 |
+| ``\lambda``                         | `λ`    | `slope`                             | Slope parameter of gamma size distribution [1/m]                               |
+| ``N'(D)``                           | `Np`   |                                     | Number size distribution, ``N'(D) = N_0 D^\mu e^{-\lambda D}``                 |
+| ``D``                               | `D`    |                                     | Particle diameter [m]                                                          |
+
+### Ice Particle Properties
+
+| math symbol                         | code   | property name                       | description                                                                    |
+| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ |
+| ``F^f``                             | `Fᶠ`   | `rime_fraction`                     | Rime (frozen accretion) mass fraction [-], 0 = unrimed, 1 = fully rimed        |
+| ``\rho^f``                          | `ρᶠ`   | `rime_density`                      | Density of rime layer [kg/m³]                                                  |
+| ``F^l``                             | `Fˡ`   | `liquid_fraction`                   | Liquid water fraction on ice particles [-]                                     |
+| ``m(D)``                            | `m`    |                                     | Particle mass as function of diameter [kg]                                     |
+| ``V(D)``                            | `V`    |                                     | Terminal velocity as function of diameter [m/s]                                |
+| ``A(D)``                            | `A`    |                                     | Particle cross-sectional area [m²]                                             |
+| ``C(D)``                            | `C`    |                                     | Particle capacitance for vapor diffusion [m]                                   |
+| ``\alpha``                          | `α`    | `coefficient`                       | Mass-diameter power law coefficient, ``m(D) = \alpha D^\beta`` [kg/m^β]        |
+| ``\beta``                           | `β`    | `exponent`                          | Mass-diameter power law exponent [-]                                           |
+| ``\rho^i``                          | `ρⁱ`   |                                     | Pure ice density [kg/m³], typically 917                                        |
+
+### Fall Speed
+
+| math symbol                         | code   | property name                       | description                                                                    |
+| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ |
+| ``a_V``                             | `a_V`  | `fall_speed_coefficient`            | Fall speed power law coefficient [m^{1-b}/s]                                   |
+| ``b_V``                             | `b_V`  | `fall_speed_exponent`               | Fall speed power law exponent [-]                                              |
+| ``V_n``                             | `Vn`   |                                     | Number-weighted mean fall speed [m/s]                                          |
+| ``V_m``                             | `Vm`   |                                     | Mass-weighted mean fall speed [m/s]                                            |
+| ``V_z``                             | `Vz`   |                                     | Reflectivity-weighted mean fall speed [m/s]                                    |
+
+### Ice Concentrations and Moments
+
+| math symbol                         | code   | property name                       | description                                                                    |
+| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ |
+| ``N_i``                             | `N_ice`, `Nᵢ` |                                | Ice number concentration [1/m³]                                                |
+| ``L_i``                             | `L_ice`, `Lᵢ` |                                | Ice mass concentration [kg/m³]                                                 |
+| ``Z_i``                             | `Z_ice`, `Zᵢ` |                                | Ice reflectivity / sixth moment [m⁶/m³]                                        |
+| ``Q_{norm}``                        | `Qnorm` |                                    | Normalized ice mass = ``L_i / N_i`` [kg]                                       |
+
+### Rain Properties
+
+| math symbol                         | code   | property name                       | description                                                                    |
+| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ |
+| ``N_r``                             | `N_rain`, `Nʳ` |                               | Rain number concentration [1/m³]                                               |
+| ``L_r``                             | `L_rain`, `Lʳ` |                               | Rain mass concentration [kg/m³]                                                |
+| ``\mu_r``                           | `μ_r`  |                                     | Rain shape parameter [-]                                                       |
+
+### Collection and Ventilation
+
+| math symbol                         | code   | property name                       | description                                                                    |
+| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ |
+| ``E^{ic}``                          | `Eⁱᶜ`  | `ice_cloud_collection_efficiency`   | Ice-cloud droplet collection efficiency [-]                                    |
+| ``E^{ir}``                          | `Eⁱʳ`  | `ice_rain_collection_efficiency`    | Ice-rain collection efficiency [-]                                             |
+| ``f^{ve}``                          | `fᵛᵉ`  |                                     | Ventilation factor for vapor diffusion enhancement [-]                         |
+
+### Diameter Thresholds
+
+| math symbol                         | code   | property name                       | description                                                                    |
+| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ |
+| ``D_{th}``                          | `D_spherical` |                              | Threshold between small spherical ice and aggregates [m]                       |
+| ``D_{gr}``                          | `D_graupel` |                                | Threshold between aggregates and graupel [m]                                   |
+| ``D_{cr}``                          | `D_partial` |                                | Threshold between graupel and partially rimed ice [m]                          |
+| ``D_{crit}``                        | `D_crit` |                                   | Critical diameter separating small and large ice for melting [m]               |

docs/src/breeze.bib

@@ -322,3 +322,184 @@ @article{Shu1988Efficient
   doi = {10.1016/0021-9991(88)90177-5},
   author = {Chi-Wang Shu and Stanley Osher},
 }
+
+@article{MilbrandtMorrison2016,
+  author = {Milbrandt, Jason A. and Morrison, Hugh},
+  title = {Parameterization of cloud microphysics based on the prediction of bulk ice particle properties. {Part III}: Introduction of multiple free categories},
+  journal = {Journal of the Atmospheric Sciences},
+  volume = {73},
+  number = {3},
+  pages = {975--995},
+  year = {2016},
+  doi = {10.1175/JAS-D-15-0204.1}
+}
+
+@article{MilbrandtEtAl2024,
+  author = {Milbrandt, Jason A. and Morrison, Hugh and Dawson, Daniel T. and Paukert, Marcus},
+  title = {A triple-moment representation of ice in the {Predicted Particle Properties (P3)} microphysics scheme},
+  journal = {Journal of Advances in Modeling Earth Systems},
+  volume = {16},
+  number = {2},
+  pages = {e2023MS003751},
+  year = {2024},
+  doi = {10.1029/2023MS003751}
+}
+
+@article{MilbrandtYau2005,
+  author = {Milbrandt, Jason A. and Yau, M. K.},
+  title = {A multimoment bulk microphysics parameterization. {Part I}: Analysis of the role of the spectral shape parameter},
+  journal = {Journal of the Atmospheric Sciences},
+  volume = {62},
+  number = {9},
+  pages = {3051--3064},
+  year = {2005},
+  doi = {10.1175/JAS3534.1}
+}
+
+@article{FieldEtAl2007,
+  author = {Field, Paul R. and Heymsfield, Andrew J. and Bansemer, Aaron},
+  title = {Snow size distribution parameterization for midlatitude and tropical ice clouds},
+  journal = {Journal of the Atmospheric Sciences},
+  volume = {64},
+  number = {12},
+  pages = {4346--4365},
+  year = {2007},
+  doi = {10.1175/2007JAS2344.1}
+}
+
+@article{KhairoutdinovKogan2000,
+  author = {Khairoutdinov, Marat and Kogan, Yefim},
+  title = {A new cloud physics parameterization in a large-eddy simulation model of marine stratocumulus},
+  journal = {Monthly Weather Review},
+  volume = {128},
+  number = {1},
+  pages = {229--243},
+  year = {2000},
+  doi = {10.1175/1520-0493(2000)128<0229:ANCPPI>2.0.CO;2}
+}
+
+@article{HallPruppacher1976,
+  author = {Hall, W. D. and Pruppacher, H. R.},
+  title = {The survival of ice particles falling from cirrus clouds in subsaturated air},
+  journal = {Journal of the Atmospheric Sciences},
+  volume = {33},
+  number = {10},
+  pages = {1995--2006},
+  year = {1976},
+  doi = {10.1175/1520-0469(1976)033<1995:TSOIPF>2.0.CO;2}
+}
+
+@article{KlempEtAl2015,
+  author = {Klemp, Joseph B. and Dudhia, Jimy and Hassiotis, Anthony D.},
+  title = {An upper gravity-wave absorbing layer for {NWP} applications},
+  journal = {Monthly Weather Review},
+  volume = {136},
+  number = {10},
+  pages = {3987--4004},
+  year = {2008},
+  doi = {10.1175/2008MWR2596.1}
+}
+
+@article{DeMottEtAl2010icenuclei,
+  author =	 {P. J. DeMott and A. J. Prenni and X. Liu and S. M. Kreidenweis
+                  and M. D. Petters and C. H. Twohy and M. S. Richardson and
+                  T. Eidhammer and D. C. Rogers},
+  title =	 {Predicting global atmospheric ice nuclei distributions and
+                  their impacts on climate},
+  journal =	 {Proceedings of the National Academy of Sciences},
+  volume =	 107,
+  number =	 25,
+  pages =	 {11217-11222},
+  year =	 2010,
+  doi =		 {10.1073/pnas.0910818107},
+}
+
+@article{HeymsfieldPflaum1985graupelgrowth,
+  author =	 "Andrew J. Heymsfield and John C. Pflaum",
+  title =	 "A Quantitative Assessment of the Accuracy of Techniques for
+                  Calculating Graupel Growth",
+  journal =	 "Journal of Atmospheric Sciences",
+  year =	 1985,
+  publisher =	 "American Meteorological Society",
+  address =	 "Boston MA, USA",
+  volume =	 42,
+  number =	 21,
+  doi =		 "10.1175/1520-0469(1985)042<2264:AQAOTA>2.0.CO;2",
+  pages =	 "2264 - 2274",
+}
+
+@article{MeyerEtAl1992icenucleation,
+  author =	 "Michael P. Meyers and Paul J. DeMott and William R. Cotton",
+  title =	 "New Primary Ice-Nucleation Parameterizations in an Explicit
+                  Cloud Model",
+  journal =	 "Journal of Applied Meteorology and Climatology",
+  year =	 1992,
+  publisher =	 "American Meteorological Society",
+  address =	 "Boston MA, USA",
+  volume =	 31,
+  number =	 7,
+  doi =		 "10.1175/1520-0450(1992)031<0708:NPINPI>2.0.CO;2",
+  pages =	 "708 - 721",
+}
+
+@article{Mitchell1996powerlaws,
+  author =	 "David L. Mitchell",
+  title =	 "Use of Mass- and Area-Dimensional Power Laws for Determining
+                  Precipitation Particle Terminal Velocities",
+  journal =	 "Journal of Atmospheric Sciences",
+  year =	 1996,
+  publisher =	 "American Meteorological Society",
+  address =	 "Boston MA, USA",
+  volume =	 53,
+  number =	 12,
+  doi =		 "10.1175/1520-0469(1996)053<1710:UOMAAD>2.0.CO;2",
+  pages =	 "1710 - 1723",
+}
+
+% =============================================================================
+% P3 Microphysics Papers (Complete Set)
+% =============================================================================
+
+@article{Morrison2015part2,
+  author = {Morrison, Hugh and Milbrandt, Jason A. and Bryan, George H. and Ikeda, Kyoko and Tessendorf, Sarah A. and Thompson, Gregory},
+  title = {Parameterization of cloud microphysics based on the prediction of bulk ice particle properties. {Part II}: Case study comparisons with observations and other schemes},
+  journal = {Journal of the Atmospheric Sciences},
+  volume = {72},
+  number = {1},
+  pages = {312--339},
+  year = {2015},
+  doi = {10.1175/JAS-D-14-0066.1}
+}
+
+@article{MilbrandtEtAl2021,
+  author = {Milbrandt, Jason A. and Morrison, Hugh and Dawson, Daniel T. and Paukert, Marcus},
+  title = {A triple-moment representation of ice in the {Predicted Particle Properties (P3)} microphysics scheme},
+  journal = {Journal of the Atmospheric Sciences},
+  volume = {78},
+  number = {2},
+  pages = {439--458},
+  year = {2021},
+  doi = {10.1175/JAS-D-20-0084.1}
+}
+
+@article{MilbrandtEtAl2025liquidfraction,
+  author = {Milbrandt, Jason A. and Morrison, Hugh and Dawson, Daniel T.},
+  title = {Predicted liquid fraction for ice particles in the {Predicted Particle Properties (P3)} microphysics scheme},
+  journal = {Journal of Advances in Modeling Earth Systems},
+  volume = {17},
+  number = {1},
+  pages = {e2024MS004404},
+  year = {2025},
+  doi = {10.1029/2024MS004404}
+}
+
+@article{Morrison2025complete3moment,
+  author = {Morrison, Hugh and Milbrandt, Jason A. and Dawson, Daniel T.},
+  title = {A complete three-moment representation of ice in the {Predicted Particle Properties (P3)} microphysics scheme},
+  journal = {Journal of Advances in Modeling Earth Systems},
+  volume = {17},
+  number = {1},
+  pages = {e2024MS004644},
+  year = {2025},
+  doi = {10.1029/2024MS004644}
+}