P3 Autoconversion: Physics Property Tests and Technical Documentation #7999

pressel · 2026-01-17T00:48:53Z

P3 Autoconversion: Physics Property Tests and Technical Documentation

Description:
This PR introduces a new "Physics Property Test" strategy for the P3 microphysics scheme, starting with the cloud water to rain autoconversion process. Unlike traditional BFB regression tests which only detect changes from a baseline, these tests validate that the implementation adheres to the fundamental physical principles of the parameterization (Khairoutdinov and Kogan, 2000).

In addition, this PR establishes a new section in the Technical Guide for detailed physics documentation.

Key Changes:

Enhanced Unit Tests (p3_autoconversion_unit_tests.cpp):
- Phase Space Sweep: Tests cover a wide range of regimes ($q_c$ from $5 \times 10^{-9}$ to $10^{-2}$ kg/kg, $N_c$ from $10^6$ to $10^9$ #/m³).
- Physical Properties Validated:
  - Thresholds: Verifies rate is zero below $q_c = 10^{-8}$ kg/kg.
  - Monotonicity: Checks correct sensitivity to inputs ($\partial R/\partial q_c > 0$ and $\partial R/\partial N_c < 0$).
  - Conservation: Verifies specific mass loss equals specific number loss ($N_{loss} = R \cdot N_c/q_c$).
  - Limits: Verifies autoconversion is negligible in the "Haze Limit" ($r < 1\mu m$).
  - Self-Consistency: Verifies the implicit mass of new raindrops corresponds to the characteristic radius ($r_{auto} \approx 25\mu m$).
- Parameter Validation: Ensures runtime configuration matches KK2000 constants.
New Documentation (docs/technical/physics/p3/autoconversion.md):
- Documents the mathematical formulation of the autoconversion rate and number tendencies.
- Explains the implementation details (thresholds, variance scaling status).
- Details the test strategy and the specific physical properties being verified.
Documentation Structure:
- Updated components/eamxx/mkdocs.yml to include a new Physics section under the Technical Guide.

Testing:

Ran p3_autoconversion_unit_tests on pm-cpu (GNU).
All property checks pass.
The test correctly identifies that subgrid variance scaling is currently disabled in the implementation.

Copilot

Pull request overview

This PR introduces a comprehensive physics property testing framework for the P3 microphysics autoconversion process, replacing simple positivity checks with rigorous validation of physical principles from Khairoutdinov and Kogan (2000). It also establishes technical documentation infrastructure for detailed physics descriptions.

Changes:

Enhanced unit tests with physics-based property validation across a wide parameter space (5×10⁻⁹ to 10⁻² kg/kg for qc, 10⁶ to 10⁹ #/m³ for Nc)
Added comprehensive technical documentation describing the mathematical formulation, implementation details, and testing strategy
Extended mkdocs configuration to include a new Physics section under the Technical Guide

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
`components/eamxx/src/physics/p3/tests/p3_autoconversion_unit_tests.cpp`	Replaced simple positivity test with comprehensive physics property tests validating thresholds, monotonicity, conservation, limits, and variance scaling
`components/eamxx/docs/technical/physics/p3/autoconversion.md`	New technical documentation detailing KK2000 formulation, implementation specifics, and property-based test strategy
`components/eamxx/mkdocs.yml`	Added Physics > P3 > Autoconversion section to documentation navigation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

components/eamxx/src/physics/p3/tests/p3_autoconversion_unit_tests.cpp

components/eamxx/docs/technical/physics/p3/autoconversion.md

Co-authored-by: Copilot <[email protected]>

… logic

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 11 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

components/eamxx/docs/technical/physics/p3/autoconversion.md

components/eamxx/src/physics/p3/tests/p3_autoconversion_unit_tests.cpp

components/eamxx/docs/technical/physics/p3/autoconversion.md

components/eamxx/src/physics/p3/tests/p3_autoconversion_unit_tests.cpp

Co-authored-by: Copilot <[email protected]>

…ation

github-actions · 2026-01-19T15:19:26Z

PR Preview Action v1.8.1
🚀 View preview at https://E3SM-Project.github.io/E3SM/pr-preview/pr-7999/
Built to branch `gh-pages` at 2026-01-20 15:57 UTC. Preview will be ready when the GitHub Pages deployment is complete.

mahf708

I skimmed this PR, and this looks pretty good. I added some minor comments which can be addressed later. Some equations in https://docs.e3sm.org/E3SM/pr-preview/pr-7999/EAMxx/technical/physics/p3/autoconversion/ aren't loading correctly in my browser, just double check that one more time before merging

mahf708 · 2026-01-20T18:03:44Z

components/eamxx/src/physics/p3/tests/p3_autoconversion_unit_tests.cpp

+#ifdef SCREAM_DOUBLE_PRECISION
+    const Real identity_tol = 1e-14;  // ~100x machine epsilon (double)
+#else
+    const Real identity_tol = 1e-7;   // ~1000x machine epsilon (float)
+#endif


can also use something from std/kokkos numerics here for the automatically detected epsilon with <Real>

e.g.

// A numerical tolerance auto tol = std::numeric_limits<Real>::epsilon() * 100;

mahf708 · 2026-01-20T18:05:57Z

components/eamxx/src/physics/p3/tests/p3_autoconversion_unit_tests.cpp

-    Spack qc_incld, nc_incld(1e7), qc2qr_autoconv_tend(0.0), nc2nr_autoconv_tend(0.0), ncautr(0.0);
-    for(int si=0; si<Spack::n; ++si){
-        qc_incld[si] = 1e-6 * i * Spack::n + si;
+  void validate_autoconversion_parameters() {


note that we set the defaults in the xmls and the hardcoded items below may cause fails that will require code edits here again? nbd, we can always edit the items below, just noting it here for your consideration

mahf708 · 2026-01-20T18:06:13Z

components/eamxx/docs/technical/physics/p3/autoconversion.md

+$$
+
+\equiv \texttt{nc_incld} \cdot \texttt{sp(1.e-6)} \cdot \rho
+### Number Tendencies


need a line above this "title" otherwise linter will keep crying

pressel added 4 commits January 16, 2026 06:46

First autoconversion peroperty test impls.

d4a5cff

Merge branch 'master' into pressel/eamxx/p3-autoconversion-pt

075a834

refined physics property test conditions

895fb2f

Merge branch 'master' into pressel/eamxx/p3-autoconversion-pt

e647f80

pressel requested review from AaronDonahue and Copilot January 17, 2026 00:48

pressel added BFB PR leaves answers BFB Testing Anything related to unit/system tests EAMxx C++ based E3SM atmosphere model (aka SCREAM) labels Jan 17, 2026

Copilot started reviewing on behalf of pressel January 17, 2026 00:49 View session

Copilot AI reviewed Jan 17, 2026

View reviewed changes

pressel marked this pull request as draft January 17, 2026 00:55

pressel and others added 4 commits January 16, 2026 16:58

Update components/eamxx/docs/technical/physics/p3/autoconversion.md

52dccd1

Co-authored-by: Copilot <[email protected]>

test(p3): improve variance scaling logic in autoconversion unit test

7cc6cea

test(p3): use high-precision Pi constant and improve variance scaling…

b4594c5

… logic

P3 autoconv tests: relax tol, clarify embryo msg

9f2355c

pressel requested a review from Copilot January 17, 2026 02:13

Copilot started reviewing on behalf of pressel January 17, 2026 02:14 View session

Copilot AI reviewed Jan 17, 2026

View reviewed changes

Update components/eamxx/docs/technical/physics/p3/autoconversion.md

0886400

Co-authored-by: Copilot <[email protected]>

Copilot AI mentioned this pull request Jan 17, 2026

No changes needed - validate_eps is correct as-is #8000

Closed

pressel added 3 commits January 17, 2026 08:39

test(p3): enforce strict 25um embryo radius check and update docs

a0fb9b3

p3_tests: improve comment

8b483ae

test(p3): enforce strict monotonicity in autoconversion and update docs

1a0b87f

E3SM-Project deleted a comment from Copilot AI Jan 17, 2026

pressel added 3 commits January 18, 2026 07:25

test(p3): enforce strict monotonicity and fix autoconversion document…

37afc4d

…ation

markdown formatting

8d17e3f

better treatment of tolerances

ca5c630

pressel self-assigned this Jan 18, 2026

markdown compliance

9c8fe91

pressel added 3 commits January 18, 2026 09:24

fixing shadow tolerances

4e4e4b9

remove haze terminology to be scientifically precise

abde1e2

fixing link in docs

0552b32

pressel added 3 commits January 19, 2026 08:54

refining docs

13e4b63

equation formatting

bae5bb9

more formatting

b8ca699

bartgol added the CI: approved Allow gh actions PR testing on ghci-snl-* machines label Jan 19, 2026

pressel added 2 commits January 20, 2026 07:17

more docs formatting

22027f4

a bit more formatting

9277793

pressel requested a review from mahf708 January 20, 2026 15:29

pressel marked this pull request as ready for review January 20, 2026 15:32

more formatting

105639e

AaronDonahue added CI: approved Allow gh actions PR testing on ghci-snl-* machines and removed CI: approved Allow gh actions PR testing on ghci-snl-* machines labels Jan 20, 2026

mahf708 marked this pull request as draft January 20, 2026 17:56

mahf708 marked this pull request as ready for review January 20, 2026 17:56

mahf708 approved these changes Jan 20, 2026

View reviewed changes

P3 Autoconversion: Physics Property Tests and Technical Documentation #7999

Are you sure you want to change the base?

P3 Autoconversion: Physics Property Tests and Technical Documentation #7999

Conversation

pressel commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-01-20 15:57 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

mahf708 left a comment

Choose a reason for hiding this comment

Uh oh!

mahf708 Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

mahf708 Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

mahf708 Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

mahf708 Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

pressel commented Jan 17, 2026 •

edited

Loading

github-actions bot commented Jan 19, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-01-20 15:57 UTC.
Preview will be ready when the GitHub Pages deployment is complete.