Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Doc updates #75

Merged
merged 6 commits into from
Mar 5, 2020
Merged

Doc updates #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a34c165
Remove FAQ chapter until we can populate it (post-release).
ligiabernardet Mar 5, 2020
5a4f282
Remove unused chapter
ligiabernardet Mar 5, 2020
93003ff
Fixed link to supported platforms for regression tests.
ligiabernardet Mar 5, 2020
b11ddde
Clarify location of documentation to build NCEPLibs. Fix formatting.
ligiabernardet Mar 5, 2020
738dd70
Add ability to initialize from NEMSIO format. Fix formatting issues.
ligiabernardet Mar 5, 2020
b60472d
Multiple updates to documentation. Removed un-used entries from lists…
ligiabernardet Mar 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 4 additions & 18 deletions doc/UsersGuide/source/Acronyms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Acronyms
:widths: 20 80

+----------------+---------------------------------------------------+
| Abbreviation | Explanation |
| Acronyms | Explanation |
+================+===================================================+
| AOML | NOAA's Atlantic Oceanographic and Meteorological |
| | Laboratory |
Expand All @@ -19,8 +19,6 @@ Acronyms
+----------------+---------------------------------------------------+
| CCPP | Common Community Physics Package |
+----------------+---------------------------------------------------+
| CPP | C preprocessor |
+----------------+---------------------------------------------------+
| dycore | Dynamical core |
+----------------+---------------------------------------------------+
| EDMF | Eddy-Diffusivity Mass Flux |
Expand All @@ -29,13 +27,13 @@ Acronyms
+----------------+---------------------------------------------------+
| ESMF | The Earth System Modeling Framework |
+----------------+---------------------------------------------------+
| ESRL | NOAA Earth System Research Laboratory |
| ESRL | NOAA Earth System Research Laboratories |
+----------------+---------------------------------------------------+
| FMS | Flexible Modeling System |
+----------------+---------------------------------------------------+
| FV3 | Finite-Volume Cubed Sphere |
+----------------+---------------------------------------------------+
| GFDL | Geophysical Fluid Dynamics Laboratory |
| GFDL | NOAA Geophysical Fluid Dynamics Laboratory |
+----------------+---------------------------------------------------+
| GFS | Global Forecast System |
+----------------+---------------------------------------------------+
Expand All @@ -51,26 +49,16 @@ Acronyms
+----------------+---------------------------------------------------+
| NCEP | National Centers for Environmental Predicction |
+----------------+---------------------------------------------------+
| NEMS | National Oceanic and Atmospheric Administration |
| | (NOAA) Environmental Modeling System |
| NEMS | NOAA Environmental Modeling System |
+----------------+---------------------------------------------------+
| NOAA | National Oceanic and Atmospheric Administration |
+----------------+---------------------------------------------------+
| NSSL | National Severe Storms Laboratory |
+----------------+---------------------------------------------------+
| OpenMP | Open Multi-Processing |
+----------------+---------------------------------------------------+
| PBL | Planetary Boundary Layer |
+----------------+---------------------------------------------------+
| png | Portable Network Graphic |
+----------------+---------------------------------------------------+
| PR | Pull request |
+----------------+---------------------------------------------------+
| PROD | Compiler optimization flags for production mode |
+----------------+---------------------------------------------------+
| REPRO | Compiler optimization flags for reproduction mode |
| | (bit-for-bit testing) |
+----------------+---------------------------------------------------+
| RRTMG | Rapid Radiative Transfer Model for Global |
| | Circulation Models |
+----------------+---------------------------------------------------+
Expand All @@ -92,7 +80,5 @@ Acronyms
+----------------+---------------------------------------------------+
| UFS | Unified Forecast System |
+----------------+---------------------------------------------------+
| VLab | Virtual Laboratory |
+----------------+---------------------------------------------------+
| WM | Weather Model |
+----------------+---------------------------------------------------+
25 changes: 12 additions & 13 deletions doc/UsersGuide/source/BuildingAndRunning.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
.. _BuildingAndRunning:

******************************************
Building and Running the UFS Weather Model
******************************************
Expand All @@ -15,8 +15,8 @@ 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
<https://github.com/NOAA-EMC/NCEPLIBS>`_. Be sure to look at the tag in that repository that
matches the tag on this WM release.
<https://github.com/NOAA-EMC/NCEPLIBS>`_ (**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
Expand All @@ -42,7 +42,7 @@ 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
<https://github.com/NOAA-EMC/NCEPLIBS-external>`_, and at the top level of the `NCEPLIBS repository
<https://github.com/NOAA-EMC/NCEPLIBS-external>`_, and at the top level of the `NCEPLIBS repository
<https://github.com/NOAA-EMC/NCEPLIBS>`_. 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.

Expand All @@ -62,7 +62,7 @@ You will need to make sure that the WM has the paths to the libraries that it re
that, these environment variables need to be set, as shown in :numref:`Table %s <ReqLibEnvVar>` and
:numref:`Table %s <ReqLibEnvVar2>` for the bash shell.

.. _ReqLibEnvVar:
.. _ReqLibEnvVar:

.. table:: *Bundled libraries (NCEPLIBS) required for the Weather Model*

Expand All @@ -84,7 +84,7 @@ that, these environment variables need to be set, as shown in :numref:`Table %s

|

.. _ReqLibEnvVar2:
.. _ReqLibEnvVar2:

.. table:: *Third-party libraries (NCEPLIBS-external) required for the Weather Model*

Expand All @@ -110,26 +110,26 @@ load the modules, for example on hera, run:
cd ../..

If you are not running on one of the pre-configured platforms, you will need to set the environment variables
in a different way.
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
``setenv_nceplibs.sh`` that will set the NCEPLIBS-external variables for you.
``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.

-----------------------------------
Setting other environment variables
-----------------------------------
You will also need to set the ``CMAKE_Platform`` environment variable.
See the ``README`` files in the ``doc/`` directories of the NCEPLIBS-external repository for recognized values.
See the ``README`` files in the ``doc/`` directories of the NCEPLIBS-external repository for recognized values.

The default value is:

.. code-block:: console

export CMAKE_Platform=linux.<compiler>

Where <compiler> is either Intel or GNU. You may also wish to set the following environment variables:

* ``CMAKE_Platform``: if not set the default is linux.${COMPILER}
Expand All @@ -151,7 +151,7 @@ If ``CCPP_SUITES`` is not set, the default is ``‘FV3_GFS_v15p2’``.
Building the model
------------------
The UFS Weather Model uses the cmake build system. There is a build script called ``build.sh`` in the
top-level directory of the WM repository that ensures all necessary variables are actually set.
top-level directory of the WM repository that ensures all necessary variables are actually set.

After setting all the environment variables, you can build the model using

Expand All @@ -168,5 +168,4 @@ set up specifically for issues related to the Weather Model.
Running the model
=================
The `UFS Weather Model wiki <https://github.com/ufs-community/ufs-weather-model/wiki>`_ includes a simple
test case that illustrates how the model can be run.

test case that illustrates how the model can be run.
6 changes: 3 additions & 3 deletions doc/UsersGuide/source/ContributingDevelopment.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
.. _ContributingDevelopment:

*************************
Contributing Development
*************************
Expand All @@ -20,7 +20,7 @@ If developers would like to get their code committed back to the original reposi

* 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/Weather-Model-Platform-and-Compiler-Support. 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.
* 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.

Expand Down Expand Up @@ -85,7 +85,7 @@ rt.sh is a bash shell file to run the RT and has the following options:
% 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/Weather-Model-Platform-and-Compiler-Support). For information on testing the CCPP code, or using alternate computational platforms, see the following sections.
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.

Expand Down
12 changes: 0 additions & 12 deletions doc/UsersGuide/source/FAQforModelConfiguration.rst
View file
Open in desktop

This file was deleted.

15 changes: 2 additions & 13 deletions doc/UsersGuide/source/Glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ Glossary
Model agnostic, vetted, collection of codes containing atmospheric physical parameterizations
and suites for use in NWP along with a framework that connects the physics to host models

*CCPP-Framework*
CCPP-Framework
The infrastructure that connects physics schemes with a host model; also refers to a software
repository of the same name

*CCPP-Physics*
CCPP-Physics
The pool of CCPP-compliant physics schemes; also refers to a software repository of the same name

FMS
Expand All @@ -38,17 +38,6 @@ Glossary
oversimplified parameters, rather than realistically requiring such effects to be
consequences of the dynamics of the system (AMS Glossary)

Physics *cap*
Autogenerated interface between an individual physics scheme and the host model. Used
only in the dynamic CCPP build

PROD
Compiler flags used by NCEP for operational runs of the UFS Atmosphere and by EMC for
regression tests of the code

REPRO
Compiler flags used by EMC to guarantee reproducibility of the UFS Atmosphere code

Suite Definition File (SDF)
An external file containing information about the
construction of a physics suite. It describes the schemes that are called, in which
Expand Down
Loading