Skip to content

SRW App Users' Guide (close-to-final): corrections and notes (not meant to be merged, but to be picked up by the documentation team) #126

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

Closed
climbfuji wants to merge 1 commit into from
Closed

SRW App Users' Guide (close-to-final): corrections and notes (not meant to be merged, but to be picked up by the documentation team) #126

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions docs/UsersGuide/source/CodeReposAndDirs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,8 @@ contents of these sub-directories are described in :numref:`Table %s <Subdirecto

.. _Subdirectories:

NOTE DOM 20220227 do we expect the users to know what j-job scripts / j-jobs are?

.. table:: Sub-directories of the regional workflow.

+-------------------------+---------------------------------------------------------+
Expand Down Expand Up @@ -145,6 +147,8 @@ When the ``generate_FV3LAM_wflow.sh`` script is run, the user-defined experiment
is specified in the ``config.sh`` file. The contents of the ``EXPTDIR`` directory, before the
workflow is run, is shown in :numref:`Table %s <ExptDirStructure>`.

NOTE DOM 20220227 better to say "Tracers" instead of "Scalar fields in the table below", to be consistent with section 5.7 (also makes more sense)

.. _ExptDirStructure:

.. table:: Files and sub-directory initially created in the experimental directory.
Expand Down
32 changes: 18 additions & 14 deletions docs/UsersGuide/source/ConfigNewPlatform.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ The first step to installing on a new machine is to install :term:`NCEPLIBS` (ht

* C and C++ compilers compatible with the Fortran compiler

* gcc v9+, ifort v18+, and clang (MacOS) have been tested
* gcc v9+, ifort v18+, and clang v9+ (macOS, native Apple clang or LLVM clang) have been tested

* Python v3.6+

* Prerequisite packages must be downloaded: jinja2, yaml and f90nml, as well as pygrib if the user would like to use the provided graphics scripts
* Prerequisite packages must be downloaded: jinja2, yaml and f90nml, as well as a number of additional Python modules (see :numref:`Section %s <SW-OS-Requirements>` if the user would like to use the provided graphics scripts

* Perl 5

Expand All @@ -28,16 +28,20 @@ The first step to installing on a new machine is to install :term:`NCEPLIBS` (ht

* CMake v3.15+ is needed for building NCEPLIBS, but versions as old as 3.12 can be used to build NCEPLIBS-external, which contains a newer CMake that can be used for the rest of the build.

For Linux systems, as long as the above software is available, you can move on to the next step: installing the :term:`NCEPLIBS-external` package.

For MacOS systems, you will also need to set the stack size to “unlimited”.
For both Linux and macOS, you will need to set the stack size to "unlimited" (if allowed) or the largest possible value

.. code-block:: console

# Linux, if allowed
ulimit -s unlimited

# macOS, this corresponds to 65MB
ulimit -S -s unlimited

Additionally, some extra software is needed: ``wget``, ``coreutils``, ``pkg-config``, and ``gnu-sed``.
It is recommended that you install this software using the Homebrew package manager for MacOS (https://brew.sh/):
For Linux systems, as long as the above software is available, you can move on to the next step: installing the :term:`NCEPLIBS-external` package.

For macOS systems, some extra software is needed: ``wget``, ``coreutils``, ``pkg-config``, and ``gnu-sed``.
It is recommended that you install this software using the Homebrew package manager for macOS (https://brew.sh/):

* brew install wget

Expand Down Expand Up @@ -160,7 +164,7 @@ At this point there are just a few more variables that need to be set prior to b
export CMAKE_CXX_COMPILER=mpicxx
export CMAKE_Fortran_COMPILER=mpifort

If you are using your machine’s built-in MPI compilers, it is recommended you set the ``CMAKE_*_COMPILER`` flags to full paths to ensure that the correct MPI aliases are used. Finally, one last environment variable, ``CMAKE_Platform``, must be set. This will depend on your machine; for example, on a MacOS operating system with GNU compilers:
If you are using your machine’s built-in MPI compilers, it is recommended you set the ``CMAKE_*_COMPILER`` flags to full paths to ensure that the correct MPI aliases are used. Finally, one last environment variable, ``CMAKE_Platform``, must be set. This will depend on your machine; for example, on a macOS operating system with GNU compilers:

.. code-block:: console

Expand Down Expand Up @@ -198,7 +202,7 @@ Running the graphics scripts in ``${WORKDIR}/ufs-srweather-app/regional_workflow

For the final step of creating and running an experiment, the exact methods will depend on if you are running with or without a workflow manager (Rocoto).

Running Without a Workflow Manager: Generic Linux and MacOS Platforms
Running Without a Workflow Manager: Generic Linux and macOS Platforms
=====================================================================
Now that the code has been built, you can stage your data as described in :numref:`Section %s <DownloadingStagingInput>`.

Expand Down Expand Up @@ -244,7 +248,7 @@ From here, you can run each individual task of the UFS SRW App using the provide
cp ${WORKDIR}/ufs-srweather-app/regional_workflow/ush/wrappers/*sh .
cp ${WORKDIR}/ufs-srweather-app/regional_workflow/ush/wrappers/README.md .

The ``README.md`` file will contain instructions on the order that each script should be run in. An example of wallclock times for each task for an example run (2017 Macbook Pro, MacOS Catalina, 25km CONUS domain, 48hr forecast) is listed in :numref:`Table %s <WallClockTimes>`.
The ``README.md`` file will contain instructions on the order that each script should be run in. An example of wallclock times for each task for an example run (2017 Macbook Pro, macOS Catalina, 25km CONUS domain, 48hr forecast) is listed in :numref:`Table %s <WallClockTimes>`.

.. _WallClockTimes:

Expand Down Expand Up @@ -341,7 +345,7 @@ Those requirements highlighted in **bold** are included in the NCEPLIBS-external

* 4GB memory (CONUS 25km domain)

* Fortran compiler with full Fortran 2003 standard support
* Fortran compiler with full Fortran 2008 standard support

* C and C++ compiler

Expand All @@ -361,13 +365,13 @@ Those requirements highlighted in **bold** are included in the NCEPLIBS-external

* **netCDF (C and Fortran libraries)**
* **HDF5**
* **ESMF**
* **ESMF** 8.0.0
* **Jasper**
* **libJPG**
* **libPNG**
* **zlib**

MacOS-specific prerequisites:
macOS-specific prerequisites:

* brew install wget
* brew install cmake
Expand All @@ -381,4 +385,4 @@ Optional but recommended prerequisites:
* Bash v4+
* Rocoto Workflow Management System (1.3.1)
* **CMake v3.15+**
* Python package pygrib for graphics
* Python packages scipy, matplotlib, pygrib, cartopy, and pillow for graphics
16 changes: 8 additions & 8 deletions docs/UsersGuide/source/ConfigParameters.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Grid Generation Parameters
==========================
``GRID_GEN_METHOD``: (Default: “”)
This variable specifies the method to use to generate a regional grid in the horizontal. The only supported value of this parameter is “ESGgrid”, in which case the Extended Schmidt Gnomonic grid generation method developed by Jim Purser of EMC will be used.
This variable specifies the method to use to generate a regional grid in the horizontal. The only supported value of this parameter is “ESGgrid”, in which case the Extended Schmidt Gnomonic grid generation method developed by Jim Purser of EMC will be used. NOTE DOM 20220227 insert proper reference here or remove "developed by ..."

.. note::

Expand Down Expand Up @@ -49,11 +49,11 @@ Computational Forecast Parameters
``BLOCKSIZE``: (Default: “”)
The amount of data that is passed into the cache at a time.

Here, we set these parameters to null strings. This is so that, for any one of these parameters:
Here, we set these parameters to null strings. This is so that, for any one of these parameters:

#. If the experiment is using a predefined grid, then if the user sets the parameter in the user-specified experiment configuration file (``EXPT_CONFIG_FN``), that value will be used in the forecast(s). Otherwise, the default value of the parameter for that predefined grid will be used.
#. If the experiment is using a predefined grid and the user sets the parameter in the user-specified experiment configuration file (``EXPT_CONFIG_FN``), that value will be used in the forecast(s). Otherwise, the default value of the parameter for that predefined grid will be used.

#. If the experiment is not using a predefined grid (i.e. it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the parameter in that configuration file. Otherwise, the parameter will remain set to a null string, and the experiment generation will fail because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory.
#. If the experiment is not using a predefined grid (i.e. it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the parameter in that configuration file. Otherwise, the parameter will remain set to a null string, and the experiment generation will fail, because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory.

Write-Component (Quilting) Parameters
=====================================
Expand Down Expand Up @@ -91,7 +91,7 @@ Currently supported ``PREDEF_GRID_NAME`` options are "RRFS_CONUS_25km," "RRFS_CO
Pre-existing Directory Parameter
================================
``PREEXISTING_DIR_METHOD``: (Default: “delete”)
This variable determines the method to use to deal with pre-existing directories [e.g ones generated by previous calls to the experiment generation script using the same experiment name (``EXPT_SUBDIR``) as the current experiment]. This variable must be set to one of "delete", "rename", and "quit". The resulting behavior for each of these values is as follows:
This variable determines the method to deal with pre-existing directories [e.g ones generated by previous calls to the experiment generation script using the same experiment name (``EXPT_SUBDIR``) as the current experiment]. This variable must be set to one of "delete", "rename", and "quit". The resulting behavior for each of these values is as follows:

* "delete": The preexisting directory is deleted and a new directory (having the same name as the original preexisting directory) is created.

Expand Down Expand Up @@ -128,12 +128,12 @@ These parameters set flags (and related directories) that determine whether the

Surface Climatology Parameter
=============================
``SFC_CLIMO_FIELDS``: (Default: “("facsf" "maximum_snow_albedo" "slope_type" "snowfree_albedo" "soil_type" "substrate_temperature" "vegetation_greenness" "vegetation_type")”
``SFC_CLIMO_FIELDS``: (Default: “("facsf" "maximum_snow_albedo" "slope_type" "snowfree_albedo" "soil_type" "substrate_temperature" "vegetation_greenness" "vegetation_type")”)
Array containing the names of all the fields for which the ``MAKE_SFC_CLIMO_TN`` task generates files on the native FV3-LAM grid.

Fixed File Parameters
=====================
Set parameters associated with the fixed (i.e. static) files. For the main NOAA HPC platforms, as well as Cheyenne, Odin, and Stampede, fixed files are prestaged in locations on each machine with paths defined in the ``setup.sh`` script.
Set parameters associated with the fixed (i.e. static) files. For the main NOAA HPC platforms, as well as Cheyenne, Odin, and Stampede, fixed files are prestaged with paths defined in the ``setup.sh`` script.

``FIXgsm``: (Default: “”)
System directory in which the majority of fixed (i.e. time-independent) files that are needed to run the FV3-LAM model are located.
Expand Down Expand Up @@ -221,7 +221,7 @@ Set parameters associated with the fixed (i.e. static) files. For the main NOAA
``CYCLEDIR_LINKS_TO_FIXam_FILES_MAPPING``: (Default: see below)
.. code-block:: console

("aerosol.dat | global_climaeropac_global.txt" \
("aerosol.dat | global_climaeropac_global.txt" \
"co2historicaldata_2010.txt | fix_co2_proj/global_co2historicaldata_2010.txt" \
"co2historicaldata_2011.txt | fix_co2_proj/global_co2historicaldata_2011.txt" \
"co2historicaldata_2012.txt | fix_co2_proj/global_co2historicaldata_2012.txt" \
Expand Down
Loading