diff --git a/doc/UsersGuide/source/Acronyms.rst b/doc/UsersGuide/source/Acronyms.rst index edf950688d..1395ec20d7 100644 --- a/doc/UsersGuide/source/Acronyms.rst +++ b/doc/UsersGuide/source/Acronyms.rst @@ -62,8 +62,6 @@ Acronyms | RRTMG | Rapid Radiative Transfer Model for Global | | | Circulation Models | +----------------+---------------------------------------------------+ - | RT | Regression test | - +----------------+---------------------------------------------------+ | SAS | Simplified Arakawa-Schubert | +----------------+---------------------------------------------------+ | SDF | Suite Definition File | diff --git a/doc/UsersGuide/source/BuildingAndRunning.rst b/doc/UsersGuide/source/BuildingAndRunning.rst index 6601359df2..00efb1b101 100644 --- a/doc/UsersGuide/source/BuildingAndRunning.rst +++ b/doc/UsersGuide/source/BuildingAndRunning.rst @@ -15,14 +15,14 @@ There are two categories of libraries that are needed: Most have an NCEPLIBS prefix in the repository, e.g. NCEPLIBS-bacio. Select tools from the UFS Utilities repository (UFS-UTILS) are also included in this category. A list of the bundled libraries tested with this WM release is in the top-level ``README`` of the `NCEPLIBS repository - `_ (**be sure to look at the tag in that repository that + `_ (**be sure to look at the tag in that repository that matches the tag on this WM release**). #. Third-party libraries (NCEPLIBS-external). These are libraries that were developed external to the UFS Weather Model. They are general software packages that are also used by other models in the community. Building these is optional, since existing builds of these libraries can be pointed to instead. A list of the external libraries tested with this WM release is in the top-level ``README`` - of the `NCEPLIBS-external repository `_. Again, be + of the `NCEPLIBS-external repository `_. Again, be sure to look at the tag in that repository that matches the tag on this WM release. .. note:: @@ -34,7 +34,7 @@ to build NCEPLIBS and NCEPLIBS-external or are working on a system that is alrea pre-configured platforms, the libraries are already available. If you do have to build the libraries, it is a good idea to check the platform- and compiler-specific -``README`` files in the doc/ directory of the `NCEPLIBS-external repository `_ +``README`` files in the doc/ directory of the `NCEPLIBS-external repository `_ as a first step, to see if your system or one similar to it is included. These files have detailed instructions for building NCEPLIBS-external, NCEPLIBS, and the UFS Weather Model. They may be all the documentation you need. Be sure to use the tag that corresponds to this version of the WM, and define a @@ -42,8 +42,8 @@ WORK directory path before you get started. If your platform is not included in these platform- and compiler-specific ``README`` files, there is a more generic set of instructions in the ``README`` file at the top level of the `NCEPLIBS-external repository -`_, and at the top level of the `NCEPLIBS repository -`_. It may still be a good idea to look at some of the platform- +`_, and at the top level of the `NCEPLIBS repository +`_. It may still be a good idea to look at some of the platform- and compiler-specific ``README`` files as a guide. Again, be sure to use the tag that corresponds to this version of the WM. The top-level ``README`` in the NCEPLIBS-external repository includes a troubleshooting section that may be helpful. @@ -57,13 +57,13 @@ set up specifically for issues related to build dependencies. Downloading the Weather Model Code ================================== -To clone the ufs-weather-model repository for this v1.0.0 release, execute the following commands: +To clone the ufs-weather-model repository for this v1.1.0 release, execute the following commands: .. code-block:: console git clone https://github.com/ufs-community/ufs-weather-model.git ufs-weather-model cd ufs-weather-model - git checkout ufs-v1.0.0 + git checkout ufs-v1.1.0 git submodule update --init --recursive Compiling the model will take place within the `ufs-weather-model` directory you just created. @@ -149,7 +149,7 @@ If you are not running on one of the pre-configured platforms, you will need to in a different way. If you used one of the platform- and compiler-specific ``README`` files in the ``doc/`` directory of NCEPLIBS-external -to build the prerequisite libraries, there is a script in the ``NCEPLIBS-ufs-v1.0.0/bin`` directory called +to build the prerequisite libraries, there is a script in the ``NCEPLIBS-ufs-v1.1.0/bin`` directory called ``setenv_nceplibs.sh`` that will set the NCEPLIBS-external variables for you. Of course, you can also set the values of these variables yourself if you know where the paths are on your system. diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst deleted file mode 100644 index 84edf6446a..0000000000 --- a/doc/UsersGuide/source/ContributingDevelopment.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. _ContributingDevelopment: - -************************* -Contributing Development -************************* - -The ufs-weather-model repository contains the model code and external links needed to build the Unified Forecast System (UFS) atmosphere model and associated components, including the WaveWatch III model. This weather model is used in several of the UFS applications, including the medium-range weather application, the short-range weather application, and the sub-seasonal to seasonal application. - ---------------------------------------------- -Making code changes using a forking workflow ---------------------------------------------- - -If developers would like to make code changes, they need to make a personal fork, set up upstream remote (for merging with the original ufs-weather-model), and create a branch for ufs-weather-model and each of the subcomponent repositories they want to change. They can then make code changes, perform testing and commit the changes to the branch in their personal fork. It is suggested that they update their branch by merging the develop branch with the develop branch of the original repositories periodically to get the latest updates and bug fixes. - -If developers would like to get their code committed back to the original repository, it is suggested to follow the steps below: - -1. Create an issue in the authoritative repository. For example to commit code changes to fv3atm, please go to https://github.com/NOAA-EMC/fv3atm, under NOAA-EMC/fv3atm and find the “Issues” tab next to the “Code” tab. Click on “Issues” and a new page will appear. On the right side of the page, there is a green “New issue” button. Clicking on that will lead to a new issue page. Fill out the title, comments to describe the code changes, and also please provide personal fork and branch information. Lastly, click on the “Submit new issue” button, so that the new issue is created. - -2. When the development is mature, tests have been conducted, and the developer is satisfied with the results, create a pull request to commit the code changes. - - * Merge developer’s branch to the latest ufs-weather-model develop branch in authoritative repository. If changes are made in model sub-components, developers need to merge their branches to branches with the corresponding authoritative repository (or original repository for some components). For this, code management practices of the subcomponents need to be followed. - - * Regression tests associated with the ufs-weather-model are available on Tier 1 and Tier 2 platforms as described in https://github.com/ufs-community/ufs-weather-model/wiki/Regression-Test-Policy-for-Weather-Model-Platforms-and-Compilers. If the developer has access to these platforms, the developer should pass the regression test on at least one supported platform. If the developer does not have access to these platforms, this should be stated in the PR so the code manager(s) can conduct the tests. - - * For each component branch where developers make changes, developers need to go to their personal fork on GitHub and click on the “New pull request” button. When a new page “Compare changes” appears, developers will choose the branch in their fork with code changes to commit and the branch in upstream repository that the changes will be committed to. Also developers in the commit comment must add the github issue title and number created in 1) in the comment box. The code differences between the two branches will be displayed. Developers can review the differences and click on “submit pull request” to make the pull request. After code changes are committed to the component repository, developers will make pull requests to ufs-weather-model repository. - -3. When PRs are created, the creator must temporarily modify .gitmodules to point to his/her fork and branch if updates are required for submodules. - -4. Merging code from PRs with submodules requires coordination with the person making the PRs. From the "innermost" nested PR up to the top-level PR, the PRs need to be merged as-is. After each merge, the person creating the PRs has to update his/her local code to check out the merged version, revert the change to .gitmodules, and push this to GitHub to update the PR. And so on and so forth. - -5. Checking out the code ufs_release_1.0 should always be as follows: - -.. code-block:: console - - git clone https://github.com/ufs-community/ufs-weather-model - cd ufs-weather-model - git checkout ufs_release_1.00 - git submodule update --init --recursive - -6. Checking out a PR with id ID for testing it should always be as follows: - -.. code-block:: console - - git clone https://github.com/ufs-community/ufs-weather-model - cd ufs-weather-model - git fetch origin pull/ID/head:BRANCHNAME - git checkout BRANCHNAME - git submodule update --init --recursive - -It is suggested that the developers inform all the related code managers as the hierarchy structure of the ufs-weather-model repository may require collaboration among the code managers. - ------------------------------------ -Engaging in the code review process ------------------------------------ - -When code managers receive a pull request to commit the code changes, it is recommended that they add at least two code reviewers to review the code and at least one of the reviewers has write permission. The reviewers will write comments about the code changes and give a recommendation as to whether the code changes can be committed. What kinds of code changes will be accepted in the repository is beyond the scope of this document; future ufs-weather-model code management documents may have a detailed answer for that. - -Reviewers may suggest some code changes during the review process. Developers need to respond to these comments in order to get code changes committed. If developers make further changes to their branch, reviewers need to check the code changes again. When both reviewers give recommendation to commit the code, code managers will merge the changes into the repository. - -.. _ConductingRegTests: - ----------------------------- -Conducting regression tests ----------------------------- - -Only developers using Tier 1 and 2 platforms can run the ufs-weather-model regression tests. Other developers need to work with the code managers to assure completion of the regression tests. - -To run regression test using rt.sh - -rt.sh is a bash shell file to run the RT and has the following options: - -.. code-block:: console - - Usage: ./rt.sh -c | -f | -s | -l | -m | -k | -r | -e | -h - -c create new baseline results for - -f run full suite of regression tests - -s run standard suite of regression tests - -l run test specified in - -m compare against new baseline results - -k keep run directory (automatically deleted otherwise if all tests pass) - -r use Rocoto workflow manager - -e use ecFlow workflow manager - -h display this help - -.. code-block:: console - - % cd ufs-weather-model/tests - % ./rt.sh -f - -This command can only be used on platforms that have been configured for regression testing (Tier 1 and Tier 2 platforms as described in https://github.com/ufs-community/ufs-weather-model/wiki/Regression-Test-Policy-for-Weather-Model-Platforms-and-Compilers). For information on testing the CCPP code, or using alternate computational platforms, see the following sections. - -This command and all others below produce log output in ./tests/log_machine.compiler. These log files contain information on the location of the run directories that can be used as templates for the user. Each rt*.conf contains one or more compile commands preceding a number of tests. - -Regression test log files (ufs-weather-model/tests/Compile_$(MACHINE_ID).log and ufs-weather-model/tests/RegressionTests_$(MACHINE_ID).log ) will be updated. - -If developers wish to contribute code that changes the results of the regression tests (because of updates to the physics, for example), it is useful to run rt.sh as described above to make sure that the test failures are as expected. It is then useful to establish a new personal baseline: - -./rt.sh -l rt.conf -c # create own reg. test baseline - -Once the personal baseline has been created, future runs of the RT should be compared against the personal baseline using the -m option. - -./rt.sh -l rt.conf -m # compare against own baseline - -To create new baseline: - -.. code-block:: console - - % cd ufs-weather-model/tests - % ./rt.sh -f -c - -An alternative/complementary regression test system is using NEMSCompsetRun, which focuses more on coupled model configurations than testing features of the standalone ufs-weather-model. To run regression test using NEMSCompsetRun: - -.. code-block:: console - - % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun -f - -Regression test log files (ufs-weather-model/log/$MACHINE_ID/* ) will be updated. - -To create new baseline: - -.. code-block:: console - - % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun --baseline fv3 --platform=${PLATFORM} - -The value of ${PLATFORM} can be found in ufs-weather-model/compsets/platforms.input. - -Developers need to commit the regression test log files to their branch before making pull request. diff --git a/doc/UsersGuide/source/FAQ.rst b/doc/UsersGuide/source/FAQ.rst index c537aefe31..511da9e1c7 100644 --- a/doc/UsersGuide/source/FAQ.rst +++ b/doc/UsersGuide/source/FAQ.rst @@ -10,7 +10,7 @@ How do I build and run a single test of the UFS Weather Model? An efficient way to build and run the UFS Weather Model is to use the regression test (``rt.sh``). This script is widely used by model developers on Tier 1 and 2 platforms -and is described in :numref:`Section %s `. The advantages to this approach are: +and is described in the UFS WM GitHub `wiki `_. The advantages to this approach are: - It does not require a workflow, pre- or post-processing steps. - The batch submission script is generated. diff --git a/doc/UsersGuide/source/InputNML.inc b/doc/UsersGuide/source/InputNML.inc index a0acedc56e..4b3d202f33 100644 --- a/doc/UsersGuide/source/InputNML.inc +++ b/doc/UsersGuide/source/InputNML.inc @@ -14,15 +14,15 @@ physics options are chosen. The following link describes the various physics-related namelist records: -https://dtcenter.org/GMTB/v4.0/sci_doc/CCPPsuite_nml_desp.html +https://dtcenter.org/GMTB/v4.1.0/sci_doc/CCPPsuite_nml_desp.html The following link describes the stochastic physics namelist records: -https://stochastic-physics.readthedocs.io/en/ufs-v1.0.0/namelist_options.html +https://stochastic-physics.readthedocs.io/en/release-ufs-v1.1.0/namelist_options.html The following link describes some of the other namelist records (dynamics, grid, etc): -https://www.gfdl.noaa.gov/wp-content/uploads/2017/09/fv3_namelist_Feb2017.pdf +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. diff --git a/doc/UsersGuide/source/Introduction.rst b/doc/UsersGuide/source/Introduction.rst index 3bb11c5496..7ff396deb9 100644 --- a/doc/UsersGuide/source/Introduction.rst +++ b/doc/UsersGuide/source/Introduction.rst @@ -7,14 +7,14 @@ Introduction The Unified Forecast System (:term:`UFS`) :term:`Weather Model` (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 -Atmospheric Administration (NOAA). The UFS WM v1.0 is the first public release of this +Atmospheric Administration (NOAA). The UFS WM v1.1 is the latest public release of this software and represents a snapshot of a continuously evolving system undergoing open development. More information about the UFS can be found in its portal at https://ufscommunity.org/. Key architectural elements of the UFS WM, along with links to external detailed documentation for those elements, are listed below: -- `The Finite-Volume Cubed-Sphere (FV3) dynamical core `_. +- `The Finite-Volume Cubed-Sphere (FV3) dynamical core `_. - `The Flexible Modeling System `_ (:term:`FMS`), a software infrastructure used for functions such as parallelization. @@ -22,11 +22,11 @@ for those elements, are listed below: - `The Common-Community Physics Package `_ (:term:`CCPP`), a library of physical parameterizations and the framework to use it with the model. :term:`Parameterization or physics scheme` is defined here. -- `The stochastic physics capability `_, including the Stochastic Kinetic Backscatter Scheme (SKEBS), +- `The stochastic physics capability `_, including the Stochastic Kinetic Backscatter Scheme (SKEBS), the Stochastically Perturbed Parameterization Tendencies (SPPT) scheme, the perturbed boundary layer humidity (SHUM) scheme, and the cellular automata method. -- `The NOAA Environmental Modeling System `_ (:term:`NEMS`) model driver used to create the main program. +- `The NOAA Environmental Modeling System `_ (:term:`NEMS`) model driver used to create the main program. - The libraries needed to build the system, such as: - `National Centers for Environmental Prediction (NCEP) Libraries `_ @@ -37,7 +37,7 @@ for those elements, are listed below: - The regression tests used to maintain software integrity as innovations are added. -For the UFS WM v1.0 release, the following aspects are supported: +For the UFS WM v1.1 release, the following aspects are supported: - Global configuration with resolutions of C96 (~100 km), C192 (~50 km), C384 (25 km), and C768 (~13 km) @@ -49,10 +49,9 @@ For the UFS WM v1.0 release, the following aspects are supported: - Ability to run with or without SKEBS, SPPT, and SHUM. -- Ability to initialize from GFS files in Gridded Binary v2 (GRIB2) or NEMS - Input/Output (NEMSIO) format for past dates, - starting January 1, 2018, when the preprocessing utility chgres_cube is employed. Dates before - that may work, but are not guaranteed. +- Ability to initialize from GFS files in Gridded Binary v2 (GRIB2), NEMS Input/Output (NEMSIO), or + Network Common Data Form (netCDF) format for past dates, starting January 1, 2018, when the + preprocessing utility chgres_cube is employed. Dates before that may work, but are not guaranteed. - Output files in Network Common Data Form (NetCDF) format. @@ -68,7 +67,7 @@ This simple ocean scheme keeps the SST constant throughout the forecast and is r conditions do not contain all fields needed to initialize the NSST scheme. -Even when using physics suite GFS_v15p2, the UFS WM v1 differs from the operational GFS v15.2 in a few ways. First, the public release code +Even when using physics suite GFS_v15p2, the UFS WM v1.1 differs from the operational GFS v15.2 in a few ways. First, the public release code reflects the state of development as of the fall of 2019, and therefore the parameterizations contain innovations beyond what is in GFSv15.2 operations. For example, the GFDL microphysics distributed for use in GFS v15.2 and GFS v16beta @@ -90,9 +89,9 @@ The UFS WM v1 code is portable and can be used with Linux and Mac operating syst .. note:: - At this time, the following aspects are unsupported: standalone regional domains, 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, physics suites other than GFS v15.2 and GFS v16beta the *cellular automata* stochastic scheme, initialization from sources other than GFS, the use of different file formats for input and output, and the use of the model in different computational platforms. It is expected that the UFS WM supported capabilities will be expanded in future releases. + At this time, the following aspects are unsupported: standalone regional domains, 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, physics suites other than GFS v15.2 and GFS v16beta, the *cellular automata* stochastic scheme, initialization from sources other than GFS, the use of different file formats for input and output, and the use of the model in different computational platforms. It is expected that the UFS WM supported capabilities will be expanded in future releases. -It should be noted that the UFS WM is a component of the UFS Medium-Range (MR) Weather Application (App), which also contains pre- and post-processing components, a comprehensive build system, and workflows for configuration and execution of the application. At this time, the UFS WM is only supported to the general community for use as part of the UFS MR Weather App. However, those wishing to contribute development to the UFS WM should become familiar with the procedures for running the model as a standalone component and for executing the regression tests described in this guide to make sure no inadvertent changes to the results have been introduced during the development process. +It should be noted that the UFS WM is a component of the UFS Medium-Range (MR) Weather Application (App), which also contains pre- and post-processing components, a comprehensive build system, and workflows for configuration and execution of the application. At this time, the UFS WM is only supported to the general community for use as part of the UFS MR Weather App. However, those wishing to contribute development to the UFS WM should become familiar with the procedures for running the model as a standalone component and for executing the regression tests described in the UFS WM GitHub `wiki `_ to make sure no inadvertent changes to the results have been introduced during the development process. Support for the UFS WM is provided through the `UFS Forum `_ by the Developmental Testbed Center (DTC) and other groups involved in UFS development, such as NOAA’s Environmental Modeling Center (EMC), NOAA research laboratories (GFDL, NSSL, ESRL, and AOML), and NCAR. UFS users and developers are encouraged not only to post questions, but also to help address questions posted by other members of the community. @@ -110,8 +109,6 @@ This WM User’s Guide is organized as follows: contains a description of the :term:`Suite Definition File (SDF)` and namelists needed to configure the model for running with the GFS v15.2 and GFS v16beta physics suites. -- :numref:`Chapter %s ` (Contributing development) goes beyond the capabilities supported in the public release to cover code management for conducting development and proposing contributions back to the authoritative code repositories. It should be noted that the regression tests described here are mandatory for committing code back to the ufs-weather-model authoritative code repository. These regressions tests differ from those distributed with the workflows for UFS applications, which are intended for application users and developers to assess the quality of their installations and the impact of their code changes. - - :numref:`Chapter %s ` (FAQ) lists frequently asked questions and answers. Finally, :numref:`Chapters %s ` and :numref:`%s ` contain a list of acronyms and a glossary, respectively. diff --git a/doc/UsersGuide/source/SDFandNamelistExamplePractices.rst b/doc/UsersGuide/source/SDFandNamelistExamplePractices.rst index 8f54bb0b20..b389c2f4dd 100644 --- a/doc/UsersGuide/source/SDFandNamelistExamplePractices.rst +++ b/doc/UsersGuide/source/SDFandNamelistExamplePractices.rst @@ -8,15 +8,15 @@ The public release of the UFS MR Weather App includes four supported physics sui GFS_v15p2, GFS_v15p2_no_nsst, GFS_v16beta, and GFS_v16beta_no_nsst. You will find the Suite Definition Files (SDFs) for these suites in -https://github.com/NOAA-EMC/fv3atm/tree/ufs-v1.0.0/ccpp/suites +https://github.com/NOAA-EMC/fv3atm/tree/ufs-v1.1.0/ccpp/suites (no other SDFs are available with this release). You will find the namelists for the C96 configuration here: -https://github.com/ufs-community/ufs-weather-model/tree/ufs-v1.0.0/parm/ccpp_v15p2_c96.nml.IN +https://github.com/ufs-community/ufs-weather-model/tree/ufs-v1.1.0/parm/ccpp_v15p2_c96.nml.IN and -https://github.com/ufs-community/ufs-weather-model/tree/ufs-v1.0.0/parm/ccpp_v16beta_c96.nml.IN +https://github.com/ufs-community/ufs-weather-model/tree/ufs-v1.1.0/parm/ccpp_v16beta_c96.nml.IN As noted in the file names, these namelists are for the operational (v15p2) and developmental (v16beta) GFS suites. Each of these namelists are relevant to the suites with and without the SST prediction scheme, that is, @@ -24,16 +24,16 @@ they are relevant for the suite that employs NSST and for the suite that employs model (`no_nsst`). The only difference in the namelist regarding how SST prediction is addressed is variable `nstf_name`. For more information about this variable and for information about namelist options for higher resolution configurations, please consult the -`CCPP v4 Scientific Documentation `_. +`CCPP v4.1.0 Scientific Documentation `_. The four CCPP suites for the UFS MR Weather App release are supported in four grid resolutions: C96, C192, C384, and C768, with 64 vertical levels. An in depth description of the namelist settings, SDFs, and parameterizations used -in all supported suites can be found in the `CCPP v4 Scientific Documentation `_. +in all supported suites can be found in the `CCPP v4.1.0 Scientific Documentation `_. Note both suites do not use stochastic physics by default, but the stochastic physics can be activated following the -instructions described in the `stochastic physics v1 user's guide `_. +instructions described in the `stochastic physics v1.1 user's guide `_. Both the SDF and the *input.nml* contain information about how to specify the physics suite. Some of this information is redundant, and the user must make sure they are compatible. The diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst index 98914f4eee..8100ee51c1 100644 --- a/doc/UsersGuide/source/index.rst +++ b/doc/UsersGuide/source/index.rst @@ -15,7 +15,6 @@ Welcome to the UFS Weather Model User's Guide BuildingAndRunning InputsOutputs SDFandNamelistExamplePractices - ContributingDevelopment FAQ Acronyms Glossary