Skip to content

Commit

Permalink
documentation updates (#721)
Browse files Browse the repository at this point in the history 
* 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 <bin.li@noaa.gov>
Co-authored-by: jiandewang <jiande.wang@noaa.gov>
Co-authored-by: Ali.Abdolali <37336972+aliabdolali@users.noreply.github.com>
Co-authored-by: Ali Abdolali <ali.abdolali@noaa.gov>
Co-authored-by: Jun Wang <junwang-noaa@users.noreply.github.com>
Co-authored-by: Minsuk Ji <57227195+MinsukJi-NOAA@users.noreply.github.com>
  • Loading branch information
@DeniseWorthen @binli2337
@jiandewang @aliabdolali @junwang-noaa @MinsukJi-NOAA
7 people authored Aug 2, 2021
1 parent ddcd809 commit 85fa626
Show file tree
Hide file tree
Showing 9 changed files with 929 additions and 146 deletions.
18 changes: 6 additions & 12 deletions doc/UsersGuide/source/BuildingAndRunning.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
82 changes: 53 additions & 29 deletions doc/UsersGuide/source/CodeOverview.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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
Expand Down
44 changes: 10 additions & 34 deletions doc/UsersGuide/source/InputNML.inc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
----------

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -115,6 +116,7 @@ This release of the UFS Weather Model sets the following variables in the ``&fms
max_files_w = 100
/

------
namsfc
------

Expand All @@ -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
Expand Down Expand Up @@ -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
---------------

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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'
/

Expand Down
Loading

0 comments on commit 85fa626

Please sign in to comment.