documentation updates (#721)

* Update InputsOutputs.rst, Codeoverview * Stampede update (#15) * Fix build env setup in Chapter 3 (#16) * cleanup and reorg of 2.2 Directory Structure Co-authored-by: BinLi-NOAA <[email protected]> Co-authored-by: jiandewang <[email protected]> Co-authored-by: Ali.Abdolali <[email protected]> Co-authored-by: Ali Abdolali <[email protected]> Co-authored-by: Jun Wang <[email protected]> Co-authored-by: Minsuk Ji <[email protected]>
ufs-community · Aug 2, 2021 · 85fa626 · 85fa626
1 parent ddcd809
commit 85fa626
Show file tree

Hide file tree

Showing 9 changed files with 929 additions and 146 deletions.
diff --git a/doc/UsersGuide/source/BuildingAndRunning.rst b/doc/UsersGuide/source/BuildingAndRunning.rst
@@ -119,44 +119,38 @@ For the ufs-weather-model ATM app (standalone ATM):
 
 .. code-block:: console
 
-    export CMAKE_FLAGS="-DAPP=ATM"
-    export CCPP_SUITES="FV3_GFS_v16"
+    export CMAKE_FLAGS="-DAPP=ATM -DCCPP_SUITES=FV3_GFS_v16"
 
 For the ufs-weather-model ATM app (standalone ATM) in 32 bit:
 
 .. code-block:: console
 
-    export CMAKE_FLAGS="-DAPP=ATM -D32BIT=ON"
-    export CCPP_SUITES="FV3_GFS_v16"
+    export CMAKE_FLAGS="-DAPP=ATM -D32BIT=ON -DCCPP_SUITES=FV3_GFS_v16"
 
 For the ufs-weather-model ATMW app (standalone ATM with wave):
 
 .. code-block:: console
 
-    export CMAKE_FLAGS="-DAPP=ATMW"
-    export CCPP_SUITES="FV3_GFS_v16"
+    export CMAKE_FLAGS="-DAPP=ATMW -DCCPP_SUITES=FV3_GFS_v16"
 
 For the ufs-weather-model S2S app (atm/ice/ocean):
 
 .. code-block:: console
 
-    export CMAKE_FLAGS="-DAPP=S2S"
-    export CCPP_SUITES="FV3_GFS_2017_coupled,FV3_GFS_2017_satmedmf_coupled,FV3_GFS_v15p2_coupled,FV3_GFS_v16_coupled,FV3_GFS_v16_couplednsst"
+    export CMAKE_FLAGS="-DAPP=S2S -DCCPP_SUITES=FV3_GFS_2017_coupled,FV3_GFS_2017_satmedmf_coupled,FV3_GFS_v15p2_coupled,FV3_GFS_v16_coupled,FV3_GFS_v16_couplednsst"
 
 For the ufs-weather-model S2S app (atm/ice/ocean) with debugging flags turned on, with verbose build messages:
 
 .. code-block:: console
 
-    export CMAKE_FLAGS="-DAPP=S2S -DDEBUG=ON"
-    export CCPP_SUITES="FV3_GFS_2017_coupled,FV3_GFS_2017_satmedmf_coupled,FV3_GFS_v15p2_coupled,FV3_GFS_v16_coupled,FV3_GFS_v16_couplednsst"
+    export CMAKE_FLAGS="-DAPP=S2S -DDEBUG=ON -DCCPP_SUITES=FV3_GFS_2017_coupled,FV3_GFS_2017_satmedmf_coupled,FV3_GFS_v15p2_coupled,FV3_GFS_v16_coupled,FV3_GFS_v16_couplednsst"
     export BUILD_VERBOSE=1
 
 For the ufs-weather-model S2SW app (atm/ice/ocean/wave):
 
 .. code-block:: console
 
-    export CMAKE_FLAGS="-DAPP=S2SW"
-    export CCPP_SUITES="FV3_GFS_2017_coupled,FV3_GFS_v15p2_coupled,FV3_GFS_v16_coupled,FV3_GFS_v16_coupled_noahmp"
+    export CMAKE_FLAGS="-DAPP=S2SW -DCCPP_SUITES=FV3_GFS_2017_coupled,FV3_GFS_v15p2_coupled,FV3_GFS_v16_coupled,FV3_GFS_v16_coupled_noahmp"
 
 ------------------
 Building the model

diff --git a/doc/UsersGuide/source/CodeOverview.rst b/doc/UsersGuide/source/CodeOverview.rst
@@ -20,12 +20,8 @@ The ufs-weather-model repository supports the short- and medium-range UFS applic
     - Authoritative repository URL
   * - Umbrella repository for the UFS Weather Model
     - https://github.com/ufs-community/ufs-weather-model
-  * - Infrastructure: Flexible Modeling System
-    - https://github.com/NOAA-GFDL/FMS
   * - Infrastructure: NOAA Environmental Modeling System
     - https://github.com/NOAA-EMC/NEMS
-  * - Infrastructure: Utilities
-    - https://github.com/NOAA-EMC/NCEPLIBS-pyprodutil
   * - Framework to connect the CCPP library to a host model
     - https://github.com/NCAR/ccpp-framework
   * - CCPP library of physical parameterizations
@@ -36,6 +32,18 @@ The ufs-weather-model repository supports the short- and medium-range UFS applic
     - https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere
   * - Stochastic physics pattern generator
     - https://github.com/noaa-psd/stochastic_physics
+  * - Modular Ocean Model (MOM6)
+    - https://github.com/NOAA-EMC/MOM6
+  * - Los Alamos sea ice model (CICE6)
+    - https://github.com/NOAA-EMC/CICE
+  * - NOAA/NCEP WAVEWATCH III Model (WW3)
+    - https://github.com/NOAA-EMC/WW3
+  * - NUOPC Community Mediator for Earth Prediction Systems (CMEPS)
+    - https://github.com/NOAA-EMC/CMEPS
+  * - Community Data Models for Earth Prediction Systems (CDEPS)
+    - https://github.com/NOAA-EMC/CDEPS
+
+.. TODO:: GOCART information in progress
 
 In the table, the left column contains a description of each repository, and the right column shows the component repositories which are pointing to (or will point to) the authoritative repositories. The ufs-weather-model currently uses git submodule to manage the sub-components.
 
@@ -44,32 +52,37 @@ The umbrella repository for the UFS Weather Model is named ufs-weather-model.  U
 .. code-block:: console
 
    ufs-weather-model/
-   ├── FMS                                     https://github.com/NOAA-GFDL/FMS
    ├── FV3                                     https://github.com/NOAA-EMC/fv3atm
    │   ├── atmos_cubed_sphere                  https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere
    │   ├── ccpp
    │   │   ├── framework                       https://github.com/NCAR/ccpp-framework
    │   │   ├── physics                         https://github.com/NCAR/ccpp-physics
    ├── NEMS                                    https://github.com/NOAA-EMC/NEMS
-   │   └── tests/produtil/NCEPLIBS-pyprodutil  https://github.com/NOAA-EMC/NCEPLIBS-pyprodutil
    ├── stochastic_physics                      https://github.com/noaa-psd/stochastic_physics
-
+   ├── MOM6-interface
+   │    └── MOM6                               https://github.com/NOAA-EMC/MOM6
+   ├── CICE-interface
+   │    └── CICE                               https://github.com/NOAA-EMC/CICE
+   ├── WW3                                     https://github.com/NOAA-EMC/WW3
+   ├── CMEPS-interface
+   │    └── CMEPS                              https://github.com/NOAA-EMC/CMEPS
+   ├── CDEPS-interface
+   │    └── CDEPS                              https://github.com/NOAA-EMC/CDEPS
+   
 ===================
 Directory Structure
 ===================
 
 When the ufs-weather-model is cloned, the basic directory structure will be similar to the example below. Files and some directories have been removed for brevity.
 
+
 .. code-block:: console
 
    ufs-weather-model/
-   ├── cmake               --------- cmake configuration files
-   ├── compsets            --------- configurations used by some regression tests
-   ├── conf                --------- compile options for Tier 1 and 2 platforms
-   ├── doc                 --------- READMEs with build, reg-test hints
-   ├── FMS                 --------- The Flexible Modeling System (FMS),a software framework
-   ├── FV3                 --------- FV3 atmosphere model
-   │   ├── atmos_cubed_sphere   ---- FV3 dynamic core
+   ├── cmake                -------- cmake configuration files
+   ├── doc                  -------- User Guide files
+   ├── FV3                  -------- UFSAtm atmosphere model
+   │   ├── atmos_cubed_sphere ------ FV3 dynamic core
    │   │   ├── docs
    │   │   ├── driver
    │   │   ├── model
@@ -81,22 +94,33 @@ When the ufs-weather-model is cloned, the basic directory structure will be simi
    │   │   ├── physics      -------- CCPP compliant physics schemes
    │   │   └── suites       -------- CCPP physics suite definition files (SDFs)
    │   ├── cpl              -------- Coupling field data structures
-   │   ├── gfsphysics
-   │   │   ├── CCPP_layer
-   │   │   ├── GFS_layer
-   │   │   └── physics     --------- unused - IPD version of physics codes
-   │   ├── io              --------- FV3 write grid comp code
-   │   ├── ipd             --------- unused - IPD driver/interfaces
-   |   ├── stochastic_physics  ----- Cmakefile for stochastic physics code
-   ├── log                 --------- log files from NEMS compset regression tests
-   ├── modulefiles         --------- system module files for supported HPC systems
-   ├── NEMS                --------- NOAA Earth Modeling System framework
-   │   ├── exe
-   │   ├── src
-   │   └── test
-   ├── parm                --------- regression test configurations
+   │   ├── io               -------- UFSAtm write grid comp code
+   │   └── stochastic_physics ------ Wrapper for stochastic physics
+   │
+   ├── NEMS                 -------- NOAA Earth Modeling System framework
    ├── stochastic_physics   -------- stochastic physics pattern generator
-   ├── tests               --------- regression test scripts
+   ├── MOM6-interface
+   │    └── MOM6
+   │        ├── src                              --------- MOM6 ocean model
+   │        └── config_source/drivers/nuopc_cap  --------- NUOPC MOM6 cap
+   ├── CICE-interface
+   │    └── CICE                                 --------- CICE6 sea ice model
+   │        ├── icepack                          --------- Sea ice column physics
+   │        └── cicecore/drivers/nuopc/cmeps     --------- NUOPC CICE6 cap
+   ├── WW3
+   │    └── model                                --------- WW3 model
+   │        └── esmf                             --------- NUOPC WW3 cap
+   ├── CDEPS-interface
+   │     └── CDEPS
+   │         └── datm                            --------- CDEPS DATM
+   │
+   ├── modulefiles          -------- system module files for supported HPC systems
+   ├── tests                -------- regression test infrastructure
+   │   └── parm
+   │   └── tests
+   │   └── fv3_conf
+   
+.. TODO:: GOCART information in progress
 
 The physics subdirectory in the *gfsphysics* directory  is not used or supported
 as part of this release (all physics is available through the :term:`CCPP` using

diff --git a/doc/UsersGuide/source/InputNML.inc b/doc/UsersGuide/source/InputNML.inc
@@ -5,7 +5,7 @@
 .. _InputNML:
 
 ---------------------------
-Namelist file ``input.nml``
+Namelist file *input.nml*
 ---------------------------
 
 The atmosphere model reads many parameters from a Fortran namelist file, named *input.nml*.  This file contains
@@ -31,6 +31,7 @@ https://noaa-emc.github.io/FV3_Dycore_ufs-v1.1.0/html/index.html
 The namelist section ``&interpolator_nml`` is not used in this release, and any modifications to
 it will have no effect on the model results.
 
+----------
 fms_io_nml
 ----------
 
@@ -57,7 +58,7 @@ The namelist variables used in ``&fms_io_nml`` are described in :numref:`Table %
      - logical
      - .true.
    * - fms_netcdf_restart
-     - If true, all modules using restart files will operate under netCDF mode.  If false, all modules using restart files will operate under binary mode.  This flag is effective only when ``fms_netcdf_override`` is .true. When ``fms_netcdf_override`` is .false., individual module setting takes over. 
+     - If true, all modules using restart files will operate under netCDF mode.  If false, all modules using restart files will operate under binary mode.  This flag is effective only when ``fms_netcdf_override`` is .true. When ``fms_netcdf_override`` is .false., individual module setting takes over.
      - logical
      - .true.
    * - threading_read
@@ -85,7 +86,7 @@ The namelist variables used in ``&fms_io_nml`` are described in :numref:`Table %
      - integer
      - 40
    * - time_stamp_restart
-     -  If true, ``time_stamp`` will be added to the restart file name as a prefix. 
+     -  If true, ``time_stamp`` will be added to the restart file name as a prefix.
      - logical
      - .true.
    * - print_chksum
@@ -115,6 +116,7 @@ This release of the UFS Weather Model sets the following variables in the ``&fms
      max_files_w = 100
    /
 
+------
 namsfc
 ------
 
@@ -126,7 +128,7 @@ The variables used in ``&namsfc`` to set the filenames are described in :numref:
 
 .. list-table:: *List of common variables in the *namsfc* namelist section used to set the filenames of
                 static datasets.*
-   :widths: 15 40 15 20 
+   :widths: 15 40 15 20
    :header-rows: 1
 
    * - Variable Name
@@ -234,6 +236,7 @@ A sample subset of this namelist is shown below:
 Additional variables for the ``&namsfc`` namelist can be found in the ``FV3/ccpp/physics/physics/sfcsub.F``
 file.
 
+---------------
 atmos_model_nml
 ---------------
 
@@ -242,7 +245,7 @@ The variables used in ``&atmos_model_nml`` are described in :numref:`Table %s <a
 
 .. _atmos_model_nml:
 
-.. list-table:: *List of common variables in the *atmos_model_nml* namelist section. 
+.. list-table:: *List of common variables in the *atmos_model_nml* namelist section.
    :widths: 10 40 15 15
    :header-rows: 1
 
@@ -263,7 +266,7 @@ The variables used in ``&atmos_model_nml`` are described in :numref:`Table %s <a
      - .false.
    * - dycore_only
      - If true, only the dynamical core (and not the GFS physics) is executed when running the model,
-       essentially running the model as a solo dynamical core. 
+       essentially running the model as a solo dynamical core.
      - logical
      - .false.
    * - debug
@@ -274,35 +277,13 @@ The variables used in ``&atmos_model_nml`` are described in :numref:`Table %s <a
      - If true, initialize timing identifiers.
      - logical
      - .false.
-   * - fdiag
-     - Array with dimension ``maxhr`` = 4096 listing the diagnostic output times (in hours) for the GFS physics.
-       This can either be a list of times after initialization, or an interval if only the first entry is
-       nonzero. The default setting of 0 will result in no outputs.
-     - real
-     - 0.
-   * - fhmax
-     - The maximal forecast time for output.
-     - real
-     - 384.0
-   * - fhmaxhf
-     - The maximal forecast hour for high frequency output.
-     - real
-     - 120.0
-   * - fhout
-     - Output frequency during forecast time from 0 to ``fhmax``, or from ``fhmaxhf`` to ``fhmax`` if ``fhmaxf>0``.
-     - real
-     - 3.0
-   * - fhouthf
-     - The high frequency output frequency during the forecast time from 0 to ``fhmaxhf`` hour.
-     - real
-     - 1.0
    * - ccpp_suite
      - Name of the CCPP physics suite
      - character(len=256)
      - FV3_GFS_v15p2, set in ``build.sh``
    * - avg_max_length
      - Forecast interval (in seconds) determining when the maximum values of diagnostic fields in FV3
-       dynamics are computed. 
+       dynamics are computed.
      - real
      - 3600.
 
@@ -314,11 +295,6 @@ A sample of this namelist is shown below:
      blocksize = 32
      chksum_debug = .false.
      dycore_only = .false.
-     fdiag = 1
-     fhmax = 384
-     fhout = 3
-     fhmaxhf = 120
-     fhouthf = 1
      ccpp_suite = 'FV3_GFS_v16beta'
    /