EAMxx: 3D Turbulence Finisher (bug fixes, enhancements, numerical stability improvements)

[bogensch]

This PR puts the finishing touches on the implementation of 3D turbulence and addresses several issues identified during rigorous scientific validation and numerical stress testing. These changes include bug fixes, corrections to the implementation, new namelist controls, and several improvements to the numerical and scientific formulation.
Specific changes include:

1. Adds independent namelist controls for horizontal turbulence subcycling and removes its dependence on the dynamical-core hyperviscosity subcycling. This allows the numerical stability and computational cost of SGS horizontal diffusion to be controlled independently of hyperviscosity.
2. Fixes an issue where tracer SGS horizontal diffusion was applied only to water vapor. Horizontal SGS diffusion is now applied consistently to all tracers.
3. Fixes two major bugs in the SGS tracer diffusion implementation that caused model crashes at high horizontal resolution. This includes an egregious sign issue when applying laplacian tendencies and avoiding applying mass matrix each subcycle.
4. Adds CFL-based clipping of the horizontal eddy diffusivities for numerical stability. Testing indicates that this clipping is triggered only rarely when using the default horizontal eddy-diffusivity parameters and therefore has negligible impact on the intended SGS turbulence formulation under normal conditions.
5. Introduces a separate formulation for the horizontal eddy diffusivities rather than using the vertical eddy diffusivities. This is more consistent with other 3D turbulence formulations and is more physically appropriate, particularly at kilometer and gray-zone resolutions where SGS turbulence can be strongly anisotropic. At these resolutions, the characteristic horizontal and vertical mixing scales can differ substantially, so using the same diffusivity formulation in both directions can produce unrealistically strong horizontal mixing.
6. Fixes an issue where the do_3d_turbulence flag was not being linked correctly to SHOC. Also add checks to ensure the flags to HOMME and SHOC are set consistently.
7. Prevents layer thickness and geopotential from being horizontally diffused by the SGS turbulence scheme. Unlike tracers and thermodynamic quantities, layer thickness and geopotential are components of the model's dynamical state and are governed by the resolved equations of motion and mass continuity. Applying an additional SGS horizontal diffusion operator to these fields is not physically analogous to turbulent mixing of tracers and can introduce unintended modifications to the model's mass distribution and pressure/geopotential structure. Horizontal SGS turbulence is therefore restricted to quantities for which turbulent transport has a clear physical interpretation.
8. Adds documentation for the 3D turbulence scheme.

Since 3D turbulence is a stealth feature, it is expected this PR will be B4B.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://E3SM-Project.github.io/E3SM/pr-preview/pr-8630/
Built to branch gh-pages at 2026-08-27 16:41 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[mahf708]

@bogensch could we add some light technical/user docs while at it? goal: tell users the technical methods (technical docs) and how to enable/disalbe/etc (user docs)

[bogensch]

@bogensch could we add some light technical/user docs while at it? goal: tell users the technical methods (technical docs) and how to enable/disalbe/etc (user docs)

Great idea, will do!

[Copilot]

Pull request overview

Refines EAMxx 3-D SGS turbulence coupling, stability, and tracer diffusion.

Changes:

• Adds independent SGS subcycling and CFL clipping.
• Applies horizontal diffusion to all tracers.
• Introduces horizontal SHOC diffusivities and corrects HOMME coupling.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
components/homme/src/theta-l_kokkos/theta_f2c_mod.F90	Extends the Fortran/C++ parameter interface.
components/homme/src/theta-l_kokkos/prim_driver_mod.F90	Passes horizontal subcycling to C++.
components/homme/src/theta-l_kokkos/cxx/HyperviscosityFunctorImpl.hpp	Stores separate SGS timestep data.
components/homme/src/theta-l_kokkos/cxx/HyperviscosityFunctorImpl.cpp	Revises SGS diffusion, clipping, and state updates.
components/homme/src/theta-l_kokkos/cxx/cxx_f90_interface_theta.cpp	Validates and stores the new parameter.
components/homme/src/share/sl_advection.F90	Exposes tracer SGS subcycling.
components/homme/src/share/namelist_mod.F90	Reads and broadcasts new namelist controls.
components/homme/src/share/cxx/SimulationParams.hpp	Adds horizontal turbulence subcycling state.
components/homme/src/share/cxx/ComposeTransportImplHorizTurb.cpp	Diffuses all tracers with CFL clipping.
components/homme/src/share/cxx/ComposeTransportImplGeneral.cpp	Configures tracer SGS exchanges and execution.
components/homme/src/share/cxx/ComposeTransportImpl.hpp	Adds tracer SGS data and exchanges.
components/homme/src/share/control_mod.F90	Defines new namelist variables.
components/eamxx/tests/single-process/shoc/input.yaml	Supplies horizontal SHOC coefficients.
components/eamxx/src/physics/shoc/shoc_functions.hpp	Declares horizontal diffusivity support.
components/eamxx/src/physics/shoc/impl/shoc_eddy_diffusivities_impl.hpp	Implements horizontal diffusivities.
components/eamxx/src/physics/shoc/eamxx_shoc_process_interface.hpp	Extends SHOC process state.
components/eamxx/src/physics/shoc/eamxx_shoc_process_interface.cpp	Produces horizontal diffusivity fields.
components/eamxx/src/physics/shoc/disp/shoc_tke_disp.cpp	Updates the small-kernel strain input.
components/eamxx/src/dynamics/homme/eamxx_homme_process_interface.cpp	Couples horizontal diffusivities to HOMME.
components/eamxx/src/dynamics/homme/eamxx_homme_fv_phys.cpp	Remaps horizontal diffusivities for FV physics.
components/eamxx/src/control/atmosphere_driver.cpp	Synchronizes the HOMME and SHOC feature flag.
components/eamxx/docs/user/model_configuration.md	Documents the new controls.
components/eamxx/cime_config/namelist_defaults_eamxx.xml	Adds defaults and process parameters.
components/eamxx/cime_config/eamxx_buildnml.py	Synchronizes flags and fallback subcycling values.

---

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

[bogensch]

All copilot revisions have been addressed. This PR is ready for a human review.

[bogensch]

NLFAILs expected due to the addition of several new namelist variables.

[bartgol]

I'll merge on Mon and submit bless req