diff --git a/Docs/sphinx_doc/Inputs.rst b/Docs/sphinx_doc/Inputs.rst index 30a7a67ccc..4ebad46387 100644 --- a/Docs/sphinx_doc/Inputs.rst +++ b/Docs/sphinx_doc/Inputs.rst @@ -26,6 +26,14 @@ Governing Equations | | all amr levels) or a list of| | | | | values (one per level) | | | +--------------------------+-----------------------------+---------------+-------------+ +| **erf.buoyancy_type** | Controls how buoyancy is | 1, 2, 3, 4 | 1 (may be | +| | calculated: 1=density | | auto-set to | +| | perturbation, 2/3=temp. | | 2 or 3 based| +| | perturbation, 4=potential | | on moisture | +| | temp. perturbation. | | and solver) | +| | See :ref:`Buoyancy` for | | | +| | details | | | ++--------------------------+-----------------------------+---------------+-------------+ | **erf.use_fft** | use FFT rather than | true / false | false | | | multigrid to solve the | | | | | the Poisson equations | | | @@ -837,7 +845,7 @@ List of Parameters +===================================+==================+================+================+ | **erf.line_sampling_interval**, | Output | Integer | -1 | | **erf.plane_sampling_interval** | frequency (steps)| | | -+===================================+==================+================+================+ ++-----------------------------------+------------------+----------------+----------------+ | **erf.line_sampling_per**, | Output | Real | -1 | | **erf.plane_sampling_per** | frequency (time) | | | +-----------------------------------+------------------+----------------+----------------+ @@ -1100,7 +1108,9 @@ List of Parameters | | | Values | | +=========================================+====================+=====================+=============+ | **erf.pbl_type** | Name of PBL Scheme | "None", "MYNN25", | "None" | -| | to be used | "YSU" | | +| | to be used | "MYNNEDMF", "MYJ", | | +| | | "YSU", "MRF", | | +| | | "SHOC" | | +-----------------------------------------+--------------------+---------------------+-------------+ | **erf.pbl_mynn_A1** | MYNN Constant A1 | Real | 1.18 | +-----------------------------------------+--------------------+---------------------+-------------+ @@ -1232,6 +1242,11 @@ List of Parameters | | delimited | | | | | columns) | | | +-------------------------------------+------------------------+-------------------+---------------------+ +| **erf.windfarm_type** | Wind farm | "None", | "None" | +| | parameterization | "Fitch", "EWP", | | +| | | "SimpleActuator", | | +| | | "GeneralActuator" | | ++-------------------------------------+------------------------+-------------------+---------------------+ | **erf.const_massflux_u** | Include a momentum | Real | 0. | | **erf.const_massflux_v** | source at each time, | | | | | (e.g., representing a | | | @@ -1372,6 +1387,8 @@ function(s). Note that ``erf.add_custom_geostrophic_profile`` cannot be used in combination with an ``erf.abl_geo_wind_table``. +- Wind farm parameterization requires ``USE_WINDFARM=TRUE`` at build time. See :ref:`WindFarmModels` for theory and examples. + Numerical Stability =================== @@ -1661,6 +1678,53 @@ Examples of Usage with the (x,y) values we have just read in. Note that the z-values are in the order z(x1,y1), z(x1,y2), z(x1,y3), ... which is contrary to standard Fortran ordering +Land Surface Model +================== + +The land surface model provides energy and moisture fluxes at the lower boundary. + +List of Parameters +------------------ + ++--------------------------------+----------------------------+--------------------+-------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++================================+============================+====================+=============+ +| **erf.land_surface_model** | Enables land surface | "None", | "None" | +| | energy and moisture | "Noah-MP", | | +| | fluxes | "MM5", "SLM" | | ++--------------------------------+----------------------------+--------------------+-------------+ + +.. note:: + + Noah-MP requires ``USE_NOAHMP=TRUE`` at build time. See :ref:`CouplingToNoahMP` for details. + +Coupling Type (Data Exchange) +============================== + +For coupled simulations with AMR-Wind or WaveWatch3, this controls the directionality of data exchange. + + +List of Parameters +------------------ + ++--------------------------------+----------------------------+--------------------+-------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++================================+============================+====================+=============+ +| **erf.coupling_type** | Coupling mode for | "OneWay", | "None" | +| | coupled simulations with | "TwoWay" | | +| | AMR-Wind or WaveWatch3 | | | ++--------------------------------+----------------------------+--------------------+-------------+ + +Notes +----- + +- **TwoWay**: Bidirectional coupling - ERF both receives and sends data +- **OneWay**: ERF receives forcing but doesn't send data back + +See :ref:`CouplingToAMRWind` and :ref:`CouplingToWW3` for more information. + Moisture ======== @@ -1683,7 +1747,7 @@ List of Parameters | | | "Morrison", | | | | | "Morrison_NoIce", | | | | | "SAM_NoPrecip_NoIce",| | -| | | "SAM_NoIce" | | +| | | "SAM_NoIce", "P3" | | +---------------------------------+--------------------------+-----------------------+------------+ | **erf.moisture_tight_coupling** | If true, advance | Bool | false | | | microphysics after every | | | @@ -1718,6 +1782,9 @@ List of Parameters | Parameter | Definition | Acceptable | Default | | | | Values | | +================================+==========================+====================+===================================+ +| **erf.radiation_model** | Enables radiation | "None", | "None" | +| | transfer calculations | "RRTMGP" | | ++--------------------------------+--------------------------+--------------------+-----------------------------------+ | **erf.rad_freq_in_steps** | Number of steps between | int | 1 | +--------------------------------+--------------------------+--------------------+-----------------------------------+ | **erf.rad_write_fluxes** | Flag to write fluxes | Bool | false | @@ -1753,6 +1820,10 @@ List of Parameters The lookup data may be downloaded as a package from `here `_. +.. note:: + + Using RRTMGP requires ``USE_RRTMGP=TRUE`` at build time. See :ref:`building` for build instructions. + Runtime Error Checking ====================== diff --git a/Docs/sphinx_doc/building.rst b/Docs/sphinx_doc/building.rst index f04eb65e07..46b6272a6d 100644 --- a/Docs/sphinx_doc/building.rst +++ b/Docs/sphinx_doc/building.rst @@ -252,6 +252,110 @@ Analogous to GNU Make, the list of cmake directives is as follows: .. note:: **At most one of ERF_ENABLE_OMP, ERF_ENABLE_CUDA, ERF_ENABLE_HIP and ERF_ENABLE_SYCL should be set to true.** +CMake Logging Options +~~~~~~~~~~~~~~~~~~~~~ + +ERF's CMake configuration supports hierarchical logging to help diagnose build issues and understand configuration decisions. These options are available with CMake 3.25+: + +Logging Levels +++++++++++++++ + +The ``--log-level`` flag controls the verbosity of CMake output: + +.. code:: shell + + # Quiet output (STATUS messages only) + cmake .. + + # Show detection details + cmake --log-level=VERBOSE .. + + # Show all diagnostics + cmake --log-level=DEBUG .. + +Logging Context ++++++++++++++++ + +The ``--log-context`` flag shows the hierarchy of messages, making it easier to understand which component is reporting: + +.. code:: shell + + # Show message hierarchy with component names + cmake --log-context .. + + # Combine with verbose output for detailed diagnostics + cmake --log-context --log-level=VERBOSE .. + +Example output with ``--log-context``: + +:: + + [ERF.Cray] Detected Cray Programming Environment (CRAYPE_VERSION=2.7.30) + [ERF.Cray] Setting Cray compiler wrappers... + [ERF.Cray] Set CMAKE_CXX_COMPILER = /opt/cray/pe/craype/default/bin/CC + [ERF.AMReX] Using internal AMReX submodule + [ERF.NetCDF] Found NetCDF: /opt/cray/pe/netcdf/4.9.0.9 + +CMake Utility Targets +~~~~~~~~~~~~~~~~~~~~~ + +ERF provides several utility targets to help manage builds: + +Clean Build Artifacts ++++++++++++++++++++++ + +To perform a complete clean (equivalent to ``make distclean`` in GNU Make): + +.. code:: shell + + make distclean + +This removes all CMake configuration and build artifacts, including: + +- CMake cache and generated files (``CMakeCache.txt``, ``CMakeFiles/``, etc.) +- Build outputs (executables, libraries) +- Generated configuration files +- Test outputs + +The install directory is preserved. + +Uninstall ++++++++++ + +To uninstall files that were installed via ``make install`` or ``cmake --install``: + +.. code:: shell + + make uninstall + +Show Detected Configuration +++++++++++++++++++++++++++++ + +On Cray systems, you can view the auto-detected configuration: + +.. code:: shell + + make show-cray-config + +This displays the configuration that was automatically detected and can be saved to use as a starting point for manual configuration. + +Using Configuration Files +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On Cray systems, ERF automatically detects the system configuration and applies necessary workarounds. If you need to use a manual configuration, you can create a configuration file and use it with CMake's ``-C`` option: + +.. code:: shell + + cmake -C path/to/config.cmake .. + +ERF provides machine-specific profile examples in ``Build/machines/``: + +- ``perlmutter_erf.profile`` - NERSC Perlmutter (NVIDIA A100) +- ``frontier_erf.profile`` - OLCF Frontier (AMD MI250X) +- ``polaris_erf.profile`` - ALCF Polaris (NVIDIA A100) +- ``aurora_erf.profile`` - ALCF Aurora (Intel GPUs) + +These profiles show the recommended modules to load for each system. Mac with CMake ~~~~~~~~~~~~~~ @@ -298,13 +402,193 @@ ERF (tested with commit ``40e64ed35ebc080ad61d08aea828330dfbdbc162``) CMake Docs ~~~~~~~~~~ -Building the ERF documentation with Cmake can be completed by configuring with the flag ``-DERF_ENABLE_DOCUMENTATION:BOOL=ON`` and then compiling the following target: +Building the ERF documentation with CMake can be completed by configuring with the flag ``-DERF_ENABLE_DOCUMENTATION:BOOL=ON`` and then compiling the following target: .. code:: shell make docs -Note again that both the sphinx and doxygen documentation will be built. +Note again that both the Sphinx and Doxygen documentation will be built. + +Cray Systems +~~~~~~~~~~~~ + +ERF supports compilation on Cray systems with both automatic detection and manual configuration. + +.. note:: + + The machine profiles and some of the build documentation for HPC systems are inspired by and modeled after the excellent `WarpX HPC documentation `__. + +**Auto-Detection Control** + +The build system can automatically detect Cray environments. Control this with: + +- **Enable auto-detection** (default on Cray systems): ``-DCRAY_AUTO_DETECTION=ON`` +- **Disable auto-detection**: ``-DCRAY_AUTO_DETECTION=OFF`` + +**Using Cray CMake Configuration Files** + +If you have a Cray CMake configuration file (generated by your system or provided), use it with the ``-C`` flag: + +.. code:: shell + + cmake -C /path/to/cray_config.cmake \ + -DERF_ENABLE_CUDA:BOOL=ON \ + -DERF_ENABLE_MPI:BOOL=ON \ + .. + +**Generating a Cray Configuration File** + +You can generate a template Cray CMake configuration file by running: + +.. code:: shell + + make show-cray-config + +This will show a file ``cray_config.cmake`` in your build directory with detected Cray settings. You can then: + +1. Review the generated settings +2. Make any necessary adjustments for your specific system +3. Use it with ``cmake -C cray_config.cmake ...`` + +The generated file will include settings such as: + +.. code:: cmake + + set(CMAKE_C_COMPILER "cc") + set(CMAKE_CXX_COMPILER "CC") + set(CMAKE_Fortran_COMPILER "ftn") + set(MPI_C_COMPILER "cc") + set(MPI_CXX_COMPILER "CC") + # ... and other detected settings + +**How Auto-Detection Works** + +When ``CRAY_AUTO_DETECTION=ON``, the build system performs the following detection and configuration: + +**Compiler Detection:** + +- First checks if ``CRAYPE_DIR`` environment variable is set (indicates Cray environment) +- Sets compilers to Cray wrappers: ``cc``, ``CC``, and ``ftn`` +- Fallback: If Cray wrappers are not found, uses system default compilers (typically ``gcc``, ``g++``, ``gfortran``) +- Decision: If using Cray wrappers, automatically sets ``-DCMAKE_CXX_COMPILER_WRAPPER=CrayPrgEnv`` + +**MPI Configuration:** + +- Automatically sets MPI compilers to match the Cray wrappers (``cc`` and ``CC``) +- Checks for ``CRAY_MPICH_DIR`` environment variable to locate MPI libraries +- Fallback: Uses standard MPI detection via ``FindMPI`` if Cray MPICH is not found +- Decision: Prefers Cray MPICH over other MPI implementations when detected + +**CUDA Configuration:** + +- When ``ERF_ENABLE_CUDA=ON``, sets ``CMAKE_CUDA_HOST_COMPILER`` to the Cray C++ wrapper (``CC``) +- Looks for ``nvcc`` in standard locations and the ``CUDA_HOME`` environment variable +- Fallback: If ``nvcc`` is not in PATH, checks ``/usr/local/cuda/bin`` +- Decision: Always uses the Cray wrapper as the CUDA host compiler to ensure compatibility with the Cray programming environment + +**Linker Configuration:** + +- Detects the default linker used by the Cray wrappers +- On newer systems, may default to ``lld`` (LLVM linker) or the GNU linker +- Fallback: Uses the compiler's default linker if detection fails +- Override: Can be manually set with ``-DCMAKE_LINKER_TYPE=`` or ``-DCMAKE_LINKER_EXE=`` + +**Module System Integration:** + +- Checks for loaded Cray modules (e.g., ``PrgEnv-gnu``, ``PrgEnv-cray``, ``cudatoolkit``) +- Uses module environment variables (``CRAY_*_DIR``) to locate libraries +- Warning: Will warn if conflicting programming environments are loaded + +**Common Workarounds** + +- **MPI not found**: Manually set ``-DMPI_HOME=$CRAY_MPICH_DIR`` +- **CUDA math libraries not found**: Load the latest cmake module with ``module load cmake`` +- **Compiler version mismatch**: Verify module compatibility with ``module list`` and ensure only one programming environment is loaded +- **Linker errors**: Explicitly set the linker with ``-DCMAKE_LINKER_EXE=/path/to/ld`` + +Build Scripts Reference +~~~~~~~~~~~~~~~~~~~~~~~~ + +ERF provides several build scripts optimized for different systems and architectures. This table shows which scripts have been tested and verified on each system. Verified builds are marked with the git commit hash where they were last tested. + +.. list-table:: ERF Build Scripts by System + :header-rows: 1 + :widths: 35 10 10 10 10 10 10 10 + + * - Build Script + - Perlmutter + - Frontier + - Aurora + - Polaris + - Kestrel + - RegtestCPU + - RegtestGPU + * - ``cmake.sh`` + - Untested + - Untested + - Untested + - Untested + - Untested + - Untested + - Untested + * - ``cmake_with_kokkos_many.sh`` + - Untested + - Untested + - Untested + - Untested + - Untested + - Untested + - Untested + * - ``cmake_with_kokkos_many_cuda.sh`` + - Untested + - — + - — + - Untested + - Untested + - — + - Untested + * - ``cmake_with_kokkos_many_noradiation_hip.sh`` + - — + - Untested + - — + - — + - — + - — + - — + * - ``cmake_with_kokkos_many_sycl.sh`` + - — + - — + - Untested + - — + - — + - — + - — + * - ``Perlmutter/build_erf_with_shoc_cuda_Perlmutter.sh`` + - Untested + - Untested + - Untested + - Untested + - Untested + - — + - Untested + +.. note:: + + The ``build_erf_with_shoc_cuda_Perlmutter.sh`` script is being tested for cross-site compatibility with auto-detection enabled. A simplified version may work across CUDA-enabled HPC sites (Perlmutter, Polaris, Kestrel) with ``-DCRAY_AUTO_DETECTION=ON``. + +**Script Descriptions** + +- ``cmake.sh``: Basic CMake build script, works on all systems +- ``cmake_with_kokkos_many.sh``: Kokkos-enabled build for CPU architectures +- ``cmake_with_kokkos_many_cuda.sh``: Kokkos build optimized for NVIDIA GPUs +- ``cmake_with_kokkos_many_noradiation_hip.sh``: Kokkos build for AMD GPUs (HIP backend) +- ``cmake_with_kokkos_many_sycl.sh``: Kokkos build for Intel GPUs (SYCL backend) +- ``Perlmutter/build_erf_with_shoc_cuda_Perlmutter.sh``: SHOC turbulence model with CUDA support + +**Testing Build Scripts** + +Build scripts can be tested using the configuration file ``Build/ERF-cmake-tests.ini``, which defines test cases for each system and script combination. Perlmutter (NERSC) ~~~~~~~~~~~~~~~~~~ @@ -336,7 +620,13 @@ where ``/path_to_here`` is the path to your ERF repository. **Using the Provided CMake Build Scripts** -If you prefer to use one of the provided CMake build scripts, first load the following modules: +If you prefer to use one of the provided CMake build scripts, first load the appropriate machine profile: + +:: + + source Build/machines/perlmutter_erf.profile + +Or load the modules manually: :: @@ -345,6 +635,16 @@ If you prefer to use one of the provided CMake build scripts, first load the fol Note that the latest cmake module helps with finding the CUDA math libraries. The gcc version should be a gcc variant such as ``gcc/12.2.0`` that has been tested to reliably find the filesystem functionality used in some utilities. Also note that the ``cray-hdf5-parallel`` module matches with the parallel configuration requirements. Then build with one of the provided build scripts. We suggest using ``Build/cmake_cuda.sh`` for a basic CUDA build, or ``Build/cmake_with_netcdf.sh`` if you need NetCDF support. +With the flags listed explicitly instead of using -DCRAY_AUTO_DECTION=ON, we suggest using ``Build/Perlmutter/cmake_with_cuda_perlmutter.sh`` for a basic CUDA build, or ``Build/Perlmutter/build_erf_with_shoc_cuda_Perlmutter.sh `` if you need SHOC support. + +To use logging for diagnostics during configuration: + +:: + + cmake --log-context --log-level=VERBOSE \ + -DERF_ENABLE_CUDA:BOOL=ON \ + -DERF_ENABLE_MPI:BOOL=ON \ + .. && make **Submitting Jobs** diff --git a/Docs/sphinx_doc/theory/Buoyancy.rst b/Docs/sphinx_doc/theory/Buoyancy.rst index d82cc93648..81ec147655 100644 --- a/Docs/sphinx_doc/theory/Buoyancy.rst +++ b/Docs/sphinx_doc/theory/Buoyancy.rst @@ -1,21 +1,20 @@ +.. role:: cpp(code) + :language: c++ - .. role:: cpp(code) - :language: c++ - - .. role:: f(code) - :language: fortran +.. role:: f(code) + :language: fortran .. _Buoyancy: -ERF has several options for how to define the buoyancy force. - Buoyancy ========= -The following are a list of the buoyancy models available in ERF. All models may be employed +ERF has several options for how to define the buoyancy force. All models may be employed with the compressible formulation but those applicable to the anelastic formulation will be explicitly stated in the description. +The buoyancy formulation is selected via the ``erf.buoyancy_type`` parameter. See :ref:`sec:Inputs` +for available values and defaults. Density of the mixture ----------------------- @@ -39,9 +38,8 @@ Using this we can write where :math:`\rho_d \equiv \cfrac{m_a}{V}` is the density of dry air. - -Type 1 ------- +Type 1: Density Perturbation +----------------------------- One version of the buoyancy force is expressed simply as @@ -52,30 +50,46 @@ One version of the buoyancy force is expressed simply as \rho^\prime = \rho_{total} - \rho_0 where the total density :math:`\rho_{total} = \rho_d(1 + q_v + q_c + q_p)` is the sum of dry and moist components and :math:`\rho_0` is the total density -for the background state. For eg., a usual scenario is that of a background state that contains only air and vapor and no cloud water or precipitates. For such a state, +for the background state. For example, a usual scenario is that of a background state that contains only air and vapor and no cloud water or precipitates. For such a state, the total background density :math:`\rho_0 = \rho_{d_0}(1 + q_{v_0})`, where :math:`\rho_{d_0}` and :math:`q_{v_0}` are the background dry density and vapor mixing ratio respectively. As a check, we observe that :math:`\rho^\prime_0 = 0`, which means that the background state is not buoyant. -Type 3 ------- +This is the default formulation for both dry and certain moist simulations. + +Type 2/3: Temperature Perturbation +----------------------------------- + +**Note:** Types 2 and 3 are implemented identically in the code. + +For **dry** simulations, the buoyancy is: + +.. math:: + \mathbf{B} = -\rho_0 \mathbf{g} \frac{T'}{T_0} -This formulation of the buoyancy term assumes that the horizontal averages of the moisture quantities are negligible. +For **moist** simulations, this formulation assumes that the horizontal averages of the moisture quantities are negligible: .. math:: - \mathbf{B} = \rho^\prime \mathbf{g} \approx -\rho_0 \mathbf{g} ( \frac{T^\prime}{\overline{T}} - + 0.61 q_v - q_c - q_i - q_p) + \mathbf{B} = \rho^\prime \mathbf{g} \approx -\rho_0 \mathbf{g} \left( \frac{T^\prime}{\overline{T}} + + 0.61 q_v - q_c - q_i - q_p \right) We note that this version of the buoyancy force matches that given in Marat F. Khairoutdinov and David A. Randall's paper (J. Atm Sciences, 607, 1983) if we neglect :math:`\frac{p^\prime}{\bar{p_0}}`. -Type 4 ------- +Type 3 is utilized when the anelastic formulation is employed. A specialized implementation +based on dry potential temperature perturbations is used in the anelastic case. + +Type 4: Potential Temperature Perturbation +------------------------------------------- + This expression for buoyancy is from `khairoutdinov2003cloud`_ and `bryan2002benchmark`_. .. _`khairoutdinov2003cloud`: https://journals.ametsoc.org/view/journals/atsc/60/4/1520-0469_2003_060_0607_crmota_2.0.co_2.xml .. _`bryan2002benchmark`: https://journals.ametsoc.org/view/journals/mwre/130/12/1520-0493_2002_130_2917_absfmn_2.0.co_2.xml +For **dry** simulations: + .. math:: + \mathbf{B} = -\rho_0 \mathbf{g} \frac{\theta'}{\theta_0} \begin{equation} \mathbf{B} = \rho'\mathbf{g} \approx -\rho \mathbf{g} \Bigg(\frac{T'}{T} + 0.61 q_v' - q_c - q_p - \frac{p'}{p}\Bigg) @@ -124,14 +138,21 @@ Since the background values of cloud water and precipitate mass mixing ratios -- \rho'\approx -\rho\Bigg(\frac{T'}{T} + 0.61 q_v' - q_c - q_p - \frac{p'}{p}\Bigg), \end{equation} -Type 5 ------- +which gives the final expression for Type 4 moist buoyancy. + +Type 5: Anelastic Formulation (Internal Use Only) +-------------------------------------------------- + +.. note:: + Type 5 is not user-selectable via ``erf.buoyancy_type``. It describes the specialized + buoyancy implementation used internally when the anelastic formulation is enabled. + Utilizing :math:`\theta_d` and neglecting the pressure term in Type 4 leads to: .. math:: \begin{equation} - \rho'\approx -\rho\Bigg(\frac{\theta_d'}{\theta} + 0.61 q_v' - q_c' - q_p'\Bigg). + \rho'\approx -\rho\left(\frac{\theta_d'}{\theta} + 0.61 q_v' - q_c' - q_p'\right). \end{equation} -We note that this buoyancy model is employed when utilizing the anelastic formulation. +This buoyancy model is employed when utilizing the anelastic formulation. diff --git a/Docs/sphinx_doc/theory/Microphysics.rst b/Docs/sphinx_doc/theory/Microphysics.rst index dad137e25c..5d3ca8b638 100644 --- a/Docs/sphinx_doc/theory/Microphysics.rst +++ b/Docs/sphinx_doc/theory/Microphysics.rst @@ -38,6 +38,9 @@ Model overview and transported quantities in ERF | Double moment | ``Morrison`` | :math:`q_i` | :math:`q_r` | :math:`q_s` | :math:`q_g` | | | | | | | | +--------------------+------------------------+-------------+-------------+-------------+-------------+ +| Predicted Particle | ``P3`` | :math:`q_i` | :math:`q_r` | :math: | -- | +| Properties | | | | `q_{rim}` | | ++--------------------+------------------------+-------------+-------------+-------------+-------------+ Kessler Microphysics model @@ -213,3 +216,22 @@ Saturation Adjustment (SatAdj) Microphysics Model ------------------------------------------------- The saturation adjustment microphysics model is the simplest possible moisture model and only transports the water vapor mixing ratio, :math:`q_v`, and the cloud water mixing ration, :math:`q_c`. Evaporation, :math:`q_v \longrightarrow q_c`, and condensation, :math:`q_c \longrightarrow q_v`, are the only relevant mechanisms. The final saturation state, :math:`q_v = q_{vs}(T)` is obtained from Newton-Raphson iterations on the thermal temperature :math:`T`. + +Predicted Particle Properties (P3) Microphysics Model +------------------------------------------------------ + +The P3 microphysics scheme uses a fundamentally different approach than traditional bulk schemes. +Rather than using fixed hydrometeor categories (ice, snow, graupel), P3 predicts evolving ice particle +properties, allowing continuous transitions from unrimed ice to heavily rimed particles. + +P3 transports water vapor (:math:`q_v`), cloud water (:math:`q_c`), rain (:math:`q_r`), total ice mass +(:math:`q_i`), and rime mass (:math:`q_{rim}`). Additional prognostic variables include ice number +concentration and rime volume. + +The scheme represents physical processes including vapor deposition/sublimation, riming, aggregation, +melting, and sedimentation. Particle properties evolve continuously based on environmental conditions +and microphysical processes. + +.. P3 requires ``USE_P3=TRUE`` at build time and interfaces with E3SM's P3 implementation. + +For details, see Morrison and Milbrandt (2015, *J. Atmos. Sci.*, 72, 287–311). diff --git a/Docs/sphinx_doc/theory/PBLschemes.rst b/Docs/sphinx_doc/theory/PBLschemes.rst index ca0c6ba8f0..53eeffd015 100644 --- a/Docs/sphinx_doc/theory/PBLschemes.rst +++ b/Docs/sphinx_doc/theory/PBLschemes.rst @@ -20,9 +20,9 @@ for any quantity :math:`\phi`). PBL schemes may be used in conjunction with an LES model that specifies horizontal turbulent transport, in which case the vertical component of the LES model is ignored. -Right now, the only PBL scheme supported in ERF is the Mellor-Yamada-Nakanishi-Niino -Level 2.5 model, largely matching the original forumulation proposed by Nakanishi and -Niino in a series of papers from 2001 to 2009. +Right now, ERF supports several PBL schemes: MYNN Level 2.5, MYJ, SHOC, MRF, and YSU. + +The MYNN Level 2.5 model is the Mellor-Yamada-Nakanishi-Niino Level 2.5 model, largely matching the original forumulation proposed by Nakanishi and Niino in a series of papers from 2001 to 2009. .. _MYNN25: @@ -121,8 +121,94 @@ the implementation of MYNN PBL models in ERF. MYNN-EDMF Level 2.5 PBL Model ----------------------------- +.. warning:: + + Implementation is in progress with basic support. + More recent advancements that add significant complexity to the MYNN scheme have been incorporated into WRF, as described in Olson et al. 2019. These advancements are not included in ERF, but may be in the future. +.. _MYJ: + +MYJ PBL Model +------------- + +.. warning:: + + Implementation is in progress with basic support. + +The Mellor-Yamada-Janjic (MYJ) scheme is a 1.5-order turbulence closure that solves +a prognostic equation for turbulent kinetic energy (TKE). It uses a local closure approach +with no counter-gradient terms, making it particularly effective for stable and neutral boundary layers. + +The turbulent fluxes are computed using gradient diffusion: + +.. math:: + \overline{w'\phi'} = -K_\phi \frac{\partial \phi}{\partial z} + +The vertical turbulent transport coefficients are computed from TKE and a master length scale: + +.. math:: + K_{m,v} = \rho L q S_m, \quad K_{\theta,v} = \rho L q S_h, \quad K_{q,v} = \rho L q S_h + +where :math:`q = \sqrt{2\cdot\text{TKE}}`, :math:`L` is the master length scale, and +:math:`S_m`, :math:`S_h` are stability functions that account for buoyancy effects and depend on +the gradient Richardson number. The master length scale :math:`L` is diagnosed based on the +PBL height, von Kármán's constant, and height above the surface within the PBL, transitioning +to a local mixing length in the free atmosphere. + +The prognostic TKE equation includes production by shear and buoyancy, and dissipation: + +.. math:: + \frac{\partial \text{TKE}}{\partial t} + \nabla \cdot (\mathbf{u} \text{TKE}) + = P_s + P_b - \epsilon + \nabla \cdot (K_q \nabla \text{TKE}) + +where :math:`P_s` is shear production, :math:`P_b` is buoyancy production, and +:math:`\epsilon` is dissipation. + +Closure coefficients are taken from Janjić (2002) NCEP Office Note 437. The implementation in ERF follows Janjić (1994, 2002) and uses the Mellor-Yamada (1982) length scale formulation. + +References +~~~~~~~~~~ + +* Janjić, Z. I. (1994): "The Step-Mountain Eta Coordinate Model: Further developments + of the convection, viscous sublayer, and turbulence closure schemes", + *Monthly Weather Review*, 122(5), 927-945. +* Janjić, Z. I. (2002): "Nonsingular implementation of the Mellor-Yamada Level 2.5 Scheme + in the NCEP Meso model", NCEP Office Note No. 437. +* Mellor, G. L., & Yamada, T. (1982): "Development of a turbulence closure model for + geophysical fluid problems", *Reviews of Geophysics*, 20(4), 851-875. + +.. _SHOC: + +SHOC PBL Model +-------------- + +.. warning:: + + Implementation is in progress with basic support. + +The Simplified Higher-Order Closure (SHOC) is a unified parameterization that represents +both turbulent mixing and shallow convection in a single framework. Originally developed for +the Community Atmosphere Model (CAM) and now used in E3SM, SHOC uses prognostic TKE with +diagnostic second and third-order moments and assumed probability density functions (PDFs) +to represent subgrid-scale variability. + +SHOC computes vertical turbulent fluxes for momentum, heat, and moisture, along with +subgrid-scale cloud fraction and liquid water content. The assumed PDFs allow the scheme +to predict partial cloudiness and transitions between clear and cloudy conditions. The +implementation uses higher-order closure equations to diagnose eddy diffusivities and +turbulent fluxes, with special treatment for cloud-top entrainment. + +References +~~~~~~~~~~ + +* Golaz, J.-C., et al. (2002): "A PDF-based model for boundary layer clouds. Part I: + Method and model description", *Journal of the Atmospheric Sciences*, 59(24), 3540-3551. +* Bogenschutz, P. A., & Krueger, S. K. (2013): "A simplified PDF parameterization of + subgrid-scale clouds and turbulence for cloud-resolving models", + *Journal of Advances in Modeling Earth Systems*, 5(2), 195-211. +* E3SM SHOC Documentation: https://github.com/E3SM-Project/E3SM/tree/master/components/eamxx/src/physics/shoc + .. _MRFPBL: MRF PBL Model