diff --git a/doc/UsersGuide/Makefile b/doc/UsersGuide/Makefile index 2b79cf2c86..3ba1c5bd74 100644 --- a/doc/UsersGuide/Makefile +++ b/doc/UsersGuide/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS = -a -n +SPHINXOPTS = -a -n -W --keep-going SPHINXBUILD = sphinx-build SOURCEDIR = source BUILDDIR = build diff --git a/doc/UsersGuide/requirements.in b/doc/UsersGuide/requirements.in index 26c778f4aa..d4a3c97475 100644 --- a/doc/UsersGuide/requirements.in +++ b/doc/UsersGuide/requirements.in @@ -1,3 +1,4 @@ -sphinx>=6.0.0 +sphinx==7.4.7 sphinx_rtd_theme sphinxcontrib-bibtex +requests==2.32.2 diff --git a/doc/UsersGuide/requirements.txt b/doc/UsersGuide/requirements.txt index 9e47095cca..b0c4c19e68 100644 --- a/doc/UsersGuide/requirements.txt +++ b/doc/UsersGuide/requirements.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.11 +# This file is autogenerated by pip-compile with Python 3.13 # by the following command: # # pip-compile requirements.in @@ -40,15 +40,17 @@ pygments==2.17.2 # via sphinx pyyaml==6.0.1 # via pybtex -requests==2.32.0 - # via sphinx +requests==2.32.2 + # via + # -r requirements.in + # sphinx six==1.16.0 # via # latexcodec # pybtex snowballstemmer==2.2.0 # via sphinx -sphinx==7.2.6 +sphinx==7.4.7 # via # -r requirements.in # sphinx-rtd-theme diff --git a/doc/UsersGuide/source/AutomatedTesting.rst b/doc/UsersGuide/source/AutomatedTesting.rst deleted file mode 100644 index 8655532a17..0000000000 --- a/doc/UsersGuide/source/AutomatedTesting.rst +++ /dev/null @@ -1,128 +0,0 @@ -.. _AutomatedTesting: - -***************** -Automated Testing -***************** - -The UFS Weather Model repository on GitHub employs two types of automated testing: - - #. CI/CD (Continuous Integration/Continuous Development) testing on the cloud - #. AutoRT on NOAA R&D platforms - -Both are application level tests and utilize the regression testing framework -discussed in :numref:`Section %s `. - -===== -CI/CD -===== - -The UFS Weather Model (:term:`WM`) uses GitHub Actions (GHA), a GitHub-hosted continuous integration service, -to perform CI/CD testing. Build jobs are done on GHA-provided virtual machines. Test jobs are -performed on the Amazon Web Services (AWS) cloud platform using a number of EC2 instances. -Builds and tests are carried out in a Docker container. The container includes a pre-installed version of the -:term:`HPC-Stack`, which includes all prerequisite libraries. Input data needed to run the tests -are stored as a separate Docker container. - -When a developer makes a pull request (PR) to the UFS WM repository, a code -manager may add the `run-ci` label, which triggers the CI/CD workflow. -The CI/CD workflow then executes the following steps: - - #. A check is performed to make sure the UFS Weather Model and its first level - subcomponents are up to date with the top of the ``develop`` branch. - - #. If the check is successful, build jobs are started on GHA-provided virtual machines - by downloading the HPC-Stack Docker container stored in Docker Hub. - - #. Once all build jobs are successful, the created executable files are stored as - artifacts in GHA. - - #. A number of AWS EC2 instances are started. - - #. Test jobs are started on AWS after downloading the HPC-Stack Docker container, - the executable file from the build job, and the input-data Docker container. - - #. When all tests are complete, EC2 instances are stopped. Test results are reported - on GitHub. - - -The GHA-related ``yaml`` scripts are located in the ``.github/workflows/`` directory. -``build_test.yml`` is the main workflow file, and ``aux.yml`` is an auxiliary -file responsible for (1) checking that the PR branch is up-to-date and -(2) starting/stopping the EC2 instances. - -Other CI-related scrips are located in the ``tests/ci/`` directory. ``ci.sh`` is the main script that -invokes Docker build and run. ``Dockerfile`` is used to build the UFS Weather Model. -Other shell and python scripts help with various tasks. For example: - - * ``repo_check.sh`` checks that the PR branch is up-to-date. - * ``check_status.py`` checks the status of EC2 instances. - * ``setup.py`` and ``ci.test`` configure the test cases to execute in the CI/CD workflow. - -.. COMMENT: It sounds like aux.yml and repo_check.sh do the same thing... What's the difference? - -======= -Auto RT -======= - -The Automated Regression Testing (AutoRT) system is a python program that automates the process -of regression testing on NOAA HPC platforms. -It contains the files in :numref:`Table %s ` below: - -.. _autoRT-files: -.. table:: *Files for Automated Regression Testing (AutoRT) system* - - +-------------------+-----------------------------------------------------+ - | **File Name** | **Description** | - +===================+=====================================================+ - | start_rt_auto.sh | Verifies HPC name, sets the python paths | - +-------------------+-----------------------------------------------------+ - | rt_auto.py | Python interface between the HPC and the github API | - +-------------------+-----------------------------------------------------+ - | jobs/bl.py | Functions for the baseline job | - +-------------------+-----------------------------------------------------+ - | jobs/rt.py | Functions for the regression test job | - +-------------------+-----------------------------------------------------+ - ------------------ -AutoRT Workflow ------------------ - -On supported HPC systems, a :term:`cron job` runs the ``start_rt_auto.sh`` bash script every 15 minutes. -This script checks the HPC name and sets certain python paths. Then, it runs ``rt_auto.py``, -which uses the Github API (through pyGitHub) to check the labels on pull requests to -``ufs-weather-model``. If a PR label matches the HPC name -(e.g., hera-intel-RT or derecho-gnu-BL), the label provides the HPC -with the compiler and job information to run a test or task on the machine. -If no PR label matches HPC name, the script exits. - -For example, a PR labeled ``gaea-intel-BL`` will be recognized by the HPC machine 'Gaea'. -It will set the ``RT_COMPILER`` variable to 'intel' and run the baseline creation script (``bl.py``). -This script creats a job class that contains all information from the machine that the job will need to run. -That information is sent into the ``jobs/rt[bl].py`` script. - -``rt.py`` sets directories for storage, gets repo information, runs the regression test, and -completes any required post processing. - -.. code-block:: python3 - - def run(job_obj): - logger = logging.getLogger('RT/RUN') - workdir = set_directories(job_obj) - branch, pr_repo_loc, repo_dir_str = clone_pr_repo(job_obj, workdir) - run_regression_test(job_obj, pr_repo_loc) - post_process(job_obj, pr_repo_loc, repo_dir_str, branch) - -``bl.py``: (similar to ``rt.py``) Adds functionality to create baselines before running regression testing. - -.. code-block:: python3 - :emphasize-lines: 5,6,7 - - def run(job_obj): - logger = logging.getLogger('BL/RUN') - workdir, rtbldir, blstore = set_directories(job_obj) - pr_repo_loc, repo_dir_str = clone_pr_repo(job_obj, workdir) - bldate = get_bl_date(job_obj, pr_repo_loc) - bldir = f'{blstore}/develop-{bldate}/{job_obj.compiler.upper()}' - bldirbool = check_for_bl_dir(bldir, job_obj) - run_regression_test(job_obj, pr_repo_loc) - post_process(job_obj, pr_repo_loc, repo_dir_str, rtbldir, bldir) diff --git a/doc/UsersGuide/source/BuildingAndRunning.rst b/doc/UsersGuide/source/BuildingAndRunning.rst index 406c528940..77fce82048 100644 --- a/doc/UsersGuide/source/BuildingAndRunning.rst +++ b/doc/UsersGuide/source/BuildingAndRunning.rst @@ -10,7 +10,7 @@ Supported Platforms & Compilers Before running the Weather Model (:term:`WM`), users should determine which of the :ref:`levels of support ` is applicable to their system. Generally, Level 1 & 2 systems are restricted to those with access -through NOAA and its affiliates. These systems are named (e.g., Hera, Orion, Derecho). +through NOAA and its affiliates. These systems are named (e.g., Ursa, Orion, Derecho). Level 3 & 4 systems include certain personal computers or non-NOAA-affiliated HPC systems. The prerequisite software libraries for building the WM already exist in a centralized location on Level 1/preconfigured systems, so users may skip directly to :ref:`getting the data ` and downloading the code. @@ -37,29 +37,28 @@ The WM uses two categories of libraries, which are available as a bundle via Common Modules ---------------- -As of February 24, 2025, the UFS WM Regression Tests (:term:`RTs `) on Level 1 systems use the following common modules: +As of October 20, 2025, the UFS WM Regression Tests (:term:`RTs `) on Level 1 systems use the following common modules: .. code-block:: console bacio/2.4.1 - crtm/2.4.0 - esmf/8.6.0 - fms/2024.01 + crtm/2.4.0.1 + esmf/8.8.0 + fms/2024.02 g2/3.5.1 g2tmpl/1.13.0 - gftl-shared/1.6.1 - hdf5/1.14.0 - ip/4.3.0 + gftl-shared/1.9.0 + hdf5/1.14.3 + ip/5.1.0 jasper/2.0.32 libpng/1.6.37 - mapl/2.40.3-esmf-8.6.0 + mapl/2.53.4-esmf-8.8.0 netcdf-c/4.9.2 netcdf-fortran/4.6.1 - parallelio/2.5.10 + parallelio/2.6.2 scotch/7.0.4 sp/2.5.0 w3emc/2.10.0 - zlib/1.2.13 The most updated list of common modules can be viewed in ``ufs_common.lua`` :wm-repo:`here `. @@ -91,8 +90,8 @@ the data required to run the WM RTs are already available at the following ``DIS - /glade/derecho/scratch/epicufsrt/ufs-weather-model/RT/ * - Gaea-C6 - /gpfs/f6/bil-fire8/world-shared/role.epic/UFS-WM_RT - * - Hera - - /scratch2/NAGAPE/epic/UFS-WM_RT + * - Ursa + - /scratch4/NAGAPE/epic/role-epic/UFS-WM_RT * - Hercules - /work/noaa/epic/hercules/UFS-WM_RT * - NOAA Cloud (Level 2) @@ -106,8 +105,8 @@ the data required to run the WM RTs are already available at the following ``DIS Within ``DISKNM``, input data for the UFS WM is located at the following locations: - * **INPUTDATA_ROOT**: ``${DISKNM}/NEMSfv3gfs/input-data-20240501`` - * **INPUTDATA_ROOT_WW3** ``${INPUTDATA_ROOT}/WW3_input_data_20250212`` + * **INPUTDATA_ROOT**: ``${DISKNM}/NEMSfv3gfs/input-data-20250507`` + * **INPUTDATA_ROOT_WW3** ``${INPUTDATA_ROOT}/WW3_input_data_20250807`` * **INPUTDATA_ROOT_BMIC**: ``${DISKNM}/NEMSfv3gfs/BM_IC-20220207`` * **INPUTDATA_LM4**: ``${INPUTDATA_ROOT}/LM4_input_data`` @@ -118,10 +117,10 @@ The regression testing script (``rt.sh``) has certain default data directories ( The corresponding data is publicly available in the data bucket. To view the data, users can visit https://noaa-ufs-regtests-pds.s3.amazonaws.com/index.html. Users can download the data and update the ``rt.sh`` script to point to the appropriate locations in order to run RTs on their own system: -* ``INPUTDATA_ROOT``: https://noaa-ufs-regtests-pds.s3.amazonaws.com/index.html#input-data-20240501/ -* ``INPUTDATA_ROOT_WW3`` https://noaa-ufs-regtests-pds.s3.amazonaws.com/index.html#input-data-20240501/WW3_input_data_20240214/ +* ``INPUTDATA_ROOT``: https://noaa-ufs-regtests-pds.s3.amazonaws.com/index.html#input-data-20250507/ +* ``INPUTDATA_ROOT_WW3``: https://noaa-ufs-regtests-pds.s3.amazonaws.com/index.html#input-data-20250507/WW3_input_data_20250807/ * ``INPUTDATA_ROOT_BMIC``: https://noaa-ufs-regtests-pds.s3.amazonaws.com/index.html#BM_IC-20220207/ -* ``INPUTDATA_LM4``: https://noaa-ufs-regtests-pds.s3.amazonaws.com/index.html#LM4_input_data +* ``INPUTDATA_LM4``: https://noaa-ufs-regtests-pds.s3.amazonaws.com/index.html#input-data-20250507/LM4_input_data/ To download data, users must select the files they want from the bucket and download them either in their browser, via a ``wget`` command, or through the AWS CLI. @@ -165,12 +164,12 @@ On NOAA Level 1 & 2 Systems Modulefiles for :ref:`preconfigured platforms ` are located in ``modulefiles/ufs_.``. For example, to load the modules from the -``ufs-weather-model`` directory on Hera: +``ufs-weather-model`` directory on Ursa: .. code-block:: console module use modulefiles - module load ufs_hera.intel + module load ufs_ursa.intel Note that loading this module file will also set the CMake environment variables shown in :numref:`Table %s `. @@ -180,15 +179,15 @@ Note that loading this module file will also set the CMake environment variables .. table:: *CMake environment variables required to configure the build for the Weather Model* +-------------------------+----------------------------------------------+----------------------+ - | **EnvironmentVariable** | **Description** | **Hera Intel Value** | + | **EnvironmentVariable** | **Description** | **Ursa Intel Value** | +=========================+==============================================+======================+ - | CMAKE_C_COMPILER | Name of C compiler | mpiicc | + | CMAKE_C_COMPILER | Name of C compiler | mpiicx | +-------------------------+----------------------------------------------+----------------------+ - | CMAKE_CXX_COMPILER | Name of C++ compiler | mpiicpc | + | CMAKE_CXX_COMPILER | Name of C++ compiler | mpiicpx | +-------------------------+----------------------------------------------+----------------------+ | CMAKE_Fortran_COMPILER | Name of Fortran compiler | mpiifort | +-------------------------+----------------------------------------------+----------------------+ - | CMAKE_Platform | String containing platform and compiler name | hera.intel | + | CMAKE_Platform | String containing platform and compiler name | ursa.intel | +-------------------------+----------------------------------------------+----------------------+ On Other Systems @@ -209,238 +208,23 @@ The UFS Weather Model can be built in one of several configurations (see :numref The ``CMAKE_FLAGS`` environment variable specifies which configuration to build using the ``-DAPP`` and ``-DCCPP_SUITES`` variables. Users set which components to build using ``-DAPP``. Users select the :term:`CCPP` suite(s) by setting the ``CCPP_SUITES`` environment variable at build time in order to have one or more CCPP physics suites available at runtime. -Multiple suites can be set. Additional variables, such as ``-D32BIT=ON``, -can be set if the user chooses. These options are documented in :numref:`Section %s `. -The following examples assume a bash shell. +Multiple suites can be set. Additional variables, such as ``-D32BIT=ON``, can be set if the user chooses. -ATM Configurations ---------------------- - -.. _atm: - -**Standalone ATM** - -For the ``ufs-weather-model ATM`` configuration (standalone :term:`ATM`): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATM -DCCPP_SUITES=FV3_GFS_v16" - -.. _atmw: - -**ATMW** - -For the ``ufs-weather-model ATMW`` configuration (standalone ATM coupled to :term:`WW3`): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATMW -DCCPP_SUITES=FV3_GFS_v16" - -.. _atmaero: - -**ATMAERO** - -For the ``ufs-weather-model ATMAERO`` configuration (standalone ATM coupled to :term:`GOCART`): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATMAERO -DCCPP_SUITES=FV3_GFS_v17_p8" - -.. _atmaq: - -**ATMAQ** - -For the ``ufs-weather-model ATMAQ`` configuration (standalone ATM coupled to :term:`CMAQ`): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATMAQ -DCCPP_SUITES=FV3_GFS_v15p2" - -.. _atml: - -**ATML** - -For the ``ufs-weather-model ATML`` configuration (standalone ATM coupled to :term:`LND`): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATML -DCCPP_SUITES=FV3_GFS_v17_p8" - -.. _atmf: - -**ATMF** - -For the ``ufs-weather-model ATMF`` configuration (standalone ATM coupled to :term:`UFS Fire`): +For example, the ``ufs-weather-model ATMW`` configuration (standalone ATM coupled to :term:`WW3`) would look like: .. code-block:: console - export CMAKE_FLAGS="-DAPP=ATMF -DCCPP_SUITES=FV3_HRRR -D32BIT=ON" + export CMAKE_FLAGS="-DAPP=ATMW -DCCPP_SUITES=FV3_GFS_v17_p8" -.. _atm_ds2s: - -**ATM_DS2S** - -For the ``ufs-weather-model ATM_DS2S`` configuration (:term:`ATM`/:term:`DOCN`/:term:`DICE`): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATM_DS2S -DCCPP_SUITES=FV3_GFS_v17_coupled_p8_ugwpv1" - - -.. _atm_ds2s-pcice: - -**ATM_DS2S-PCICE** - -For the ``ufs-weather-model ATM_DS2S-PCICE`` configuration (:term:`ATM`/:term:`DOCN`/:term:`CICE6` [prescribed ice mode]): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATM_DS2S-PCICE -DCCPP_SUITES=FV3_GFS_v17_coupled_p8" - - -S2S Configurations ----------------------- - -.. _s2s: - -**S2S** - -For the ``ufs-weather-model S2S`` configuration (coupled atm/ice/ocean): +Other common examples include: .. code-block:: console - export CMAKE_FLAGS="-DAPP=S2S -DCCPP_SUITES=FV3_GFS_v17_coupled_p8" + export CMAKE_FLAGS="-DAPP=S2S -DCCPP_SUITES=FV3_GFS_v17_coupled_p8_ugwpv1" -To turn on debugging flags, add ``-DDEBUG=ON`` flag after ``-DAPP=S2S``. Users can allow verbose build messages by running: + export CMAKE_FLAGS="-DAPP=S2SW -DCCPP_SUITES=FV3_GFS_v17_coupled_p8_ugwpv1" -.. code-block:: console - - export BUILD_VERBOSE=1 - -To receive atmosphere-ocean fluxes from the CMEPS :term:`mediator`, add the argument ``-DCMEPS_AOFLUX=ON``. -For example: - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=S2S -DCCPP_SUITES=FV3_GFS_v17_coupled_p8_sfcocn -DCMEPS_AOFLUX=ON" - -.. _s2sa: - -**S2SA** - -For the ``ufs-weather-model S2SA`` configuration (atm/ice/ocean/aerosols): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=S2SA -DCCPP_SUITES=FV3_GFS_2017_coupled,FV3_GFS_v15p2_coupled,FV3_GFS_v16_coupled,FV3_GFS_v16_coupled_noahmp" - -.. _s2sw: - -**S2SW** - -For the ``ufs-weather-model S2SW`` configuration (atm/ice/ocean/wave): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=S2SW -DCCPP_SUITES=FV3_GFS_v17_coupled_p8" - -.. _s2swa: - -**S2SWA** - -For the ``ufs-weather-model S2SWA`` configuration (atm/ice/ocean/wave/aerosols): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=S2SWA -DCCPP_SUITES=FV3_GFS_v17_coupled_p8,FV3_GFS_cpld_rasmgshocnsstnoahmp_ugwp" - -.. _s2swal: - -**S2SWAL** - -For the ``ufs-weather-model S2SWAL`` configuration (atm/ice/ocean/wave/aerosols/land): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=S2SWAL -DCCPP_SUITES=FV3_GFS_v17_coupled_p8,FV3_GFS_v17_coupled_p8_ugwpv1" - - -.. _ng-godas: - -NG-GODAS Configuration ------------------------- - -For the ``ufs-weather-model NG-GODAS`` configuration (atm/ocean/ice/data assimilation): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=NG-GODAS" - -HAFS Configurations ----------------------- - -.. _hafs: - -**HAFS** - -For the ``ufs-weather-model HAFS`` configuration (atm/ocean) in 32 bit: - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=HAFS -D32BIT=ON -DCCPP_SUITES=FV3_HAFS_v0_gfdlmp_tedmf_nonsst,FV3_HAFS_v0_gfdlmp_tedmf" - -.. _hafsw: - -**HAFSW** - -For the ``ufs-weather-model HAFSW`` configuration (atm/:term:`HYCOM`/wave) in 32-bit with moving nest: - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=HAFSW -D32BIT=ON -DMOVING_NEST=ON -DCCPP_SUITES=FV3_HAFS_v0_gfdlmp_tedmf,FV3_HAFS_v0_gfdlmp_tedmf_nonsst,FV3_HAFS_v0_thompson_tedmf_gfdlsf" - -.. _hafs-mom6w: - -**HAFS-MOM6W** - -For the ``ufs-weather-model HAFS-MOM6`` configuration (atm/:term:`MOM6`/wave) in 32-bit with moving nest: - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=HAFS-MOM6W -DREGIONAL_MOM6=ON -DCDEPS_INLINE=ON -DMOVING_NEST=ON -DCCPP_SUITES=FV3_HAFS_v1_gfdlmp_tedmf,FV3_HAFS_v1_gfdlmp_tedmf_nonsst,FV3_HAFS_v1_thompson,FV3_HAFS_v1_thompson_nonsst -D32BIT=ON" - -.. _hafs-all: - -**HAFS-ALL** - -For the ``ufs-weather-model HAFS-ALL`` configuration (data/atm/ocean/wave) in 32 bit: - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=HAFS-ALL -D32BIT=ON -DCCPP_SUITES=FV3_HAFS_v0_gfdlmp_tedmf,FV3_HAFS_v0_gfdlmp_tedmf_nonsst" - -Land Configurations ----------------------- - -.. _lnd: - -**LND** - -For the ``ufs-weather-model LND`` configuration (:term:`DATM`/land [:term:`NOAHMP`]): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=LND" - -.. _lnd-lm4: - -**LM4** - -For the ``ufs-weather-model LND-LM4`` configuration (:term:`DATM`/land [:term:`LM4`]): - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=LND-LM4" +For the complete and most up-to-date list of ``-DAPP`` and ``DCCPP_SUITES`` options, see :ref:`Chapter 7 ` or the :wm-repo:`CMakeLists.txt ` file. ------------------ Building the Model @@ -454,7 +238,7 @@ If any of the environment variables have not been set, the ``build.sh`` script w .. code-block:: console - ./build.sh: line 11: CMAKE_Platform: Please set the CMAKE_Platform environment variable, e.g. [macosx.gnu|linux.gnu|linux.intel|hera.intel|...] + ./build.sh: line 11: CMAKE_Platform: Please set the CMAKE_Platform environment variable, e.g., [ufs_hercules.intel|ufs_hercules.gnu|ufs_ursa.intel|ufs_ursa.intelllvm|...] The WM can be built by running the following command from the ``ufs-weather-model`` directory: @@ -503,7 +287,11 @@ the defaults. * - Function Name - Description * - export_fv3_v16 - - Set variables to the FV3 default values for GFS v16 cases. This section will be removed once support for GFSv16 is officially depricated. + - Set variables to the FV3 default values for GFS v16 cases. This section will be removed once support for GFSv16 is officially deprecated. + * - export_mpas + - Set variables to the MPAS default values. + * - export_gfs_physics + - Set default values for GFS physics suite configurations. * - export_fv3 - Set variables to the FV3 default values. * - export_tiled @@ -643,7 +431,7 @@ The ``rt.conf`` file is a pipe-separated values (PSV) file grouped into sections #. **CMAKE Options** -- Provides all CMAKE options for the build. This typically includes the ``-DAPP`` and ``-DCCPP_SUITES`` flags; these flags set which components to build and which physics suites will be available at runtime. Additional options are documented in :numref:`Section %s `, but users can examine the :wm-repo:`CMakeLists.txt ` file for the most up-to-date list of options. #. **Machines** to run on (``-`` is used to ignore specified machines, ``+`` is used to run only on specified machines). For example: - * ``+ hera orion gaea``: Compile will only run on Hera, Orion, and Gaea machines + * ``+ ursa orion gaeac6``: Compile will only run on Ursa, Orion, and Gaea-C6 machines * ``- wcoss2 acorn``: Compile will NOT be run on WCOSS2 or Acorn #. ``fv3``: Set as fv3. Previously, this was used to run a test without compiling code (e.g., if FV3 was already present). @@ -667,12 +455,14 @@ in 32-bit mode and then runs the ``control`` test: RUN | cpld_control_gfsv17 | - noaacloud | baseline | RUN | cpld_control_gfsv17_iau | - noaacloud | baseline | cpld_control_gfsv17 RUN | cpld_restart_gfsv17 | - noaacloud | | cpld_control_gfsv17 + RUN | cpld_restart_gfsv17_iau | - noaacloud | | cpld_control_gfsv17_iau RUN | cpld_mpi_gfsv17 | - noaacloud | | The ``rt.conf`` file includes a large number of tests. If the user wants to run only specific tests, s/he can either (1) comment out the tests to be skipped (using the ``#`` prefix) -or (2) create a new file (e.g., ``my_rt.conf``), add the tests, and execute ``./rt.sh -l my_rt.conf``. +or (2) create a new file (e.g., ``my_rt.conf``), add the tests, and execute ``./rt.sh -a -l my_rt.conf``. +For the most up-to-date list of supported tests see the :wm-repo:`rt.conf ` file. .. _run-wm: @@ -694,7 +484,7 @@ Users can run a number of preconfigured regression test cases from the ``rt.conf using the regression test script ``rt.sh`` in the ``tests`` directory. ``rt.sh`` is the top-level script that calls lower-level scripts to build specified WM configurations, set up environments, and run tests. -Users should edit the ``rt.conf`` file to indicate which tests/configurations to run or create their own configuration file (e.g., ``my_tests.conf``) with the subset of tests they want to run. +Users should edit the ``rt.conf`` file to indicate which tests/configurations to run or create their own configuration file (e.g., ``my_tests.conf``) with the subset of tests from :wm-repo:`rt.conf `. On NOAA RDHPCS ------------------ @@ -706,7 +496,7 @@ regression tests by editing the ``rt.conf`` file and executing: ./rt.sh -a -l rt.conf -where ```` is to the account/project number where users submit their batch jobs. +where ```` is the account/project number where users submit their batch jobs. Users may need to add additional command line arguments or change information in the ``rt.sh`` file as well. This information is provided in :numref:`Section %s ` below. @@ -739,7 +529,7 @@ This section contains additional information on command line options and trouble Optional Arguments ^^^^^^^^^^^^^^^^^^^^^ -To display detailed information on how to use ``rt.sh``, users can simply run ``./rt.sh``, which will output the following options: +To display detailed information on how to use ``rt.sh``, users can simply run ``./rt.sh -h``, which will output the following options: .. code-block:: console @@ -774,7 +564,7 @@ create the configuration file (e.g. ``my_rt.conf``) based on the desired tests i .. code-block:: console - ./rt.sh -r -l my_rt.conf + ./rt.sh -a -r -l my_rt.conf adding additional arguments as desired. @@ -782,7 +572,7 @@ To run a single test, users can try the following command instead of creating a .. code-block:: console - ./rt.sh -r -k -n "control_p8 " + ./rt.sh -a -r -k -n "control_p8 " where ```` is ``gnu`` or ``intel``. @@ -796,8 +586,8 @@ correctly. If there is a problem with these or other variables (e.g., file paths .. code-block:: console :emphasize-lines: 5,6 - + echo 'Machine: ' hera.intel ' Account: ' nems - Machine: hera.intel Account: nems + + echo 'Machine: ' ursa.intel ' Account: ' nems + Machine: ursa.intel Account: nems + mkdir -p /scratch1/NCEPDEV/stmp4/First.Last mkdir: cannot create directory ‘/scratch1/NCEPDEV/stmp4/First.Last’: Permission denied ++ echo 'rt.sh error on line 370' @@ -811,67 +601,78 @@ Log Files ------------ The regression test generates a number of log files. The summary log file -``RegressionTests_..log`` in the ``tests`` directory compares -the results of the test against the baseline for a given platform and -reports the outcome: +``RegressionTests_.log`` in the ``tests`` directory provides a summary +of the regression test outcomes, which will look similar to this excerpt: + +.. code-block:: console + + PASS -- COMPILE 's2sw_pdlib_intel' [14:10, 12:22] ( 1 warnings 1036 remarks ) + PASS -- TEST 'cpld_control_pdlib_p8_intel' [12:41, 11:00](2171 MB) + PASS -- TEST 'cpld_restart_pdlib_p8_intel' [07:49, 05:23](1636 MB) + PASS -- TEST 'cpld_mpi_pdlib_p8_intel' [17:40, 15:30](2120 MB) + PASS -- TEST 'cpld_control_c48_5deg_intel' [13:30, 11:22](3029 MB) + FAILED: TEST TIMED OUT -- TEST 'cpld_warmstart_c48_5deg_intel' [, ]( MB) + FAILED: UNABLE TO START TEST -- TEST 'cpld_restart_c48_5deg_intel' [, ]( MB) + +More detailed log files for each test are located in the ``tests/logs/log_`` directory: * ``'Missing file'`` results when the expected files from the simulation are not found and typically occurs when the simulation did not run to completion; * ``'OK'`` means that the simulation results are bit-for-bit identical to those of the baseline; * ``'NOT OK'`` when the results are **not** bit-for-bit identical; and - * ``'Missing baseline'`` when there is no baseline data to compare against. + * ``'Missing baseline'`` when there is no baseline data to compare against -More detailed log files are located in the ``tests/log_./`` directory. -The run directory path, which corresponds to the value of ``RUNDIR`` in the ``run_`` file, -is particularly useful. ``$RUNDIR`` is a self-contained (i.e., sandboxed) -directory with the executable file, initial conditions, model configuration files, -environment setup scripts and a batch job submission script. The user can run the test -by navigating into ``$RUNDIR`` and invoking the command: +The run directory also contains useful information. It is symlinked from the ``tests`` directory as ``run_dir``, +and the actual path is set in ``rt.sh`` via the ``$RUNDIR_ROOT`` variable. The run directory contains subdirectories +named ``run_`` for each test that is run via ``rt.sh``. These are self-contained +(i.e., sandboxed) directories with the executable file, initial conditions, model configuration files +(e.g., ``input.nml``, ``model_configure``, ``ufs.configure``), +environment setup scripts and a batch job submission script. +``err`` and ``out`` files in each ``run_`` directory contain information sent to standard error and standard out, +respectively. +Additionally, application-dependent files (e.g., ``ice_in`` for the Subseasonal-to-Seasonal Application) are included. +The user can rerun the test by navigating into the ``run_`` directory and invoking the command: .. code-block:: console sbatch job_card This can be particularly useful for debugging and testing code changes. Note that -``$RUNDIR`` is automatically deleted at the end of a successful regression test; -specifying the ``-k`` option retains the ``$RUNDIR``, e.g. ``./rt.sh -l rt.conf -k``. - -Inside the ``$RUNDIR`` directory are a number of model configuration files (``input.nml``, -``model_configure``, ``ufs.configure``) and other application -dependent files (e.g., ``ice_in`` for the Subseasonal-to-Seasonal Application). -These model configuration files are -generated by ``rt.sh`` from the template files in the ``tests/parm`` directory. +the run directory is automatically deleted at the end of a successful regression test; +specifying the ``-k`` option retains the run directory, e.g., ``./rt.sh -a -l rt.conf -k``. + +Model configuration files are generated by ``rt.sh`` from the template files in the ``tests/parm`` directory. Specific values used to fill in the template files are test-dependent and are set in two stages. First, default values are specified in ``tests/default_vars.sh``, and the default values are overriden if necessary by values specified in a test file ``tests/tests/``. For example, the variable ``DT_ATMOS`` is initially assigned 1800 in the function ``export_fv3`` of the script ``default_vars.sh``, but the test file -``tests/tests/control`` overrides this setting by reassigning 720 to the variable. +(e.g., ``tests/tests/control_p8_faster``) overrides this setting by reassigning 720 to the variable. -The files ``fv3_run`` and ``job_card`` also reside in the ``$RUNDIR`` directory. +The files ``fv3_run`` and ``job_card`` also reside in the run directory. These files are generated from the template files in the ``tests/fv3_conf`` directory. ``job_card`` is a platform-specific batch job submission script, while ``fv3_run`` prepares the initial conditions for the test by copying relevant data from the -input data directory of a given platform to the ``$RUNDIR`` directory. +input data directory of a given platform to the run directory. :numref:`Table %s ` summarizes the subdirectories discussed above. .. _RTSubDirs: -.. table:: *Regression Test Subdirectories* - - +-----------------+--------------------------------------------------------------------------------------+ - | **Name** | **Description** | - +=================+======================================================================================+ - | tests/ | Regression test root directory. Contains rt-related scripts and the summary log file | - +-----------------+--------------------------------------------------------------------------------------+ - | tests/tests/ | Contains specific test files | - +-----------------+--------------------------------------------------------------------------------------+ - | tests/parm/ | Contains templates for model configuration files | - +-----------------+--------------------------------------------------------------------------------------+ - | tests/fv3_conf/ | Contains templates for setting up initial conditions and a batch job | - +-----------------+--------------------------------------------------------------------------------------+ - | tests/log_*/ | Contains fine-grained log files | - +-----------------+--------------------------------------------------------------------------------------+ +.. list-table:: Regression Test Subdirectories + :widths: 25 75 + :header-rows: 1 + * - Name + - Description + * - ``tests/`` + - Regression test root directory. Contains rt-related scripts and the summary log file. + * - ``tests/tests/`` + - Contains specific test files. + * - ``tests/parm/`` + - Contains templates for model configuration files. + * - ``tests/fv3_conf/`` + - Contains templates for setting up initial conditions and a batch job. + * - ``tests/logs/log_/`` + - Contains fine-grained log files. .. _UsingOpnReqTest: @@ -883,9 +684,9 @@ tests in place of ``rt.sh``. Given the name of a test, ``opnReqTest`` carries ou Each test case addresses an aspect of the requirements that new operational implementations must satisfy. These requirements are shown in :numref:`Table %s `. For the following discussions on opnReqTest, the user should note the distinction between -``'test name'`` and ``'test case'``. Examples of test names are ``control``, ``cpld_control`` +``'test name'`` and ``'test case'``. Examples of test names are ``control_p8``, ``cpld_control_p8`` and ``regional_control`` which are all found in the ``tests/tests`` directory, whereas -test case refers to any one of the operational requirements: ``thr``, ``mpi``, ``dcp``, ``rst``, ``bit`` and ``dbg``. +test case refers to any one of the operational requirements: ``thr``, ``fhz``, ``mpi``, ``dcp``, ``rst``, ``bit`` and ``dbg``. .. _OperationalRequirement: @@ -906,6 +707,8 @@ test case refers to any one of the operational requirements: ``thr``, ``mpi``, ` +----------+-------------------------------------------------------------------------------+ | dbg | Model can be compiled and run to completion in debug mode | +----------+-------------------------------------------------------------------------------+ + | fhz | Early forecast output produces consistent results | + +----------+-------------------------------------------------------------------------------+ The operational requirement testing uses the same testing framework as the regression tests, so it is recommended that the user first read :numref:`Section %s `. @@ -960,12 +763,12 @@ executing ``./opnReqTest -h``, which produces the following results: Frequently used options are ``-e`` to use the ecFlow -workflow manager, and ``-k`` to keep the ``$RUNDIR``. The Rocoto workflow manager +workflow manager, and ``-k`` to keep the run directory. The Rocoto workflow manager is not used operationally and therefore is not an option. As discussed in :numref:`Section %s `, the variables and values used to configure model parameters and to set up initial conditions in the -``$RUNDIR`` directory are set up in two stages. First, ``tests/default_vars.sh`` +run directory are set up in two stages. First, ``tests/default_vars.sh`` define default values; then a specific test file in the ``tests/tests`` subdirectory either overrides the default values or creates new variables if required by the test. The regression test treats the different test cases shown in diff --git a/doc/UsersGuide/source/CAPE2020.rst b/doc/UsersGuide/source/CAPE2020.rst index 224de6f2fe..02b42616db 100644 --- a/doc/UsersGuide/source/CAPE2020.rst +++ b/doc/UsersGuide/source/CAPE2020.rst @@ -34,7 +34,7 @@ Users who have access to :term:`HPSS` can generate initial conditions (:term:`IC In order to generate all necessary configuration, data, input, and fix files to run a configuration similar to the July 2020 CAPE case for another date (still C48 resolution), the user first needs to run the base ``ufs_test.sh`` script for the default July 2020 CAPE case as described in :numref:`Section %s `. -To generate coldstart ICs via the UFS_UTILS ``gdas_init``/``chgres_cube`` utilities on an :term:`RDHPCS` with :term:`HPSS` access (e.g., Hera), the user can run the following commands: +To generate coldstart ICs via the UFS_UTILS ``gdas_init``/``chgres_cube`` utilities on an :term:`RDHPCS` with :term:`HPSS` access (e.g., Ursa), the user can run the following commands: .. code-block:: console @@ -45,7 +45,7 @@ To generate coldstart ICs via the UFS_UTILS ``gdas_init``/``chgres_cube`` utilit ./build_all.sh cd util/gdas_init -where ```` is Hera. +where ```` is ursa. Then, users will need to edit the ``config`` file to: @@ -100,7 +100,7 @@ The July 2020 CAPE case can be run as-is without adjusting the configuration. Us Different Date ^^^^^^^^^^^^^^^^ -Users may choose to run a similar UFS WM configuration for different dates with user-generated :term:`ICs` (see :numref:`Section %s ` for instructions on downloading this data from :term:`HPSS`). In this case, users will need to copy the ``gfs*.nc`` and ``sfc*.nc`` files from ``OUTDIR/gfs.YYYYMMDD/HH/model_data/atmos/input`` into the ``INPUT`` directory of a UFS WM run directory. (The run directory is set in ``create_xml.py`` as ``${PTMP}/${USER}/FV3_RT/rt_${pid}`` for HSD cases.) Note that this will only work when the run directory uses ICs of the same resolution. +Users may choose to run a similar UFS WM configuration for different dates with user-generated :term:`ICs` (see :numref:`Section %s ` for instructions on downloading this data from :term:`HPSS`). In this case, users will need to copy the ``gfs*.nc`` and ``sfc*.nc`` files from ``OUTDIR/gfs.YYYYMMDD/HH/model_data/atmos/input`` into the ``INPUT`` directory of a UFS WM run directory. (The run directory is set in ``${UFS_WM}/tests-dev/machine_config/create_xml.py`` as ``${PTMP}/${USER}/FV3_RT/rt_${pid}`` for HSD cases.) Note that this will only work when the run directory uses ICs of the same resolution. Additionally, users will need to adjust the model start time in the ``model_configure`` file. For example: diff --git a/doc/UsersGuide/source/CodeOverview.rst b/doc/UsersGuide/source/CodeOverview.rst index 2d3c344359..c5a3b064ee 100644 --- a/doc/UsersGuide/source/CodeOverview.rst +++ b/doc/UsersGuide/source/CodeOverview.rst @@ -24,11 +24,12 @@ Preconfigured (Level 1) systems for the UFS WM already have the required externa Currently, Level 1 (or Tier-1) platforms for regression testing are: * WCOSS2 (Intel) - * Gaea (Intel) - * Hera (Intel/GNU compilers) + * Gaea C6 (Intel) + * Ursa (Intel/GNU compilers) * Jet (Intel) * Orion (Intel) * Hercules (Intel/GNU compilers) + * Derecho (Intel/GNU compilers) * AWS Docker container (Intel) More information is available in the :wm-wiki:`UFS WM wiki `. @@ -46,52 +47,70 @@ Currently, Level 2 platforms for regression testing are: UFS Weather Model Hierarchical Repository Structure =================================================== -The UFS :term:`WM` repository supports the :term:`UFS` short- and medium-range weather applications (:term:`SRW` / :term:`MRW` Apps). The WM repository contains atmosphere, ocean, sea ice, land, and wave components, as well as some infrastructure components. Each of these subcomponents has its own repository. All the repositories are currently located in GitHub with public access to the broader community. :numref:`Table %s ` describes the list of repositories that comprise the UFS WM. +The UFS :term:`WM` repository supports the :term:`UFS` short-range weather applications (:term:`SRW`). The WM repository contains atmosphere, ocean, sea ice, land, and wave components, as well as some infrastructure components. Each of these subcomponents has its own repository. All the repositories are currently located in GitHub with public access to the broader community. :numref:`Table %s ` describes the list of repositories that comprise the UFS WM. .. _Repo_Structure: .. list-table:: *List of Repositories that comprise the ufs-weather-model* - :widths: 50 50 - :header-rows: 1 - - * - Repository Description - - Authoritative repository URL - * - Umbrella repository for the UFS Weather Model - - https://github.com/ufs-community/ufs-weather-model - * - Framework to connect the :term:`CCPP` library to a host model - - https://github.com/NCAR/ccpp-framework - * - CCPP library of physical parameterizations - - https://github.com/NCAR/ccpp-physics - * - Umbrella repository for the physics and dynamics of the atmospheric model (FV3) - - https://github.com/NOAA-EMC/fv3atm - * - :term:`FV3` dynamical core - - https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere - * - Stochastic physics pattern generator - - https://github.com/NOAA-PSL/stochastic_physics - * - Modular Ocean Model (:term:`MOM6`) - - https://github.com/NOAA-EMC/MOM6 - * - HYbrid Coordinate Ocean Model (:term:`HYCOM`) - - https://github.com/NOAA-EMC/HYCOM-src - * - Los Alamos sea ice model (:term:`CICE6`) - - https://github.com/NOAA-EMC/CICE - * - NOAA/NCEP WAVEWATCH III Model (:term:`WW3`) - - https://github.com/NOAA-EMC/WW3 - * - The Goddard Chemistry Aerosol Radiation and Transport (:term:`GOCART`) - - https://github.com/GEOS-ESM/GOCART - * - NUOPC Community Mediator for Earth Prediction Systems (:term:`CMEPS`) - - https://github.com/NOAA-EMC/CMEPS - * - Community Data Models for Earth Prediction Systems (:term:`CDEPS`) - - https://github.com/NOAA-EMC/CDEPS - * - Air Quality Model (:term:`AQM`) - - https://github.com/NOAA-EMC/AQM - * - Noah-MP Land Surface Model (Noah-MP) - - https://github.com/NOAA-EMC/noahmp - * - NOAA-GFDL Land Model (:term:`LM4`) - - https://github.com/NOAA-GFDL/LM4-NUOPC-driver - * - Community Fire Behavior Model - - https://github.com/NOAA-EMC/fire_behavior - -In the table, the left-hand column contains a description of each repository, and the + :widths: 20 50 30 + :header-rows: 1 + + * - Repository name + - Repository Description + - Authoritative repository URL + * - UFS Weather Model + - Umbrella repository for the UFS Weather Model + - https://github.com/ufs-community/ufs-weather-model + * - CCPP Framework + - Framework to connect the :term:`CCPP` library to a host model + - https://github.com/NCAR/ccpp-framework + * - CCPP Physics + - CCPP library of physical parameterizations + - https://github.com/NCAR/ccpp-physics + * - UFSATM + - Umbrella repository for the physics and dynamics of the atmospheric model + - https://github.com/NOAA-EMC/ufsatm + * - GFDL_atmos_cubed_sphere + - :term:`FV3` dynamical core + - https://github.com/NOAA-GFDL/GFDL_atmos_cubed_sphere + * - Stochastic Physics + - Stochastic physics pattern generator + - https://github.com/NOAA-PSL/stochastic_physics + * - MOM6 + - Modular Ocean Model (:term:`MOM6`) + - https://github.com/NOAA-EMC/MOM6 + * - HYCOM-src + - HYbrid Coordinate Ocean Model (:term:`HYCOM`) + - https://github.com/NOAA-EMC/HYCOM-src + * - CICE + - Los Alamos sea ice model (:term:`CICE6`) + - https://github.com/NOAA-EMC/CICE + * - WW3 + - NOAA/NCEP WAVEWATCH III Model (:term:`WW3`) + - https://github.com/NOAA-EMC/WW3 + * - GOCART + - The Goddard Chemistry Aerosol Radiation and Transport (:term:`GOCART`) + - https://github.com/GEOS-ESM/GOCART + * - CMEPS + - NUOPC Community Mediator for Earth Prediction Systems (:term:`CMEPS`) + - https://github.com/NOAA-EMC/CMEPS + * - CDEPS + - Community Data Models for Earth Prediction Systems (:term:`CDEPS`) + - https://github.com/NOAA-EMC/CDEPS + * - AQM + - Air Quality Model (:term:`AQM`) + - https://github.com/NOAA-EMC/AQM + * - Noah-MP + - Noah-MP Land Surface Model (Noah-MP) + - https://github.com/NOAA-EMC/noahmp + * - LM4-NUOPC-driver + - NOAA-GFDL Land Model (:term:`LM4`) + - https://github.com/NOAA-GFDL/LM4-NUOPC-driver + * - Fire Behavior + - Community Fire Behavior Model + - https://github.com/NOAA-EMC/fire_behavior + +In the table, the left-hand column contains the name of each repository, the middle column contains the repository description and the right-hand column shows the GitHub location of the authoritative component repositories. The UFS WM currently uses Git submodules to manage these subcomponents. @@ -114,6 +133,7 @@ The umbrella repository for the UFS WM is named ``ufs-weather-model``. Under thi │ ├── (datm) -------- CDEPS DATM │ ├── (docn) -------- CDEPS DOCN │ └── (dice) -------- CDEPS DICE + ├── ci ├── CICE-interface │ └── CICE -------- CICE6 sea ice model │ ├── (icepack) -------- Sea ice column physics @@ -127,21 +147,6 @@ The umbrella repository for the UFS WM is named ``ufs-weather-model``. Under thi ├── doc -------- User Guide files ├── driver ├── fire_behavior -------- Community Fire Behavior Model - ├── FV3 -------- UFSAtm atmosphere model - │ ├── (atmos_cubed_sphere) -------- FV3 dynamical core - │ │ ├── (docs) - │ │ ├── (driver) - │ │ ├── (model) - │ │ └── (tools) - │ ├── (ccpp) -------- Common Community Physics Package - │ │ ├── (config) - │ │ ├── (driver) - │ │ ├── (framework) -------- CCPP framework - │ │ ├── (physics) -------- CCPP-compliant physics schemes - │ │ └── (suites) -------- CCPP physics suite definition files (SDFs) - │ ├── (cpl) -------- Coupling field data structures - │ ├── (io) -------- UFSAtm write grid comp code - │ └── (stochastic_physics) -------- Wrapper for stochastic physics ├── GOCART │ └── (ESMF) -------- GOCART model ├── HYCOM-interface @@ -171,6 +176,23 @@ The umbrella repository for the UFS WM is named ``ufs-weather-model``. Under thi ├── tests-dev -------- developmental testing framework │ ├── test_cases │ └── machine_config + ├── UFSATM -------- UFSATM atmosphere model + │ ├── (ccpp) -------- Common Community Physics Package + │ │ ├── (config) + │ │ ├── (driver) + │ │ ├── (framework) -------- CCPP framework + │ │ ├── (physics) -------- CCPP-compliant physics schemes + │ │ └── (suites) -------- CCPP physics suite definition files (SDFs) + │ ├── (cpl) -------- Coupling field data structures + │ ├── (fv3) + │ │ └── (atmos_cubed_sphere) -------- FV3 dynamical core + │ │ ├── (docs) + │ │ ├── (driver) + │ │ ├── (model) + │ │ └── (tools) + │ ├── (io) -------- UFSATM write grid component code + │ ├── (mpas) -------- MPAS dynamical core + │ └── (upp) -------- Unified Post Processor └── WW3 └── (model) -------- WW3 model └── (src) -------- NUOPC WW3 caps diff --git a/doc/UsersGuide/source/ConfigParameters.rst b/doc/UsersGuide/source/ConfigParameters.rst index ff24e8cb5f..0b394ef172 100644 --- a/doc/UsersGuide/source/ConfigParameters.rst +++ b/doc/UsersGuide/source/ConfigParameters.rst @@ -17,7 +17,7 @@ Configuration Options ``-DAPP``: Sets the :term:`WM` configuration to build. - Valid values: ``ATM``, ``ATMW``, ``ATMAERO``, ``ATMAQ``, ``ATMWM``, ``ATML``, ``ATMF``, ``ATM_DS2S``, ``ATM_DS2S-PCICE``, ``LND``, ``LND-LM4``, ``S2S``, ``S2SA``, ``S2SW``, ``S2SWA``, ``S2SL``, ``S2SWL``, ``S2SWAL``, ``NG-GODAS``, ``HAFS``, ``HAFSW``, ``HAFS-MOM6``, ``HAFS-MOM6W``, ``HAFS-ALL`` + Valid values: ``ATM``, ``ATMW``, ``ATMAERO``, ``ATMAQ``, ``ATML``, ``ATMF``, ``ATMMPAS``, ``ATM_DS2S``, ``ATM_DS2S-PCICE``, ``LND``, ``LND-LM4``, ``S2S``, ``S2SA``, ``S2SW``, ``S2SWA``, ``S2SL``, ``S2SWL``, ``S2SWAL``, ``NG-GODAS``, ``HAFS``, ``HAFSW``, ``HAFS-MOM6``, ``HAFS-MOM6W``, ``HAFS-ALL`` .. _suites: @@ -37,14 +37,15 @@ Physics Options | ``FV3_GFS_v17_p8_mynn`` | ``FV3_GFS_v17_p8_rrtmgp`` | ``FV3_GFS_v17_p8_ugwpv1`` + | ``FV3_GFS_v17_p8_ugwpv1_tempo`` | ``FV3_GFS_v16`` | ``FV3_GFS_v16_csawmg`` | ``FV3_GFS_v16_flake`` | ``FV3_GFS_v16_ras`` - | ``FV3_GFS_v15p2`` | ``FV3_GFS_v15_thompson_mynn_lam3km`` | ``FV3_global_nest_v1`` | ``FV3_HAFS_v1_gfdlmp_tedmf`` + | ``FV3_HAFS_v1_gfdlmpv3_tedmf`` | ``FV3_HAFS_v1_gfdlmp_tedmf_nonsst`` | ``FV3_HAFS_v1_thompson`` | ``FV3_HAFS_v1_thompson_nonsst`` @@ -52,6 +53,7 @@ Physics Options | ``FV3_HRRR`` | ``FV3_HRRR_c3`` | ``FV3_HRRR_gf`` + | ``FV3_ideal_mp_nssl`` | ``FV3_RAP`` | ``FV3_RAP_cires_ugwp`` | ``FV3_RAP_clm_lake`` @@ -63,56 +65,98 @@ Physics Options | ``FV3_RRFS_v1beta`` | ``FV3_RRFS_v1nssl`` | ``FV3_WoFS_v0`` + | ``MPAS_RRFS`` .. _other-build-options: Other Build Options ======================= -``-DCMEPS_AOFLUX``: (Default: OFF) - Enables atmosphere-ocean flux calculation in mediator. - Valid values: ``ON`` | ``OFF`` +``-D32BIT`` (Default: OFF) + Enable 32BIT (single precision arithmetic in dycore and fast physics). + Valid values: ``ON`` | ``OFF`` - .. COMMENT: But when/why would you do this? +``-DCCPP_32BIT`` (Default: OFF) + Enable CCPP_32BIT (single precision arithmetic in dycore and slow physics). + Valid values: ``ON`` | ``OFF`` -``-DDEBUG``: (Default: OFF) - Enables DEBUG mode. - Valid values: ``ON`` | ``OFF`` +``-DAVX2`` (Default: ON) + Enable AVX2 instruction set. + Valid values: ``ON`` | ``OFF`` - .. COMMENT: And what extras does DEBUG mode provide (that VERBOSE) doesn't? +``-DAVX`` (Default: OFF) + Enable AVX-I instruction set. + Valid values: ``ON`` | ``OFF`` -``-D32BIT``: (Default: OFF) - Enables 32-bit, single precision arithmetic in dycore and fast physics. - Valid values: ``ON`` | ``OFF`` +``-DSIMDMULTIARCH`` (Default: OFF) + Enable multi-target SIMD instruction sets. + Valid values: ``ON`` | ``OFF`` - .. COMMENT: But when/why would you do this? +``-DDEBUG`` (Default: OFF) + Enable DEBUG mode. + Valid values: ``ON`` | ``OFF`` -``-DCCPP_32BIT``: (Default: OFF) - Enables 32-bit, single precision arithmetic in slow physics. - Valid values: ``ON`` | ``OFF`` +``-DDISABLE_FMA`` (Default: OFF) + Disable Fused Multiply-Add instructions (workaround needed for AMD EPYC). + Valid values: ``ON`` | ``OFF`` - .. COMMENT: But when/why would you do this? +``-DINLINE_POST`` (Default: ON) + Enable inline post. + Valid values: ``ON`` | ``OFF`` -``-DMOVING_NEST``: (Default: OFF) - Enables moving nest code. - Valid values: ``ON`` | ``OFF`` +``-DMULTI_GASES`` (Default: OFF) + Enable MULTI_GASES. + Valid values: ``ON`` | ``OFF`` - .. COMMENT: But what does that mean? When/why is the moving nest used? +``-DMOVING_NEST`` (Default: OFF) + Enable moving nest code. + Valid values: ``ON`` | ``OFF`` -``-DMULTI_GASES``: (Default: OFF) - Enable ``MULTI_GASES``. - Valid values: ``ON`` | ``OFF`` +``-DREGIONAL_MOM6`` (Default: OFF) + Enable Regional MOM6. + Valid values: ``ON`` | ``OFF`` - .. COMMENT: But what does this DO?! And when/why is it used? +``-DOPENMP`` (Default: ON) + Enable OpenMP threading. + Valid values: ``ON`` | ``OFF`` +``-DPARALLEL_NETCDF`` (Default: OFF) + Enable parallel NetCDF. + Valid values: ``ON`` | ``OFF`` -.. COMMENT: Add any of the following options with -D in front??? - set(AVX2 ON CACHE BOOL "Enable AVX2 instruction set") - set(AVX OFF CACHE BOOL "Enable AVX-I instruction set") - set(SIMDMULTIARCH OFF CACHE BOOL "Enable multi-target SIMD instruction sets") - set(INLINE_POST OFF CACHE BOOL "Enable inline post") - set(OPENMP ON CACHE BOOL "Enable OpenMP threading") - set(PARALLEL_NETCDF OFF CACHE BOOL "Enable parallel NetCDF") - set(JEDI_DRIVER OFF CACHE BOOL "Enable JEDI as top level driver") +``-DJEDI_DRIVER`` (Default: OFF) + Enable JEDI as top level driver. + Valid values: ``ON`` | ``OFF`` +``-DCMEPS_AOFLUX`` (Default: OFF) + Enable atmosphere-ocean flux calculation in mediator. + Valid values: ``ON`` | ``OFF`` + +``-DPDLIB`` (Default: OFF) + Enable domain decomposition in WW3 via PDLIB with BT1. + Valid values: ``ON`` | ``OFF`` + +``-DPDLIB_BT4`` (Default: OFF) + Enable domain decomposition in WW3 via PDLIB with BT4. + Valid values: ``ON`` | ``OFF`` + +``-DCDEPS_INLINE`` (Default: OFF) + Enable CDEPS inline capability. + Valid values: ``ON`` | ``OFF`` + +``-DHYDRO`` (Default: OFF) + Enable hydrostatic set. + Valid values: ``ON`` | ``OFF`` + +``BUILD_WITH_IFI`` (Default: OFF) + Build UPP with In-Flight Icing (IFI) library if present. + Valid values: ``ON`` | ``OFF`` + +``REQUIRE_IFI`` (Default: OFF) + Abort if libIFI is not found ; enables BUILD_WITH_IFI=ON. + Valid values: ``ON`` | ``OFF`` + +``INTERNAL_IFI`` (Default: OFF) + Compile with IFI inside the executable, instead of a library. + Valid values: ``ON`` | ``OFF`` diff --git a/doc/UsersGuide/source/FAQ.rst b/doc/UsersGuide/source/FAQ.rst index 557750bd63..9a010498c8 100644 --- a/doc/UsersGuide/source/FAQ.rst +++ b/doc/UsersGuide/source/FAQ.rst @@ -78,7 +78,7 @@ For all systems, users will need to: .. code-block:: console - Job 7430255 finished for user Joe.Schmoe in partition hera with exit code 0:0 + Job 7430255 finished for user Joe.Schmoe in partition ursa with exit code 0:0 There is also a RESOURCE STATISTICS summary at the end of the test's ``out`` file. Errors will appear in the ``err`` file. Users can find log files with more detailed information in ``ufs-weather-model/tests/logs/log_`` (where platform is the name of the machine the user is running on, e.g., ``log_hercules``). @@ -224,10 +224,10 @@ tasks, as long as those components do not overlap (i.e., share the same PETs). An example of a global five-component coupled configuration ``ufs.configure`` appears at the end of this section. -FV3atm +UFSATM ^^^^^^ -The FV3atm component consists of one or more forecast grid components +The UFSATM component consists of one or more forecast grid components and write grid components. The MPI tasks for the forecast grid components are specified in the @@ -250,7 +250,7 @@ not support an ``8,8`` layout for a blocksize of 32. If ``layout = a ``blocksize=32``. A layout of ``4,6`` is supported for C96 with a blocksize of 32. -The FV3atm will utilize the write grid component if ``quilting`` is +The UFSATM will utilize the write grid component if ``quilting`` is set to .true. In this case, the required MPI tasks for the write grid component are the product of the ``write_groups`` and the ``write_tasks_per_group`` in the ``model_configure`` file. @@ -264,7 +264,7 @@ write grid component are the product of the ``write_groups`` and the In the above case, the write grid component requires 60 tasks. -The total number of MPI ranks for FV3atm is the sum of the forecast tasks and any +The total number of MPI ranks for UFSATM is the sum of the forecast tasks and any write grid component tasks. :: @@ -275,7 +275,7 @@ If ESMF-managed threading is used, the total number of PETs for the atmosphere component is given by the product of the number of threads requested and the total number of MPI ranks (both forecast and write grid component). If ``num_threads_atm`` is the number of threads -specified for the FV3atm component, in ``ufs.configure`` the ATM PET +specified for the UFSATM component, in ``ufs.configure`` the ATM PET bounds are given by: :: @@ -289,12 +289,12 @@ Note that in UFS WM, the ATM component is normally listed first in GOCART ^^^^^^ -GOCART shares the same grid and forecast tasks as FV3atm, but it does +GOCART shares the same grid and forecast tasks as UFSATM, but it does not have a separate write grid component in its NUOPC CAP. Also, while GOCART does not have threading capability, it shares the same data -structure as FV3atm and so it has to use the same number of threads -used by FV3atm. Therefore, the total number of MPI ranks and threads -in GOCART is the same as the those for the FV3atm forecast component +structure as UFSATM and so it has to use the same number of threads +used by UFSATM. Therefore, the total number of MPI ranks and threads +in GOCART is the same as the those for the UFSATM forecast component (i.e., excluding any write grid component). Currently, GOCART only runs on the global forecast grid component, for which only one namelist is needed. @@ -310,7 +310,7 @@ CMEPS ^^^^^ The mediator MPI tasks can overlap with other components and in UFS -the tasks are normally shared on the FV3atm forecast tasks. However, a +the tasks are normally shared on the UFSATM forecast tasks. However, a large number of tasks for the mediator is generally not recommended since it may cause slow performance. This means that the number of MPI tasks for CMEPS is given by @@ -620,7 +620,7 @@ Where can I find up-to-date documentation for the ``diag_table`` variables used =========================================================================================================== Information on ``diag_table`` variables has been added to the :ref:`diag_table section ` of the UFS Weather Model documentation. -Currently, only variables coming from fv3atm and MOM6 are included, but ``diag_table`` variables from other components will be added as time permits. +Currently, only variables coming from UFSATM and MOM6 are included, but ``diag_table`` variables from other components will be added as time permits. * :ref:`FV3ATM diag_table variables ` * `MOM6 diag_table variables `_ diff --git a/doc/UsersGuide/source/Glossary.rst b/doc/UsersGuide/source/Glossary.rst index 8a0070b2eb..3cb92477db 100644 --- a/doc/UsersGuide/source/Glossary.rst +++ b/doc/UsersGuide/source/Glossary.rst @@ -36,7 +36,10 @@ Glossary CESM The `Community Earth System Model `_ (CESM) is a fully-coupled global climate model developed at the National Center for Atmospheric Research (:term:`NCAR`) in collaboration with colleagues in the research community. - + + CFSR + The `Climate Forecast System Reanlysis `_ (CFSR) is a third generation reanalysis product. + chgres_cube The preprocessing software used to create initial and boundary condition files to "coldstart" the forecast model. It is part of :term:`UFS_UTILS`. @@ -113,6 +116,9 @@ Glossary ICs Initial conditions + + IMS + The `Interactive Multisensor Snow and Ice Mapping System `_. LM4 NUOPC NOAA-GFDL Land Model version 4 @@ -131,6 +137,9 @@ Glossary NCAR The `National Center for Atmospheric Research `_. + + NCEI + The `National Center for Environmental Information `_. NCEP National Centers for Environmental Prediction (NCEP) is a branch of the :term:`National Weather Service ` and consists of nine centers, including the :term:`Environmental Modeling Center `. More information can be found at https://www.weather.gov/ncep/. @@ -152,7 +161,10 @@ Glossary NG-GODAS Next Generation-Global Ocean Data Assimilation System. NG-GODAS is a UFS Weather Model configuration that couples ocean (:term:`MOM6`), sea ice (:term:`CICE6`), and Data Assimilation (DA) capabilities with the :term:`DATM` component of :term:`CDEPS`. - + + NIC + U.S. `National Ice Center `_. + NOAHMP Noah-MP The Noah Multi-Physics (Noah-MP) land surface model (LSM) is an open-source, community-developed LSM that has been incorporated into the UFS Weather Model (WM). It is a UFS WM land component. diff --git a/doc/UsersGuide/source/HSDcontainer.rst b/doc/UsersGuide/source/HSDcontainer.rst index 0cfbaac2b2..f6df08f136 100644 --- a/doc/UsersGuide/source/HSDcontainer.rst +++ b/doc/UsersGuide/source/HSDcontainer.rst @@ -7,7 +7,7 @@ Running UFS WM Idealized Cases in a Container ********************************************** -This chapter provides instructions for running the Unified Forecast System (:term:`UFS`) Weather Model (WM) Hierarchical System Develop (HSD) cases using a `Singularity/Apptainer `_ container. Normally, the details of building and running Earth system models will vary based on the computing platform because there are many possible combinations of operating systems, compilers, :term:`MPIs `, and package versions available. Installation via Singularity/Apptainer container reduces this variability and allows for a smoother experience building and running the UFS WM. This approach is recommended for users not running the UFS WM on a supported :wm-wiki:`Level 1 ` system (e.g., Hera, Orion). +This chapter provides instructions for running the Unified Forecast System (:term:`UFS`) Weather Model (WM) Hierarchical System Develop (HSD) cases using a `Singularity/Apptainer `_ container. Normally, the details of building and running Earth system models will vary based on the computing platform because there are many possible combinations of operating systems, compilers, :term:`MPIs `, and package versions available. Installation via Singularity/Apptainer container reduces this variability and allows for a smoother experience building and running the UFS WM. This approach is recommended for users not running the UFS WM on a supported :wm-wiki:`Level 1 ` system (e.g., Ursa, Orion). The container includes: spack-stack, Intel’s runtime environment, ufs-weather-model repository, and the prebuilt executables for the HSD cases. These are all the components needed to run the HSD cases besides the HSD data, which is discussed later in this chapter. @@ -113,7 +113,7 @@ On many NOAA :term:`RDHPCS`, a container named ``ubuntu22.04-intel-ue-1.6.0-wm-h +====================+========================================================+ | Gaea | /gpfs/f6/bil-fire8/world-shared/containers | +--------------------+--------------------------------------------------------+ - | Hera | /scratch3/NCEPDEV/nems/role.epic/containers | + | Ursa | /scratch3/NCEPDEV/nems/role.epic/containers | +--------------------+--------------------------------------------------------+ | NOAA Cloud [#fn]_ | /contrib/EPIC/containers | +--------------------+--------------------------------------------------------+ @@ -237,7 +237,7 @@ where: * ``-c`` is the compiler on the user's local machine (e.g., ``intel/2022.1.2``, ``intel-oneapi-compilers/2022.2.1``, ``intel/2023.2.0``) * ``-m`` is the :term:`MPI` on the user's local machine (e.g., ``impi/2022.1.2``, ``intel-oneapi-mpi/2021.7.1``, ``cray-mpich/8.1.28``) - * ``-p`` refers to the local machine/platform (e.g., ``hera``, ``gaea``, ``noaacloud``). Required for Gaea, Hercules, and Orion only. + * ``-p`` refers to the local machine/platform (e.g., ``ursa``, ``gaea``, ``noaacloud``). Required for Gaea, Hercules, and Orion only. * ``-i`` is the full path to the container image (e.g., ``$img`` or ``$HSD/ubuntu22.04-intel-ue-1.6.0-wm-hsd.img``). .. note:: diff --git a/doc/UsersGuide/source/IdealizedTC.rst b/doc/UsersGuide/source/IdealizedTC.rst index 6c04ccdd03..64c12376fb 100644 --- a/doc/UsersGuide/source/IdealizedTC.rst +++ b/doc/UsersGuide/source/IdealizedTC.rst @@ -3,9 +3,9 @@ .. _idealized-tc: -************************************** +******************************************* Idealized, Regional Tropical Cyclone Case -************************************** +******************************************* The idealized, regional tropical cyclone case is derived from the I-HAFS configuration (:cite:t:`Wang2024`) and is designed to support controlled studies of tropical cyclone dynamics and forecast development. It uses the ``FV3_HAFS_v1_thompson_nonsst`` physics suite, which is documented in the `DTC UFS HAFS v1 Scientific Documentation `_. The configuration used in this case removes real-world data assimilation and ocean coupling, focusing solely on atmospheric forecasts using idealized inputs. @@ -89,7 +89,7 @@ Change to something like: .. code-block:: console - WLCLK=08:00 + WLCLK=480 This allows enough time (6–8 hours recommended) for the full 120-hour simulation to run, depending on system performance. diff --git a/doc/UsersGuide/source/InputsOutputs.rst b/doc/UsersGuide/source/InputsOutputs.rst index d73f500ebc..858c783237 100644 --- a/doc/UsersGuide/source/InputsOutputs.rst +++ b/doc/UsersGuide/source/InputsOutputs.rst @@ -4,6 +4,11 @@ Data: Input, Model Configuration, and Output Files ***************************************************** +.. attention:: + + The most up-to-date files are located in the `UFS Weather Model Regression Test Data Bucket `_ for the most recent dates listed. + File descriptions will appear below, but due to ongoing updates, we cannot guarantee that every file will appear, especially when running different configurations. + The UFS Weather Model can be run in one of several configurations (sometimes referred to as "applications"), from a single-component atmospheric model to a fully coupled model with multiple earth system components (e.g., atmosphere, ocean, sea-ice and mediator). Currently, supported configurations include: @@ -16,45 +21,45 @@ mediator). Currently, supported configurations include: * - Configuration Name - Description - * - :ref:`ATM ` + * - ATM - Standalone Atmospheric Model (:term:`ATM`) - * - :ref:`ATMW ` + * - ATMW - :term:`ATM` coupled to :term:`WW3` - * - :ref:`ATMAERO ` + * - ATMAERO - :term:`ATM` coupled to :term:`GOCART` - * - :ref:`ATMAQ ` + * - ATMAQ - :term:`ATM` coupled to :term:`CMAQ` - * - :ref:`ATML ` + * - ATML - :term:`ATM` coupled to :term:`NOAHMP` - * - :ref:`ATMF ` + * - ATMF - :term:`ATM` coupled to the Community Fire Behavior Model (aka :term:`UFS FIRE`) - * - :ref:`ATM_DS2S ` + * - ATM_DS2S - Coupled :term:`ATM` - :term:`DOCN` - :term:`DICE` - :term:`CDEPS` - * - :ref:`ATM_DS2S-PCICE ` + * - ATM_DS2S-PCICE - Coupled :term:`ATM` - :term:`DOCN` - :term:`CICE6` (prescribed ice mode) - :term:`CDEPS` - * - :ref:`S2S ` + * - S2S - Coupled :term:`ATM` - :term:`MOM6` - :term:`CICE6` - :term:`CMEPS` - * - :ref:`S2SA ` + * - S2SA - Coupled :term:`ATM` - :term:`MOM6` - :term:`CICE6` - :term:`GOCART` - :term:`CMEPS` - * - :ref:`S2SW ` + * - S2SW - Coupled :term:`ATM` - :term:`MOM6` - :term:`CICE6` - :term:`WW3` - :term:`CMEPS` - * - :ref:`S2SWA ` + * - S2SWA - Coupled :term:`ATM` - :term:`MOM6` - :term:`CICE6` - :term:`GOCART` - :term:`WW3` - :term:`CMEPS` - * - :ref:`S2SWAL ` + * - S2SWAL - Coupled :term:`ATM` - :term:`MOM6` - :term:`CICE6` - :term:`GOCART` - :term:`WW3` - :term:`CMEPS` - :term:`NOAHMP` - * - :ref:`NG-GODAS ` + * - NG-GODAS - Coupled :term:`CDEPS` - :term:`DATM` - :term:`MOM6` - :term:`CICE6` - :term:`CMEPS` - * - :ref:`LND ` + * - LND - Coupled :term:`CDEPS` - :term:`DATM` - :term:`NOAHMP` - * - :ref:`LND-LM4 ` + * - LND-LM4 - Coupled :term:`CDEPS` - :term:`DATM` - :term:`LM4` - * - :ref:`HAFS ` + * - HAFS - Coupled :term:`ATM` - :term:`HYCOM` - :term:`CMEPS` - * - :ref:`HAFSW ` + * - HAFSW - Coupled :term:`ATM` - :term:`HYCOM` - :term:`WW3` - :term:`CMEPS` - * - :ref:`HAFS-MOM6W ` - - Coupled :term:`ATM` - :term:`HYCOM` - :term:`CMEPS` - * - :ref:`HAFS-ALL ` + * - HAFS-MOM6W + - Coupled :term:`ATM` - :term:`MOM6`- :term:`WW3` - :term:`CMEPS` + * - HAFS-ALL - Coupled :term:`CDEPS` - :term:`ATM` - :term:`HYCOM` - :term:`WW3` - :term:`CMEPS` .. COMMENT: Should HAFS-ALL be DATM instead of ATM? @@ -97,8 +102,12 @@ The static input files for global configurations are listed and described in :nu - Description * - aerosol.dat - External aerosols data file + * - CCN_ACTIVATE.BIN + - Cloud condensation nuclei activation binary file * - CFSR.SEAICE.1982.2012.monthly.clim.grb - - CFS reanalysis of monthly sea ice climatology + - :term:`CFS ` reanalysis of monthly sea ice climatology + * - freezeH2O.dat + - Defines freezing behavior of water under different temperatures and pressures * - co2historicaldata_YYYY.txt - Monthly CO2 in PPMV data for year YYYY * - global_albedo4.1x1.grb @@ -136,6 +145,12 @@ The static input files for global configurations are listed and described in :nu - Climatological vegetation type * - global_zorclim.1x1.grb - Climatological surface roughness + * - IMS-NIC.blended.ice.monthly.clim.grb + - Monthly climatology of global sea ice concentration from blended :term:`IMS` and :term:`NIC` datasets + * - qr_acr_qgV2.dat + - Precomputed data for rain-graupel collection processes + * - qr_acr_qsV2.dat: + - Precomputed data for rain–snow collection processes * - RTGSST.1982.2012.monthly.clim.grb - Monthly, climatological, real-time global sea surface temperature * - seaice_newland.grb @@ -224,7 +239,7 @@ MOM6 Static Datasets (i.e., *fix files*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The static input files for global configurations are listed and described in :numref:`Table %s `. +The static input files for global configurations are listed and described in :numref:`Table %s `. Note that not all files are required for all resolutions. .. _MOM6_FixFiles: @@ -235,33 +250,39 @@ The static input files for global configurations are listed and described in :nu * - Filename - Description - Used in resolution - * - runoff.daitren.clim.1440x1080.v20180328.nc + * - runoff.daitren.clim.1440x1080.v20180328.nc - climatological runoff - 0.25 - * - runoff.daitren.clim.720x576.v20180328.nc + * - runoff.daitren.clim.720x576.v20180328.nc - climatological runoff - 0.50 - * - seawifs-clim-1997-2010.1440x1080.v20180328.nc + * - runoff.daitren.iaf.720x576.v20180328.nc + - interannually varying runoff forcing + - 0.50 + * - seawifs-clim-1997-2010.1440x1080.v20180328.nc - climatological chlorophyll concentration in sea water - 0.25 - * - seawifs-clim-1997-2010.720x576.v20180328.nc + * - seawifs-clim-1997-2010.720x576.v20180328.nc - climatological chlorophyll concentration in sea water - 0.50 - * - seawifs_1998-2006_smoothed_2X.nc + * - seawifs_1998-2006_smoothed_2X.nc - climatological chlorophyll concentration in sea water - 1.00 - * - tidal_amplitude.v20140616.nc + * - tidal_amplitude.v20140616.nc - climatological tide amplitude - 0.25 - * - tidal_amplitude.nc + * - tidal_amplitude.nc - climatological tide amplitude - 0.50, 1.00 - * - geothermal_davies2013_v1.nc + * - geothermal_davies2013_v1.nc - climatological geothermal heat flow - 0.50, 0.25 - * - KH_background_2d.nc + * - KH_background_2d.nc - climatological 2-d background harmonic viscosities - 1.00 + * - salt_restore_PHC2.720x576.v20180405.nc + - climatological salinity restoring field (PHC source) + - 0.50 .. _mom-grid-ic-files: @@ -279,49 +300,105 @@ The input files containing grid information and the initial conditions for globa * - Filename - Description - - Valid RES options + - Valid resolution options - Date-dependent - * - ocean_hgrid.nc + * - ocean_hgrid.nc - horizonal grid information - - 1.00, 0.50, 0.25 + - 9.00, 5.00, 1.00, 0.50, 0.25 + - + * - oceanda_zgrid_25L.nc + - defines the vertical z-coordinate depth structure for 25 ocean layers used in data assimilation + - 5.00 - - * - ocean_mosaic.nc + * - vgrid_75_2m.nc + - vertical grid levels + - 1.00 + - + * - ocean_mosaic.nc - specify horizonal starting and ending points index - - 1.00, 0.50, 0.25 + - 9.00, 5.00, 1.00, 0.50, 0.25 - - * - ocean_topog.nc + * - ocean_topog.nc - ocean topography - - 1.00, 0.50, 0.25 + - 0.50, 0.25 - - * - ocean_mask.nc - - lans/sea mask - - 1.00, 0.50, 0.25 + * - ocean_mask.nc + - ocean mask + - 9.00, 5.00, 1.00, 0.50, 0.25 + - + * - ocean_static.nc + - static ocean grid and mask data + - 0.50 + - + * - land_mosaic_tile1Xocean_mosaic_tile1.nc + - land/ocean mosaic tiles + - 1.00, 0.50 + - + * - atmos_mosaic_tile1Xland_mosaic_tile1.nc + - atmosphere/land mosaic tiles + - 1.00 + - + * - atmos_mosaic_tile1Xocean_mosaic_tile1.nc + - atmosphere/ocean mosaic tiles + - 1.00 - - * - hycom1_75_800m.nc + * - land_mask.nc + - land mask + - 1.00, 0.50 + - + * - basin_codes.nc + - ocean basin classification grid + - 0.50 + - + * - hycom1_25.nc + - vertical coordinate thickness defining 25 vertical levels + - 9.00, 5.00 + - + * - hycom1_75_800m.nc - vertical coordinate level thickness - 1.00, 0.50, 0.25 - - * - layer_coord.nc + * - layer_coord.nc - vertical layer target potential density - 1.00, 0.50, 0.25 - - * - All_edits.nc + * - layer_coord25.nc + - vertical layer target potential density defining 25 vertical levels + - 9.00, 5.00 + - + * - All_edits.nc - specify grid points where topography are manually modified to adjust throughflow strength for narrow channels - 0.25 - - * - topo_edits_011818.nc + * - topo_edits_011818.nc - specify grid points where topography are manually modified to adjust throughflow strength for narrow channels - 1.00 - - * - MOM_channels_global_025 + * - ufs.topo_edits_011818.nc + - UFS specific grid points where topography are manually modified to adjust throughflow strength for narrow channels + - 1.00 + - + * - topog.nc + - topography + - 9.00, 1.00, 0.25 + - + * - MOM_channels_global_025 - specifies restricted channel widths - 0.50, 0.25 - - * - MOM_channel_SPEAR + * - MOM_layout + - specifies parameters for testing mask_tables in a non-FRE enviroment (production use is not recommended ) + - 0.50, 0.25 + - + * - MOM_override + - blank file for overriding default MOM6 parameters + - 9.00, 5.00, 1.00, 0.50, 0.25 + - + * - MOM_channels_SPEAR - specifies restricted channel widths - 1.00 - - * - interpolate_zgrid_40L.nc + * - interpolate_zgrid_40L.nc - specify target depth for output - 1.00, 0.50, 0.25 - @@ -330,10 +407,26 @@ The input files containing grid information and the initial conditions for globa - 0.25 - ✔ * - MOM6_IC_TS.nc - - ocean temperature and salinity initial conditions (from CFSR) + - ocean temperature and salinity initial conditions (from :term:`CFSR`) - 1.00, 0.50, 0.25 - ✔ - + * - woa18_decav_s00_01.nc + - global annual climatological average ocean salinity from 1955–2017 (from :term:`NCEI`) + - 1.00 + - ✔ + * - woa18_decav_t00_01.nc + - global annual climatological average ocean temperature from 1955–2017 (from :term:`NCEI`) + - 1.00 + - ✔ + * - mom6.mx050.2021032206.warmstart.nc + - MOM6 warm restart file + - 0.50 + - ✔ + * - mom6.mx100.2021032206.warmstart.nc + - MOM6 warm restart file + - 1.00 + - ✔ + .. _hycom-in: ------- @@ -530,14 +623,22 @@ The input files containing grid information and the initial conditions for globa - cice model IC or restart file - 1.00, 0.50, 0.25 - ✔ + * - cice.mxRES.YYYYMMDDHH.warmstart.nc + - warm restart file used to continue a previous CICE run from an existing model state + - 1.00, 0.50 + - ✔ * - grid_cice_NEMS_mxRES.nc - cice model grid at resolution RES - - 100, 050, 025 + - 9.00, 5.00, 1.00, 0.50, 0.25 - * - kmtu_cice_NEMS_mxRES.nc - cice model land mask at resolution RES - - 100, 050, 025 + - 9.00, 5.00, 1.00, 0.50, 0.25 - + * - mesh.mxRES.nc + - CICE mesh at resolution RES + - 9.00, 5.00, 1.00, 0.50, 0.25 + - .. _ww3-in: @@ -679,7 +780,7 @@ Coupled regional configurations require forcing files to fill regions that canno - Interpolated wind data from GFS - 6 min -The model driver input (ww3_multi.inp) includes the input, model and output grids definition, the starting and ending times for the entire model run and output types and intervals. The ww3_multi.inp.IN template is located under tests/parm/ directory. The inputs are described hereinafter: +The model driver input (ww3_shel.nml.IN) includes the input, model and output grids definition, the starting and ending times for the entire model run and output types and intervals. The ww3_multi.inp.IN template is located under tests/parm/ directory. The inputs are described hereinafter: .. _WW3_Driver: @@ -806,7 +907,7 @@ The input files containing grid information and the time-varying forcing files f .. note:: - Users can find atmospheric forcing files for use with the land (:ref:`LND `) component in the `Land Data Assimilation (DA) data bucket `_. These files provide atmospheric forcing data related to precipitation, solar radiation, longwave radiation, temperature, pressure, winds, humidity, topography, and mesh data. Forcing files for the land component configuration come from the Global Soil Wetness Project Phase 3 (`GSWP3 `_) dataset. + Users can find atmospheric forcing files for use with the Noah-MP land component (LND) in the `Land Data Assimilation (DA) data bucket `_. These files provide atmospheric forcing data related to precipitation, solar radiation, longwave radiation, temperature, pressure, winds, humidity, topography, and mesh data. Forcing files for the land component configuration come from the Global Soil Wetness Project Phase 3 (`GSWP3 `_) dataset. .. code-block:: console @@ -1267,7 +1368,7 @@ Registration of diagnostic fields is done using the following syntax diag_id = register_diag_field(module_name, diag_name, axes, ...) -in file ``FV3/atmos_cubed_sphere/tools/fv_diagnostics.F90``. As an example, the sea level pressure is registered as: +in file ``ufsatm/FV3/atmos_cubed_sphere/tools/fv_diagnostics.F90``. As an example, the sea level pressure is registered as: .. code-block:: console @@ -1330,13 +1431,12 @@ Each WM component has its own ``diag_table`` with associated variables. :numref: * - WM Component - Diag Table - Source File - * - FV3 + * - UFSatm - :ref:`FV3 Variables ` - - `GFS_diagnostics.F90 `_ + - `GFS_diagnostics.F90 `_ * - MOM6 - `MOM6 Variables `_ - - `MOM_diagnostics.F90 `_ - + - `MOM_diagnostics.F90 `_ A brief example of the diag_table is shown below. ``"..."`` denotes where lines have been removed. @@ -2081,8 +2181,7 @@ A sample subset of this namelist is shown below: FNABSC = 'global_mxsnoalb.uariz.t126.384.190.rg.grb' / -Additional variables for the ``&namsfc`` namelist can be found in the ``FV3/ccpp/physics/physics/Interstitials/UFS_SCM_NEPTUNE/sfcsub.F`` file. - +Additional variables for the ``&namsfc`` namelist can be found in the ``ufsatm/ccpp/physics/physics/Interstitials/UFS_SCM_NEPTUNE/sfcsub.F`` file. .. _atmos_model_nml_section: ^^^^^^^^^^^^^^^^^^^^ @@ -2187,8 +2286,7 @@ A sample subset of this namelist is shown below: cplflx = .true. / -Additional variables for the ``&gfs_physics_nml`` namelist can be found in the ``FV3/ccpp/data/GFS_typedefs.F90`` -file. +Additional variables for the ``&gfs_physics_nml`` namelist can be found in the `GFS_typedefs.F90 `_ .. _OutputFiles: @@ -2196,10 +2294,10 @@ file. Output files ============= -.. _fv3atm-out: +.. _UFSatm-out: ------- -FV3Atm +UFSAtm ------- The output files generated when running ``fv3.exe`` are defined in the ``diag_table`` file. For the default global configuration, the following files are output (six files of each kind, corresponding to the six tiles of the model grid): diff --git a/doc/UsersGuide/source/Introduction.rst b/doc/UsersGuide/source/Introduction.rst index 5aef439eca..157f3e628f 100644 --- a/doc/UsersGuide/source/Introduction.rst +++ b/doc/UsersGuide/source/Introduction.rst @@ -6,7 +6,7 @@ Introduction The Unified Forecast System (:term:`UFS`) Weather Model (:term:`WM`) is a prognostic model that can be used for short- and medium-range research and operational forecasts, as exemplified by -its use in the operational Global Forecast System (GFS) of the National Oceanic and +its use in the operational Global Forecast System (GFS) and the Hurricane Analysis and Forecast System (HAFS) of the National Oceanic and Atmospheric Administration (NOAA). In addition to its use in NOAA's operational forecast systems, the UFS WM is the atmospheric model used in public UFS application releases, such as the most recent Short-Range Weather (SRW) Application releases. These releases represent a snapshot of a continuously evolving system undergoing open development. More information about the UFS can be found on the UFS Community Portal at https://ufs.epic.noaa.gov/ and on the Earth Prediction Innovation Center (EPIC) website at https://epic.noaa.gov/get-code/ufs-weather-model/. @@ -31,13 +31,13 @@ for those elements, are listed below: * The regression tests used to maintain software integrity as innovations are added. -The UFS Weather Model is currently included in two UFS Application releases: The UFS Short-Range Weather (:term:`SRW`) Application v3.0.0 release (April 2025) and the UFS Medium Range Weather Application (:term:`MRW`) v1.1.0 release (October 2020). These UFS Apps also contain pre- and post-processing components, a comprehensive build system, and workflows for configuration and execution of the application. The SRW App v3.0.0 documentation and details can be found `here `__. The MRW App v1.1.0 documentation and details can be found `here `__. +The UFS Weather Model is currently included in two UFS Application releases: The UFS Short-Range Weather (:term:`SRW`) Application v3.0.0 release (April 2025) and the Land Data Assimilation (DA) System v2.0.0 release (November 2024). These UFS apps also contain pre- and post-processing components, a comprehensive build system, and workflows for configuration and execution of the application. The SRW App v3.0.0 documentation and details can be found `here `__. The Land DA v2.0.0 documentation and details can be found `here `__. -The UFS WM code is portable and can be used with Linux or Mac operating systems and with Intel or GNU compilers. It has been tested on a variety of platforms widely used by atmospheric scientists, such as the NOAA Research Hera system, the National Center for Atmospheric Research (:term:`NCAR`) Derecho system, the Mississippi State University (MSU) Hercules system, and Mac laptops. +The UFS WM code is portable and can be used with Linux or Mac operating systems and with Intel or GNU compilers. It has been tested on a variety of platforms widely used by atmospheric scientists, such as the NOAA Research Ursa system, the National Center for Atmospheric Research (:term:`NCAR`) Derecho system, and the Mississippi State University (MSU) Hercules system. .. note:: - At this time, the following aspects are unsupported: configurations in which a mediator is used to couple the atmospheric model to models of other earth domains (such as ocean, ice, and waves), horizontal resolutions other than the supported ones, different number or placement of vertical levels, the *cellular automata* stochastic scheme, and the use of different file formats for input and output. It is expected that the UFS WM supported capabilities will be expanded in future releases. + At this time, the following aspects are unsupported: horizontal resolutions other than the supported ones, different number or placement of vertical levels, the *cellular automata* stochastic scheme, and the use of different file formats for input and output. It is expected that the UFS WM supported capabilities will be expanded in future releases. .. COMMENT: Are coupled versions of the WM now supported? With 12 configurations it would seem that perhaps some are? .. COMMENT: Is the cellular automata stochastic scheme now supported? @@ -60,8 +60,6 @@ This WM User's Guide is organized as follows: * :numref:`Chapter %s ` (HSD Technical Documentation) provides detailed technical documentation for the HSD code. * :numref:`Chapter %s ` (Configuration Parameters) lists the purpose and valid values for various configuration parameters. - - * :numref:`Chapter %s ` (Automated Testing) describes UFS WM automated testing options. * :numref:`Chapter %s ` (FAQ) lists frequently asked questions and answers. diff --git a/doc/UsersGuide/source/conf.py b/doc/UsersGuide/source/conf.py index fa5fefafc8..d065b95f79 100644 --- a/doc/UsersGuide/source/conf.py +++ b/doc/UsersGuide/source/conf.py @@ -93,8 +93,7 @@ # Ignore anchor tags for links that show Not Found even when they exist. linkcheck_anchors_ignore = [r"L\d*", r"BM_IC-20220207", - r"input-data-20240501*", - #r"input-data-20240501/WW3_input_data_20240214", + r"input-data-20250507*", ] # Ignore working links that cause a linkcheck 403 error. linkcheck_ignore = [r'https://agupubs\.onlinelibrary\.wiley\.com/doi/10\.1029/2020MS002260', diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst index 78259b2bb9..360df71952 100644 --- a/doc/UsersGuide/source/index.rst +++ b/doc/UsersGuide/source/index.rst @@ -17,7 +17,6 @@ Welcome to the UFS Weather Model User's Guide HSD modules ConfigParameters - AutomatedTesting FAQ Acronyms Glossary