EAMxx: MAM4xx+ZM [DRAFT] by odiazib · Pull Request #8671 · E3SM-Project/E3SM

odiazib · 2026-08-26T16:26:16Z

The ZM+MAM4xx coupling is based on E3SM v2 and currently includes only the MAM4xx side. Please check for any missing code integration. I will keep this PR as a draft, as there is still a lot of work and discussion to be done.

Copilot review overview

🟡 Changes recommended

The implementation has a missing mam4xx API update, GPU-invalid host pointers, and incorrect dry-pressure units.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 3 · 1

Open (4)

Avoid capturing host configuration arrays in device kernel · New
Convert dry pressure thickness from Pa to millibars · New
Update mam4xx revision for the new convection API · New
Correct medium test duration to match documentation · New

What changed in this PR

Couples ZM deep-convection outputs to MAM4xx convective wet scavenging.

Changes:

Exposes ZM diagnostics required by MAM4xx.
Adds configurable aerosol and gas convective processing.
Adds physics-only, dynamics-physics, and CIME integration tests.

File	Description
`components/eamxx/tests/multi-process/physics_only/mam/p3_zm_mam4_wetscav/output.yaml`	Defines test outputs.
`components/eamxx/tests/multi-process/physics_only/mam/p3_zm_mam4_wetscav/input.yaml`	Configures the physics-only test.
`components/eamxx/tests/multi-process/physics_only/mam/p3_zm_mam4_wetscav/CMakeLists.txt`	Registers the test.
`components/eamxx/tests/multi-process/physics_only/CMakeLists.txt`	Enables the test directory.
`components/eamxx/tests/multi-process/dynamics_physics/mam/homme_shoc_cld_spa_p3_rrtmgp_zm_mam4_wetscav/output.yaml`	Defines coupled test outputs.
`components/eamxx/tests/multi-process/dynamics_physics/mam/homme_shoc_cld_spa_p3_rrtmgp_zm_mam4_wetscav/input.yaml`	Configures the coupled process chain.
`components/eamxx/tests/multi-process/dynamics_physics/mam/homme_shoc_cld_spa_p3_rrtmgp_zm_mam4_wetscav/CMakeLists.txt`	Registers the coupled test.
`components/eamxx/tests/multi-process/dynamics_physics/mam/CMakeLists.txt`	Enables the coupled test directory.
`components/eamxx/src/physics/zm/impl/zm_conv_main_impl.hpp`	Initializes inactive-column cloud-top output.
`components/eamxx/src/physics/zm/eamxx_zm_process_interface.cpp`	Exports ZM coupling fields.
`components/eamxx/src/physics/mam/eamxx_mam_wetscav_process_interface.hpp`	Adds ConvProc state and workspace.
`components/eamxx/src/physics/mam/eamxx_mam_wetscav_process_interface.cpp`	Integrates ConvProc with ZM outputs.
`components/eamxx/cime_config/testdefs/testmods_dirs/eamxx/mam4xx/zm/shell_commands`	Configures the CIME ZM/MAM4xx test.
`components/eamxx/cime_config/namelist_defaults_eamxx.xml`	Adds ConvProc defaults.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

susburrows · 2026-10-08T22:42:46Z

As we discussed yesterday, it would be a good idea to consolidate the convective vertical transport in one place. But I think that can wait for a follow-up PR.

whannah1 · 2026-10-09T14:05:21Z

As we discussed yesterday, it would be a good idea to consolidate the convective vertical transport in one place. But I think that can wait for a follow-up PR.

To be clear - "consolidate" does not mean we remove the ZM tracer transport since we discussed scenarios where we might want to use that capability.

kaizhangpnl · 2026-10-09T16:30:33Z

Remember that there is a potential bug in convproc.hpp:

https://github.com/E3SM-Project/mam4xx/blob/077a017ed3cdd2803ed64b34fc2f666688274875/src/mam4xx/convproc.hpp#L2732-L2744

kaizhangpnl

Great effort for this important PR. There are code changes in mam4xx, so I couldn't use in-line comment. Some of them are not MAM4xx+ZM coupling issues and they (and there are more "FIXME" comments) can be fixed later.

DJFJJA · 2026-10-09T19:21:17Z

  add_field<Computed>("zm_dcape",             scalar2d,   J/kg/s,   grid_name);
  add_field<Computed>("zm_activity",          scalar2d,     none,   grid_name);
+  add_field<Computed>("zm_jt",                scalar2d,     none,   grid_name);
+  add_field<Computed>("zm_jcbot",             scalar2d,     none,   grid_name);


ZM scheme uses the parcel lifting level (maxi) as the cloud-base level, which is appropriate for convective transport. However, for aerosol activation, the lifting condensation level (LCL) may be more appropriate, as it represents the level at which a rising air parcel becomes saturated, allowing aerosol activation and cloud droplet formation to occur.

@DJFJJA could you please point to the variable name (Fortran) of the lifting condensation level (LCL)?

@odiazib the variable jlcl in zm_conv_main() gives the index of the LCL.

So, zm tracer transport uses maxi (is this jctop?). But we want the aerosol tracer to use jlcl instead of jctop?
Note: for gases, which we agree will be handled by MAM4xx, we still need to use jctop. @DJFJJA and @whannah1.

maxi represents the parcel lifting level, corresponding to jcbot (the cloud-base level index), while jctop represents the cloud-top level index.

So, zm tracer transport uses maxi (is this jctop?). But we want the aerosol tracer to use jlcl instead of jctop? Note: for gases, which we agree will be handled by MAM4xx, we still need to use jctop. @DJFJJA and @whannah1.

To clarify - maxi was the old name for the level of maximum MSE used to launch parcels, and maxg was the "gathered" version. In the fortran refactor I renamed these to be msemax_klev / msemax_klev_g.

@DJFJJA was pointing out that the LCL may be "above" jcbot and the layers between the parcel launch level and the LCL might not have any condensate, thus no aerosol activation should happen in those levels. Whereas it might still be appropriate to use the parcel launch level for transport. I think it's a good point, but I'm not sure how to address it.

@whannah1 @DJFJJA, we are using zm_jt for ktop and zm_msemax_klev for kbot. Is this correct?

DJFJJA · 2026-10-09T19:31:12Z

In mam4xx/convproc.hpp:

I can confirm that this is a bug. The layer thickness (dz) should vary with vertical level rather than being a single scalar value. The same issue exists in the Fortran code as well.

@kaizhangpnl and @DJFJJA, can we handle this bug in a follow-up PR? This PR and its associated MAM4xx PR are too large. Note that I created an issue for this bug here: E3SM-Project/mam4xx#612

Sounds good!

…ld_kbot and zm_jctop -> zm_cld_ktop.

kaizhangpnl · 2026-10-29T00:17:28Z

Many thanks for all your work in finalizing this PR. I have one additional comment: we should verify that the units of all fields passed to ma_convproc_intr match the units it expects. I may have missed some necessary conversions, so I would appreciate the developers’ help checking this.

Two potential inconsistencies:

Dry pressure thickness (dpdry): ma_convproc_intr expects mb, whereas wet_dep.hpp and [eamxx_mam_wetscav_process_interface.cpp](https://github.com/E3SM-Project/E3SM/blob/5986c446c9b89be6800fe731454d11605f7443f3/components/eamxx/src/physics/mam/eamxx_mam_wetscav_process_interface.cpp#L875) appear to use Pa.
Convective mass fluxes: [zm_functions.hpp](https://github.com/E3SM-Project/E3SM/blob/5986c446c9b89be6800fe731454d11605f7443f3/components/eamxx/src/physics/zm/zm_functions.hpp#L455) appears to use mb/s, whereas the [MAM4xx interface](

E3SM/components/eamxx/src/physics/mam/eamxx_mam_wetscav_process_interface.cpp

Line 322 in 5986c44

add_field<Required>("zm_mflx_up", scalar3d_mid, kg / m2 / s, grid_name); // Updraft mass flux

) indicates kg/m²/s.

Could you help confirm that the necessary conversions are applied and check the remaining input fields for similar inconsistencies? Thanks!

…of zm_cld_bot for kbot.

odiazib · 2026-10-29T01:34:05Z

Convective mass fluxes: [zm_functions.hpp](https://github.com/E3SM-Project/E3SM/blob/5986c446c9b89be6800fe731454d11605f7443f3/components/eamxx/src/physics/zm/zm_functions.hpp#L455) appears to use mb/s, whereas the [MAM4xx interface](

E3SM/components/eamxx/src/physics/mam/eamxx_mam_wetscav_process_interface.cpp

Line 322 in 5986c44

add_field<Required>("zm_mflx_up", scalar3d_mid, kg / m2 / s, grid_name); // Updraft mass flux

) indicates kg/m²/s.

@kaizhangpnl The units of kg/m²/s come from the ZM interface see here.

@whannah1 Is there a typo in the units of zm_mflx_up? Should mb/s be kg/m/s^3?

odiazib · 2026-10-29T14:31:19Z

Dry pressure thickness (dpdry): ma_convproc_intr expects mb, whereas wet_dep.hpp and [eamxx_mam_wetscav_process_interface.cpp](https://github.com/E3SM-Project/E3SM/blob/5986c446c9b89be6800fe731454d11605f7443f3/components/eamxx/src/physics/mam/eamxx_mam_wetscav_process_interface.cpp#L875) appear to use Pa.

@kaizhangpnl I corrected the units for dpdry. Note that dpdry is used only by ma_convproc_intr.

DJFJJA · 2026-10-29T15:56:20Z

Convective mass fluxes: [zm_functions.hpp](https://github.com/E3SM-Project/E3SM/blob/5986c446c9b89be6800fe731454d11605f7443f3/components/eamxx/src/physics/zm/zm_functions.hpp#L455) appears to use mb/s, whereas the [MAM4xx interface](

E3SM/components/eamxx/src/physics/mam/eamxx_mam_wetscav_process_interface.cpp

Line 322 in 5986c44

add_field<Required>("zm_mflx_up", scalar3d_mid, kg / m2 / s, grid_name); // Updraft mass flux

) indicates kg/m²/s.

@kaizhangpnl The units of kg/m²/s come from the ZM interface see here.

@whannah1 Is there a typo in the units of zm_mflx_up? Should mb/s be kg/m/s^3?

In the ZM scheme, the updraft mass flux (mflx_up) is calculated in mb/s. In the Fortran implementation, it is converted to kg/m²/s using hydrostatic balance, with the conversion factor 100/g, before being stored in the output diagnostic arrays.

For example, in zm_conv_intr.F90:
! Store upward and downward mass fluxes in un-gathered arrays + convert from mb/s to kg/m^2/s
do i = 1,lengath
do k = 1,pver
mu_out(ideep(i),k) = mu(i,k) * 100.0_r8/gravit
md_out(ideep(i),k) = md(i,k) * 100.0_r8/gravit
end do
end do

However, I couldn't find an equivalent unit conversion in the current C++ implementation. In eamxx_zm_process_interface.cpp, zm_mflx_up is registered with units of kg/m²/s, but the output appears to be copied directly from the internal mflx_up array, which is documented as mb/s. @whannah1 Could you double-check this?

odiazib · 2026-10-29T16:30:43Z

I am marking this PR as ready for review so the tests can run on CI.

odiazib · 2026-10-30T17:50:24Z

      rliq(i)                = 0;
      dsubcld(i)             = 0;
-      jctop(i)               = pver - 1;
+      jctop(i)               = -1;


@overfelt I will revert this change.

whannah1 self-requested a review August 26, 2026 16:40

odiazib force-pushed the odiazib/eamxx/mam4xx-zm branch from 1d8b5a4 to 38517b8 Compare September 10, 2026 14:48

odiazib force-pushed the odiazib/eamxx/mam4xx-zm branch 2 times, most recently from 4f7920a to 24ce329 Compare September 17, 2026 15:02

odiazib force-pushed the odiazib/eamxx/mam4xx-zm branch 2 times, most recently from 39c78a4 to a57b412 Compare September 23, 2026 15:16

whannah1 reviewed Sep 23, 2026

View reviewed changes

Comment thread components/eamxx/src/physics/zm/eamxx_zm_process_interface.cpp Resolved

odiazib requested a balanced review from Copilot September 24, 2026 11:34

Copilot started reviewing on behalf of odiazib September 24, 2026 11:34

View session

odiazib requested review from kaizhangpnl and susburrows September 24, 2026 11:39

Copilot AI reviewed Sep 24, 2026

View reviewed changes

odiazib requested review from DJFJJA and yunpengshan2014 September 24, 2026 11:40

odiazib closed this Sep 28, 2026

odiazib reopened this Sep 28, 2026

odiazib force-pushed the odiazib/eamxx/mam4xx-zm branch from f309386 to a5bb2ce Compare October 1, 2026 15:11

whannah1 reviewed Oct 9, 2026

View reviewed changes

Comment thread components/eamxx/src/physics/zm/impl/zm_conv_main_impl.hpp Resolved

This comment was marked as resolved.

Sign in to view

kaizhangpnl reviewed Oct 9, 2026

View reviewed changes

whannah1 reviewed Oct 9, 2026

View reviewed changes

Comment thread components/eamxx/src/physics/zm/eamxx_zm_process_interface.cpp Resolved

DJFJJA reviewed Oct 9, 2026

View reviewed changes

odiazib and others added 9 commits October 28, 2026 15:59

Store aerdepwetis_convproc in FM.

014a648

initialization

35b6d25

rename variable from zm_ql_out/zm_ql to zm_icw_liq

ced288c

Using jctop instead of zm_jt. Variable names for FM: zm_jcbot -> zm_c…

c3f1891

…ld_kbot and zm_jctop -> zm_cld_ktop.

Type in field name, zm_cld_bit should be zm_cld_bot.

113b5a8

update mam4xx

07ca9e3

fixing compilation error in sp.

f831cf7

update mam4xx.

ac8451b

Rebase to main and update mam4xx to latest branch.

5986c44

overfelt force-pushed the odiazib/eamxx/mam4xx-zm branch from 8c82a19 to 5986c44 Compare October 28, 2026 22:01

Using zm_jt instead of zm_cld_top for top and zm_msemax_klev instead …

a5ee1b5

…of zm_cld_bot for kbot.

odiazib added 4 commits October 28, 2026 23:22

Fixing units of p_del_dry_icol; it needs to be mb.

04aed23

Fixing multi process tests.

6b0b019

Using mam4xx functions.

b29c37e

Fixing unit test p3_zm_mam4_wetscav.

7325bf5

odiazib marked this pull request as ready for review October 29, 2026 16:29

odiazib changed the title ~~EAMxx: MAM4xx+ZM~~ EAMxx: MAM4xx+ZM [DRAFT] Oct 29, 2026

odiazib added BFB PR leaves answers BFB EAMxx C++ based E3SM atmosphere model (aka SCREAM) MAM4xx MAM4xx related changes labels Oct 29, 2026

Fixing compilation error for sp.

fd2e856

odiazib commented Oct 30, 2026

View reviewed changes

odiazib added 3 commits October 30, 2026 11:53

jctop=-1 is producing out of memory errors.

ad0bb65

Using zm_activity to enable deep conv.

b1843c8

Fixing cuda out memory error.

9b47fdf

Conversation

odiazib commented Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-10-31 05:28 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

susburrows commented Oct 8, 2026

Uh oh!

whannah1 commented Oct 9, 2026

Uh oh!

Uh oh!

This comment was marked as resolved.

kaizhangpnl commented Oct 9, 2026

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

kaizhangpnl left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

odiazib Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaizhangpnl commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

odiazib commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

odiazib commented Oct 29, 2026

Uh oh!

DJFJJA commented Oct 29, 2026

Uh oh!

odiazib commented Oct 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

odiazib commented Aug 26, 2026 •

edited

Loading

github-actions Bot commented Sep 10, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-10-31 05:28 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

kaizhangpnl left a comment •

edited

Loading

odiazib Oct 13, 2026 •

edited

Loading

kaizhangpnl commented Oct 29, 2026 •

edited

Loading

odiazib commented Oct 29, 2026 •

edited

Loading