-
Notifications
You must be signed in to change notification settings - Fork 243
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
ufs_public_release: merge documentation branch, add guard for DEBUG/R…
…EPRO flags (#42) * Initial commit for a UFS Weather Model devloper's Guide in rst format for use with Sphinx * Remove references to chapters not available in this Developer's Guide. This is a test commit to test the webhook to readthedocs. The HTML in https://ufs-weather-model.readthedocs.io should update automatically * Add Users Guide subsuming Developers Guide * Added initial files for all chapters of the Users Guide * - Update Glossary.rst - Add Acronyms.rst - Remove PlatformSupport.rst; this will be included with the app. - Update conf.py to correct name of document for latex build. - Remove TransitioningFromVLAB.rst, GitGitHub.rst and Template.rst. Both html and latex builds succeed. * - Add more acronyms to Acronyms.rst - Add reference to top of Glossary.rst for linking - Add rst version of Introduction.rst from Google Docs * - Change project name in conf.py to "UFS Weather Model Users Guide" - Add chapter InputsOutputs.rst - Add chapter SDFandNamelistExamplePractices.rst Both html and latex builds succeed. Table format looks good in pdf file. * - added Code Overview chapter to UsersGuide - html and latexpdf builds were successful * - added Compiling the Code Without an Application to UsersGuide - html and latexpdf builds were successful * Update CompilingCodeWithoutApp.rst * Update Introduction.rst * Remove placeholder chapter for Regression Tests. Add content to chapter for Contributing Development explaining that it is under development. At this time, the chapter on Contributing Development contains information abojut RTs but those can be separated later. * Improve directory description. Change URL for FMS authoritative repository. * Add guard to tests/compile_cmake.sh to prevent using DEBUG=Y and REPRO=Y at the same time * User guide update (includes #32) (#40) Co-authored-by: ligiabernardet <[email protected]> Co-authored-by: JulieSchramm <[email protected]>
- Loading branch information
1 parent
2487a7b
commit 81cc69b
Showing
22 changed files
with
2,250 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= | ||
SPHINXBUILD ?= sphinx-build | ||
SOURCEDIR = source | ||
BUILDDIR = build | ||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help Makefile | ||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
This directory contains the Developer's Guide for the UFS Medium-Range Weather Application. | ||
|
||
To build in html format (from this directory, above source and build) type: | ||
|
||
`make html` | ||
|
||
This will create an `index.html` file in `./build/html`. | ||
|
||
To view in a browser window: | ||
|
||
`open build/html/index.html` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Ignore everything in this directory | ||
* | ||
# Except this file | ||
!.gitignore |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
@ECHO OFF | ||
|
||
pushd %~dp0 | ||
|
||
REM Command file for Sphinx documentation | ||
|
||
if "%SPHINXBUILD%" == "" ( | ||
set SPHINXBUILD=sphinx-build | ||
) | ||
set SOURCEDIR=source | ||
set BUILDDIR=build | ||
|
||
if "%1" == "" goto help | ||
|
||
%SPHINXBUILD% >NUL 2>NUL | ||
if errorlevel 9009 ( | ||
echo. | ||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx | ||
echo.installed, then set the SPHINXBUILD environment variable to point | ||
echo.to the full path of the 'sphinx-build' executable. Alternatively you | ||
echo.may add the Sphinx directory to PATH. | ||
echo. | ||
echo.If you don't have Sphinx installed, grab it from | ||
echo.http://sphinx-doc.org/ | ||
exit /b 1 | ||
) | ||
|
||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
goto end | ||
|
||
:help | ||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
|
||
:end | ||
popd |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
sphinxcontrib-bibtex |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,98 @@ | ||
.. _Acronyms: | ||
|
||
************************* | ||
Acronyms | ||
************************* | ||
|
||
.. table:: | ||
:widths: 20 80 | ||
|
||
+----------------+---------------------------------------------------+ | ||
| Abbreviation | Explanation | | ||
+================+===================================================+ | ||
| AOML | NOAA's Atlantic Oceanographic and Meteorological | | ||
| | Laboratory | | ||
+----------------+---------------------------------------------------+ | ||
| API | Application Programming Interface | | ||
+----------------+---------------------------------------------------+ | ||
| b4b | Bit-for-bit | | ||
+----------------+---------------------------------------------------+ | ||
| CCPP | Common Community Physics Package | | ||
+----------------+---------------------------------------------------+ | ||
| CPP | C preprocessor | | ||
+----------------+---------------------------------------------------+ | ||
| dycore | Dynamical core | | ||
+----------------+---------------------------------------------------+ | ||
| EDMF | Eddy-Diffusivity Mass Flux | | ||
+----------------+---------------------------------------------------+ | ||
| EMC | Environmental Modeling Center | | ||
+----------------+---------------------------------------------------+ | ||
| ESMF | The Earth System Modeling Framework | | ||
+----------------+---------------------------------------------------+ | ||
| ESRL | NOAA Earth System Research Laboratory | | ||
+----------------+---------------------------------------------------+ | ||
| FMS | Flexible Modeling System | | ||
+----------------+---------------------------------------------------+ | ||
| FV3 | Finite-Volume Cubed Sphere | | ||
+----------------+---------------------------------------------------+ | ||
| GFDL | Geophysical Fluid Dynamics Laboratory | | ||
+----------------+---------------------------------------------------+ | ||
| GFS | Global Forecast System | | ||
+----------------+---------------------------------------------------+ | ||
| GSD | Global Systems Division | | ||
+----------------+---------------------------------------------------+ | ||
| HTML | Hypertext Markup Language | | ||
+----------------+---------------------------------------------------+ | ||
| LSM | Land Surface Model | | ||
+----------------+---------------------------------------------------+ | ||
| MPI | Message Passing Interface | | ||
+----------------+---------------------------------------------------+ | ||
| NCAR | National Center for Atmospheric Research | | ||
+----------------+---------------------------------------------------+ | ||
| NCEP | National Centers for Environmental Predicction | | ||
+----------------+---------------------------------------------------+ | ||
| NEMS | National Oceanic and Atmospheric Administration | | ||
| | (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 | | ||
+----------------+---------------------------------------------------+ | ||
| RT | Regression test | | ||
+----------------+---------------------------------------------------+ | ||
| SAS | Simplified Arakawa-Schubert | | ||
+----------------+---------------------------------------------------+ | ||
| SDF | Suite Definition File | | ||
+----------------+---------------------------------------------------+ | ||
| sfc | Surface | | ||
+----------------+---------------------------------------------------+ | ||
| SHUM | Perturbed boundary layer specific humidity | | ||
+----------------+---------------------------------------------------+ | ||
| SKEB | Stochastic Kinetic Energy Backscatter | | ||
+----------------+---------------------------------------------------+ | ||
| SPPT | Stochastically Perturbed Physics Tendencies | | ||
+----------------+---------------------------------------------------+ | ||
| TKE | Turbulent Kinetic Energy | | ||
+----------------+---------------------------------------------------+ | ||
| UFS | Unified Forecast System | | ||
+----------------+---------------------------------------------------+ | ||
| VLab | Virtual Laboratory | | ||
+----------------+---------------------------------------------------+ | ||
| WM | Weather Model | | ||
+----------------+---------------------------------------------------+ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
.. _CodeOverview: | ||
|
||
************************* | ||
Code Overview | ||
************************* | ||
|
||
=================================================== | ||
UFS Weather Model Hierarchical Repository Structure | ||
=================================================== | ||
|
||
The ufs-weather-model repository supports the short- and medium-range UFS applications. It contains atmosphere and wave components and some infrastructure components. Each of these components has its own repository. All the repositories are currently located in GitHub with public access to the broad community. :numref:`Table %s <Repo_Structure>` describes the list of repositories that comprises the ufs-weather-model. | ||
|
||
.. _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 | ||
* - Infrastructure: Flexible Modeling System | ||
- https://github.com/NOAA-GFDL/FMS | ||
* - Infrastructure: NOAA Environmental Modeling System | ||
- https://github.com/NOAA-EMC/NEMS | ||
* - Infrastructure: add description | ||
- https://github.com/NOAA-EMC/NCEPLIBS-pyprodutil | ||
* - Framework to connect the CCPP library to a host model | ||
- https://github.com/NCAR/ccpp-framework | ||
* - CCPP library of physical parameterizations | ||
- https://github.com/NCAR/ccpp-physics | ||
* - Umbrella repository for the physics and dynamics of the atmospheric model | ||
- https://github.com/NOAA-EMC/fv3atm | ||
* - FV3 dynamical core | ||
- https://github.com/NOAA-EMC/GFDL_atmos_cubed_sphere | ||
* - Stochastic physics pattern generator | ||
- https://github.com/noaa-psd/stochastic_physics | ||
* - WAVEWATCH 3 wave model | ||
- https://github.com/NOAA-EMC/WW3 | ||
|
||
In the table, the left column contains a description of each repository, and the right column shows the component repositories which are pointing to (or will point to) the authoritative repositories. The ufs-weather-model currently uses git submodule to manage the sub-components. | ||
|
||
The umbrella repository for the UFS Weather Model is named ufs-weather-model. Under this repository reside a number of submodules that are nested in specific directories under the parent repository’s working directory. When the ufs-weather-model repository is cloned, the *.gitmodules* file creates the following directories: | ||
|
||
.. code-block:: console | ||
ufs-weather-model/ | ||
├── FMS https://github.com/NOAA-GFDL/FMS | ||
├── FV3 https://github.com/NCAR/fv3atm | ||
│ ├── atmos_cubed_sphere https://github.com/NCAR/GFDL_atmos_cubed_sphere | ||
│ ├── ccpp | ||
│ │ ├── framework https://github.com/NCAR/ccpp-framework | ||
│ │ ├── physics https://github.com/NCAR/ccpp-physics | ||
├── NEMS https://github.com/NCAR/NEMS | ||
│ └── tests/produtil/NCEPLIBS-pyprodutil https://github.com/NOAA-EMC/NCEPLIBS-pyprodutil | ||
├── stochastic_physics https://github.com/noaa-psd/stochastic_physics | ||
└── WW3 https://github.com/NOAA-EMC/WW3 | ||
=================== | ||
Directory Structure | ||
=================== | ||
|
||
When the ufs-weather-model is cloned, the basic directory structure will be similar to the example below. Files and some directories have been removed for brevity. | ||
|
||
.. code-block:: console | ||
ufs-weather-model/ | ||
├── cmake --------- cmake configuration files | ||
├── compsets --------- configurations used by some regression tests | ||
├── conf --------- compile options for Tier 1 and 2 platforms | ||
├── doc --------- READMEs with build, reg-test hints | ||
├── FMS --------- The Flexible Modeling System (FMS),a software framework | ||
├── FV3 --------- FV3 atmosphere model | ||
│ ├── atmos_cubed_sphere ---- FV3 dynamic core | ||
│ │ ├── 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 | ||
│ ├── gfsphysics | ||
│ │ ├── CCPP_layer | ||
│ │ ├── GFS_layer | ||
│ │ └── physics --------- unused - IPD version of physics codes | ||
│ ├── io --------- FV3 write grid comp code | ||
│ ├── ipd --------- unused - IPD driver/interfaces | ||
├── log --------- log files from NEMS compset regression tests | ||
├── modulefile --------- system module files for supported HPC systems | ||
├── NEMS --------- NOAA Earth Modeling System framework | ||
│ ├── exe | ||
│ ├── src | ||
│ └── test | ||
├── parm --------- regression test configurations | ||
├── release --------- unused | ||
├── stochastic_physics -------- stochastic physics pattern generator | ||
├── tests --------- regression test scripts | ||
└── WW3 --------- WAVEWATCH III (wave component) | ||
The physics subdirectory in the *gfsphysics* directory is not used or supported as part of this release (all physics is available through the :term:`CCPP`). | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,92 @@ | ||
.. _CompilingCodeWithoutApp: | ||
|
||
***************************************** | ||
Compiling the Code without an Application | ||
***************************************** | ||
|
||
UFS weather model uses the cmake build system. Since UFS weather model requires several external libraries to be available and appropriate environment variables pointing to those libraries to be set, a build script named ``build.sh`` is provided In the top-level directory of the repository to ensure all necessary variables are actually set. | ||
|
||
The required libraries and environment variables can be set as shown in :numref:`Table %s <ReqLibEnvVar>` and :numref:`Table %s <ReqLibEnvVar2>` for the bash shell. | ||
|
||
1. NCEP libraries: | ||
|
||
.. _ReqLibEnvVar: | ||
|
||
.. list-table:: *List of NCEP libraries that comprise the ufs-weather-model* | ||
:widths: 20 80 | ||
:header-rows: 1 | ||
|
||
* - NCEP Library | ||
- Environment Variables | ||
* - nemsio | ||
- export NEMSIO_INC=<path_to_nemsio_include_dir> | ||
* - | ||
- export NEMSIO_LIB=<path_to_nemsio_lib_dir>/libnemsio.a | ||
* - bacio | ||
- export BACIO_LIB4=<path_to_bacio_lib_dir>/libbacio.a | ||
* - splib | ||
- export SP_LIBd=<path_to_sp_lib_dir>/libsp_d.a | ||
* - w3emc | ||
- export W3EMC_LIBd=<path_to_w3emc_lib_dir>/libw3emc_d.a | ||
* - w3nco | ||
- export W3NCO_LIBd=<path_to_w3nco_lib_dir>/libw3nco_d.a | ||
|
||
2. Third party libraries: | ||
|
||
.. _ReqLibEnvVar2: | ||
|
||
.. list-table:: *List of External libraries that comprise the ufs-weather-model* | ||
:widths: 20 80 | ||
:header-rows: 1 | ||
|
||
* - Third Party Library | ||
- Environment Variables | ||
* - NetCDF | ||
- export NETCDF=<path_to_netcdf_install_dir> | ||
* - ESMF | ||
- export ESMFMKFILE=<path_to_esmfmk_file>/esmf.mk | ||
|
||
You can either manually set those environment variables in your shell, or if you are on one of the supported platforms (Tier 1) the easiest way of setting those variables is by using environment module and load all required modules. Modulefiles for all supported platforms are located in ``modulefiles/<platform>/fv3``. To load those modules, for example on hera, run: | ||
|
||
.. code-block:: console | ||
$ cd modulefiles/hera.intel | ||
$ module use $(pwd) | ||
$ module load fv3 | ||
$ cd ../.. | ||
Currently the build system supports two compiler families: GNU and Intel. The COMPILE environment variable must be set to either ‘gnu’ or ‘intel’ before running build script. For example, to use Intel compilers when using the bash shell, run: | ||
|
||
.. code-block:: console | ||
$ export COMPILER=intel | ||
You can further customize compiler MPI wrappers by setting these four environment variables: | ||
|
||
.. code-block:: console | ||
CMAKE_Platform : if not set the default is linux.${COMPILER} | ||
CMAKE_C_COMPILER : if not set the default is mpicc | ||
CMAKE_CXX_COMPILER : if not set the default is mpicxx | ||
CMAKE_Fortran_COMPILER : if not set the default is mpif90 | ||
In order to have one or more CCPP physics suites available at runtime, you need to select those suites at build time by setting the ``CCPP_SUITES`` environment variable. Multiple suites can be set, as shown below in an example for the bash shell | ||
|
||
.. code-block:: console | ||
$ export CCPP_SUITES=’FV3_GFS_v15p2,FV3_GFS_v16beta’ | ||
If ``CCPP_SUITES`` is not set, the default is ``‘FV3_GFS_v15p2’``. | ||
|
||
After setting all the environment variables, you can build the model using | ||
|
||
.. code-block:: console | ||
$ ./build.sh | ||
Once ``build.sh`` is finished, you should see the executable, named ufs_weather_model, in the top-level directory. | ||
|
||
|
||
|
||
|
||
|
Oops, something went wrong.