Add ERF-native SHOC PBL parameterization

[pressel]

Summary

This PR adds an ERF-native implementation of the Simplified Higher-Order Closure (SHOC) turbulence and cloud parameterization.

The native implementation lives in Source/PBL/Shoc. It is based on the E3SM/EAMxx SHOC algorithms and source structure, but it is adapted to ERF data structures, AMReX loops, ERF surface-flux coupling, diagnostics, and build systems. It is not a bit-for-bit port of EAMxx SHOC.

Users select the native path at runtime with:

zlo.type = "surface_layer"
erf.pbl_type = NATIVE_SHOC

The optional EAMxx SHOC interface remains available through:

erf.pbl_type = EAMXX_SHOC

The legacy runtime name SHOC now maps to EAMXX_SHOC with a deprecation warning.

What changed

• Added the ERF-native SHOC driver, column data structures, preprocessing, TKE diagnostics, moment diagnostics, assumed-PDF cloud diagnostics, implicit update path, energy fixer, diagnostics, and ERF coupling code.
• Added NATIVE_SHOC and EAMXX_SHOC runtime names.
• Kept legacy SHOC as a deprecated alias for EAMXX_SHOC.
• Made native SHOC an in-tree ERF implementation that is always built, but only runs when selected at runtime.
• Kept EAMxx SHOC as an optional external dependency.
• Added SHOC-family runtime helpers so shared code can distinguish native SHOC, EAMxx SHOC, and non-SHOC cases.
• Updated time integration, turbulence, microphysics, diffusion, plotfile, and profile-output coupling for the native SHOC path.
• Added native SHOC plotfile diagnostics.
• Added native SHOC unit tests and fixture data.
• Added native SHOC Sphinx documentation and a developer README.

Coupling behavior

Native SHOC receives lower-boundary heat, moisture, and momentum fluxes through ERF's surface-layer infrastructure. These fluxes may come from Monin-Obukhov similarity theory, prescribed surface-layer inputs, or an active land or ocean surface model when that model provides fluxes.

SHOC diagnoses subgrid non-precipitating cloud partitioning with its assumed PDF. To avoid double counting, ERF suppresses the saturation-adjustment or condensation step in the microphysics package when a SHOC-family PBL scheme is active. This does not disable microphysics. Microphysics still handles precipitating processes outside SHOC's cloud macrophysics role.

User-facing notes

Native SHOC is selected at runtime:

erf.pbl_type = NATIVE_SHOC

It does not require EAMxx, EKAT, or Kokkos.

Native SHOC requires the lower boundary to use ERF's surface-layer boundary condition:

zlo.type = "surface_layer"

Native SHOC is column based. Like ERF's other column physics, it requires each AMReX box on a SHOC-active level to span the full vertical domain. Z-split boxes are not supported.

Native SHOC supports two transport modes:

erf.shoc.transport_mode = tendencies
erf.shoc.transport_mode = host_diffusion

The default is tendencies.

Documentation

This PR updates:

• Docs/sphinx_doc/theory/PBLschemes.rst
• Docs/sphinx_doc/buildingLibraryConfig.rst
• Docs/sphinx_doc/buildingSystems.rst
• Source/PBL/Shoc/README.md

The docs describe runtime selection, build behavior, runtime options, diagnostics, surface-flux coupling, microphysics coupling, and the full-column grid requirement.

Reviewer notes

The most important review areas are:

• Runtime separation between NATIVE_SHOC, EAMXX_SHOC, and non-SHOC cases.
• Coupling between SHOC, surface-layer fluxes, and microphysics condensation adjustment.
• Native SHOC diagnostics and plotfile behavior.
• Full-column grid requirements and user-facing error messages.
• CMake and GNUmake handling of native SHOC versus optional EAMxx SHOC.
• Unit-test coverage for native SHOC kernels and driver behavior.

This PR does not update regression gold files.

This PR does not add a generalized portability checker.

Testing

Please update this section with final local or CI results before merging.

Suggested validation:

ctest --test-dir <build-dir> -L shoc --output-on-failure
ctest --test-dir <build-dir> -L unit --output-on-failure
ctest --test-dir <build-dir> -R "SquallLine_2D|SuperCell_3D" --output-on-failure

Also validate the Sphinx docs build if the docs environment is available.