diff --git a/.gitmodules b/.gitmodules index ca914133d5..e69de29bb2 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +0,0 @@ -[submodule "hpc-stack-mod"] - path = hpc-stack-mod - url = https://github.com/NOAA-EMC/hpc-stack.git diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index fbe1cf910d..bafb4ead29 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -35,7 +35,7 @@ The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Supported model resolutions in this release include 3-, 13-, and 25-km predefined contiguous U.S. (:term:`CONUS`) domains, each with 127 vertical levels. Preliminary tools for users to define their own domain are also available in the release with full, formal support of these tools to be provided in future releases. The Extended Schmidt Gnomonic (ESG) grid is used with the FV3-LAM, which features relatively uniform grid cells across the entirety of the domain. Additional information about the FV3 dynamical core can be found in the `scientific documentation `__, the `technical documentation `__, and on the `NOAA Geophysical Fluid Dynamics Laboratory website `__. -Interoperable atmospheric physics, along with various land surface model options, are supported through the Common Community Physics Package (CCPP), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There will be four physics suites supported for the SRW App v2.0.0 release. The first is the FV3_RRFS_v1beta physics suite, which is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (RRFS) planned for 2023-2024, and the second is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. Additionally, FV3_WoFS_v0 and FV3_HRRR will be supported. A scientific description of the CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. +Interoperable atmospheric physics, along with various land surface model options, are supported through the Common Community Physics Package (CCPP), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There will be four physics suites supported for the SRW App v2.0.0 release. The first is the FV3_RRFS_v1beta physics suite, which is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (RRFS) planned for 2023-2024, and the second is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. Additionally, FV3_WoFS_v0 and FV3_HRRR will be supported. A scientific description of the CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. .. note:: SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which physics suite definition file (:term:`SDF`) is chosen when turning this option on. Among the supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. @@ -79,7 +79,7 @@ Build System and Workflow The SRW Application has a portable build system and a user-friendly, modular, and expandable workflow framework. -An umbrella CMake-based build system is used for building the components necessary for running the end-to-end SRW Application, including the UFS Weather Model and the pre- and post-processing software. Additional libraries necessary for the application (e.g., :term:`NCEPLIBS-external` and :term:`NCEPLIBS`) are not included in the SRW Application build system but are available pre-built on pre-configured platforms. On other systems, they can be installed via the HPC-Stack (see :numref:`Chapter %s: Installing the HPC-Stack `). There is a small set of system libraries and utilities that are assumed to be present on the target computer: the CMake build software, a Fortran, C, and C++ compiler, and an :term:`MPI` library. +An umbrella CMake-based build system is used for building the components necessary for running the end-to-end SRW Application, including the UFS Weather Model and the pre- and post-processing software. Additional libraries necessary for the application (e.g., :term:`NCEPLIBS-external` and :term:`NCEPLIBS`) are not included in the SRW Application build system but are available pre-built on pre-configured platforms. On other systems, they can be installed via the HPC-Stack (see :doc:`HPC-Stack Documentation `). There is a small set of system libraries and utilities that are assumed to be present on the target computer: the CMake build software, a Fortran, C, and C++ compiler, and an :term:`MPI` library. Once built, the provided experiment generator script can be used to create a Rocoto-based workflow file that will run each task in the system in the proper sequence (see :numref:`Chapter %s ` or the `Rocoto documentation `_ for more information on Rocoto). If Rocoto and/or a batch system is not present on the available platform, the individual components can be run in a stand-alone, command line fashion with provided run scripts. The generated namelist for the atmospheric model can be modified in order to vary settings such as forecast starting and ending dates, forecast length hours, the :term:`CCPP` physics suite, integration time step, history file output frequency, and more. It also allows for configuration of other elements of the workflow; for example, users can choose whether to run some or all of the pre-processing, forecast model, and post-processing steps. diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index 04fc0402c4..4eeb57b48c 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -205,7 +205,7 @@ File Name Parameters Name of the file specifying the fields that the forecast model will output. ``FIELD_TABLE_FN``: (Default: "field_table") - Name of the file specifying the :term:`tracers` that the forecast model will read in from the :term:`IC/LBC` files. + Name of the file specifying the :term:`tracers ` that the forecast model will read in from the :term:`IC/LBC ` files. ``DATA_TABLE_FN``: (Default: "data_table") Name of the file containing the data table read in by the forecast model. @@ -413,7 +413,7 @@ CCPP Parameter Stochastic Physics Parameters ================================ -For the most updated and detailed documentation of these parameters, see the `UFS Stochastic Physics Documentation `__. +For the most updated and detailed documentation of these parameters, see the `UFS Stochastic Physics Documentation `__. ``NEW_LSCALE``: (Default: "TRUE") Use correct formula for converting a spatial legnth scale into spectral space. @@ -508,7 +508,7 @@ Stochastic Kinetic Energy Backscatter (SKEB) Parameters Parameters for Stochastically Perturbed Parameterizations (SPP) ------------------------------------------------------------------ -SPP perturbs specific tuning parameters within a physics :term:`parameterization` (unlike :ref:`SPPT `, which multiplies overall physics tendencies by a random perturbation field *after* the call to the physics suite). Each SPP option is an array, applicable (in order) to the :term:`RAP`/:term:`HRRR`-based parameterization listed in ``SPP_VAR_LIST``. Enter each value of the array in ``config.sh`` as shown below without commas or single quotes (e.g., ``SPP_VAR_LIST=( "pbl" "sfc" "mp" "rad" "gwd"`` ). Both commas and single quotes will be added by Jinja when creating the namelist. +SPP perturbs specific tuning parameters within a physics :term:`parameterization ` (unlike :ref:`SPPT `, which multiplies overall physics tendencies by a random perturbation field *after* the call to the physics suite). Each SPP option is an array, applicable (in order) to the :term:`RAP`/:term:`HRRR`-based parameterization listed in ``SPP_VAR_LIST``. Enter each value of the array in ``config.sh`` as shown below without commas or single quotes (e.g., ``SPP_VAR_LIST=( "pbl" "sfc" "mp" "rad" "gwd"`` ). Both commas and single quotes will be added by Jinja when creating the namelist. .. note:: SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which :term:`SDF` is chosen when turning this option on. Among the supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. diff --git a/docs/UsersGuide/source/ContainerQuickstart.rst b/docs/UsersGuide/source/ContainerQuickstart.rst index 1ba7cc0ef7..229db0a6eb 100644 --- a/docs/UsersGuide/source/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/ContainerQuickstart.rst @@ -31,7 +31,7 @@ Install Singularity To build and run the SRW App using a Singularity container, first install the Singularity package according to the `Singularity Installation Guide `__. This will include the installation of dependencies and the installation of the Go programming language. SingularityCE Version 3.7 or above is recommended. .. warning:: - Docker containers can only be run with root privileges, and users cannot have root privileges on :term:`HPCs`. Therefore, it is not possible to build the SRW App, which uses the HPC-Stack, inside a Docker container on an HPC system. However, a Singularity image may be built directly from a Docker image for use on the system. + Docker containers can only be run with root privileges, and users cannot have root privileges on :term:`HPCs `. Therefore, it is not possible to build the SRW App, which uses the HPC-Stack, inside a Docker container on an HPC system. However, a Singularity image may be built directly from a Docker image for use on the system. Working in the Cloud or on HPC Systems ----------------------------------------- diff --git a/docs/UsersGuide/source/ContributorsGuide.rst b/docs/UsersGuide/source/ContributorsGuide.rst index 8a41cbd739..f63bf3d447 100644 --- a/docs/UsersGuide/source/ContributorsGuide.rst +++ b/docs/UsersGuide/source/ContributorsGuide.rst @@ -27,47 +27,49 @@ Scientists from across multiple labs and organizations have volunteered to revie .. table:: - +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ - | **Organization** | **Reviewers** | **Areas of Expertise** | - +==================+================================================+===================================================================================+ + +------------------+------------------------------------------------+---------------------------------------------------------------------------------------------+ + | **Organization** | **Reviewers** | **Areas of Expertise** | + +==================+================================================+=============================================================================================+ | EMC | Chan-Hoo Jeon (@chan-hoo) | Workflow, Operational platform testing (WCOSS/NCO), and Air quality modeling (Online-CMAQ) | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Ben Blake (@BenjaminBlake-NOAA) | Output visualization, Rocoto | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Ratko Vasic (@RatkoVasic-NOAA) | Workflow, NCO requirements, and operational platform testing | - +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ - | EPIC | Mark Potts (@mark-a-potts) | HPC systems | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Jong Kim (@jkbk2004) | UFS Weather Model configuration, forecast sensitivity analysis, data assimilation | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Natalie Perlin (@natalie-perlin) | Generic Linux/Mac installations, hpc-stack/spack-stack | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Gillian Petro (@gspetro-NOAA) | Documentation | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Edward Snyder (@EdwardSnyder-NOAA) | WE2E testing, input data | - +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ - | GLERL | David Wright (@dmwright526) | FVCOM integration, output visualization, preprocessing tasks | - +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ - | GSL | Jeff Beck (@JeffBeck-NOAA) | SRW App configuration/workflow, code management, meteorological evaluation | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Gerard Ketefian (@gsketefian) | ``regional_workflow`` scripts, jinja templates, and verification tasks | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Linlin Pan (@panll) | Workflow, CCPP/physics, verification | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Christina Holt (@christinaholtNOAA) | Workflow, conda environment support, testing, and code management | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Christopher Harrop (@christopherwharrop-noaa) | Rocoto, code management, and testing | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Daniel Abdi (@danielabdi-noaa) | Workflow generation, testing RRFS on the cloud, environment modules | - +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ - | NCAR | Mike Kavulich (@mkavulich) | CCPP/physics | - | +------------------------------------------------+-----------------------------------------------------------------------------------+ - | | Will Mayfield (@willmayfield) | Verification/METplus tasks, regional_workflow (esp. on Cheyenne) | - +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ - | NSSL | Yunheng Wang (@ywangwof) | HPC systems, code management and regional workflow especially on Stampede, Jet | - | | | and NSSL computers | - +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ - + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Ben Blake (@BenjaminBlake-NOAA) | Output visualization, Rocoto | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Ratko Vasic (@RatkoVasic-NOAA) | Workflow, NCO requirements, and operational platform testing | + +------------------+------------------------------------------------+---------------------------------------------------------------------------------------------+ + | EPIC | Mark Potts (@mark-a-potts) | HPC systems | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Jong Kim (@jkbk2004) | UFS Weather Model configuration, forecast sensitivity analysis, data assimilation | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Michael Lueken (@MichaelLueken) | SRW App code management | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Natalie Perlin (@natalie-perlin) | Generic Linux/Mac installations, hpc-stack/spack-stack | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Gillian Petro (@gspetro-NOAA) | Documentation | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Edward Snyder (@EdwardSnyder-NOAA) | WE2E testing, input data | + +------------------+------------------------------------------------+---------------------------------------------------------------------------------------------+ + | GLERL | David Wright (@dmwright526) | FVCOM integration, output visualization, preprocessing tasks | + +------------------+------------------------------------------------+---------------------------------------------------------------------------------------------+ + | GSL | Jeff Beck (@JeffBeck-NOAA) | SRW App configuration/workflow, code management, meteorological evaluation | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Gerard Ketefian (@gsketefian) | ``regional_workflow`` scripts, jinja templates, and verification tasks | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Linlin Pan (@panll) | Workflow, CCPP/physics, verification | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Christina Holt (@christinaholtNOAA) | Workflow, conda environment support, testing, and code management | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Christopher Harrop (@christopherwharrop-noaa) | Rocoto, code management, and testing | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Daniel Abdi (@danielabdi-noaa) | Workflow generation, testing RRFS on the cloud, environment modules | + +------------------+------------------------------------------------+---------------------------------------------------------------------------------------------+ + | NCAR | Mike Kavulich (@mkavulich) | CCPP/physics | + | +------------------------------------------------+---------------------------------------------------------------------------------------------+ + | | Will Mayfield (@willmayfield) | Verification/METplus tasks, regional_workflow (esp. on Cheyenne) | + +------------------+------------------------------------------------+---------------------------------------------------------------------------------------------+ + | NSSL | Yunheng Wang (@ywangwof) | HPC systems, code management and regional workflow especially on Stampede, Jet | + | | | and NSSL computers | + +------------------+------------------------------------------------+---------------------------------------------------------------------------------------------+ + .. _ContribProcess: Contribution Process diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 30b1e36955..0d48c55237 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -53,7 +53,6 @@ Glossary Convection-allowing models (CAMs) are models that run on high-resolution grids (usually with grid spacing at 4km or less). They are able to resolve the effects of small-scale convective processes. They typically run several times a day to provide frequent forecasts (e.g., hourly or subhourly). cycle - cycles An hour of the day on which a forecast is started. cycle-dependent @@ -98,8 +97,7 @@ Glossary A strip of cells on the edge of the regional grid. The :ref:`wide halo ` surrounds the regional grid and is used to feed the lateral boundary conditions into the grid. The :ref:`HALO_BLEND ` parameter refers to a strip of cells *inside* the boundary of the native grid. This halo smooths out mismatches between the external and internal solutions. HPC - HPCs - High-Performance Computing (HPC) System(s). + High-Performance Computing. HPC-Stack The `HPC-Stack `__ is a repository that provides a unified, shell script-based build system for building the software stack required for numerical weather prediction (NWP) tools such as the `Unified Forecast System (UFS) `__ and the `Joint Effort for Data assimilation Integration (JEDI) `__ framework. @@ -110,18 +108,15 @@ Glossary HRRR `High Resolution Rapid Refresh `__. The HRRR is a NOAA real-time 3-km resolution, hourly updated, cloud-resolving, convection-allowing atmospheric model initialized by 3km grids with 3km radar assimilation. Radar data is assimilated in the HRRR every 15 min over a 1-h period adding further detail to that provided by the hourly data assimilation from the 13km radar-enhanced Rapid Refresh. - IC/LBC IC/LBCs Initial conditions/lateral boundary conditions - IC ICs Initial conditions LAM Limited Area Model (grid type), formerly known as the "Stand-Alone Regional Model," or SAR. LAM grids use a regional (rather than global) configuration of the :term:`FV3` :term:`dynamical core`. - LBC LBCs Lateral boundary conditions @@ -181,7 +176,6 @@ Glossary Orography The branch of physical geography dealing with mountains. - Parameterization Parameterizations Simplified functions that approximate the effects of small-scale processes (e.g., microphysics, gravity wave drag) that cannot be explicitly resolved by a model grid’s representation of the earth. @@ -198,7 +192,6 @@ Glossary The `spack-stack `__ is a collaborative effort between the NOAA Environmental Modeling Center (EMC), the UCAR Joint Center for Satellite Data Assimilation (JCSDA), and the Earth Prediction Innovation Center (EPIC). *spack-stack* is a repository that provides a Spack-based method for building the software stack required for numerical weather prediction (NWP) tools such as the `Unified Forecast System (UFS) `__ and the `Joint Effort for Data assimilation Integration (JEDI) `__ framework. spack-stack uses the Spack package manager along with custom Spack configuration files and Python scripts to simplify installation of the libraries required to run various applications. The *spack-stack* can be installed on a range of platforms and comes pre-configured for many systems. Users can install the necessary packages for a particular application and later add the missing packages for another application without having to rebuild the entire stack. tracer - tracers According to the American Meteorological Society (AMS) `definition `__, a tracer is "Any substance in the atmosphere that can be used to track the history [i.e., movement] of an air mass." Tracers are carried around by the motion of the atmosphere (i.e., by :term:`advection`). These substances are usually gases (e.g., water vapor, CO2), but they can also be non-gaseous (e.g., rain drops in microphysics parameterizations). In weather models, temperature (or potential temperature), absolute humidity, and radioactivity are also usually treated as tracers. According to AMS, "The main requirement for a tracer is that its lifetime be substantially longer than the transport process under study." UFS diff --git a/docs/UsersGuide/source/Include-HPCInstall.rst b/docs/UsersGuide/source/Include-HPCInstall.rst deleted file mode 100644 index e9d5e2d482..0000000000 --- a/docs/UsersGuide/source/Include-HPCInstall.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _InstallHPCstack: - -.. include:: ../../../hpc-stack-mod/docs/source/hpc-install.rst -.. include:: ../../../hpc-stack-mod/docs/source/mac-install.rst - -.. include:: ../../../hpc-stack-mod/docs/source/hpc-prereqs.rst -.. include:: ../../../hpc-stack-mod/docs/source/hpc-parameters.rst -.. include:: ../../../hpc-stack-mod/docs/source/hpc-components.rst -.. include:: ../../../hpc-stack-mod/docs/source/hpc-notes.rst \ No newline at end of file diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 9432e361b3..124a888795 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -68,9 +68,9 @@ and are shown in :numref:`Table %s `. +-----------------------------+--------------------------------------------------------------+ | field_table_[CCPP] | :term:`Cycle-independent` file that the forecast model | | | reads in at the start of each forecast. It specifies the | - | | :term:`tracers` that the forecast model will :term:`advect`. | - | | A different ``field_table`` may be needed for different | - | | CCPP suites. | + | | :term:`tracers ` that the forecast model will | + | | :term:`advect`. A different ``field_table`` may be needed | + | | for different CCPP suites. | +-----------------------------+--------------------------------------------------------------+ | FV3.input.yml | YAML configuration file containing the forecast model's | | | namelist settings for various physics suites. The values | @@ -179,8 +179,8 @@ If users wish to modify the fields or levels that are output from the UPP, they This process requires advanced knowledge of which fields can be output for the UFS Weather Model. UPP Product Output Tables for the UFS SRW LAM Grid: - * :doc:`3D Native Hybrid Level Fields ` - * :doc:`3D Pressure Level Fields ` + * :doc:`3D Native Hybrid Level Fields ` + * :doc:`3D Pressure Level Fields ` Use the instructions in the `UPP User's Guide `__ to make modifications to the ``fv3lam.xml`` file and to remake the flat text file, called ``postxconfig-NT-fv3lam.txt`` (default), that the UPP reads. @@ -277,7 +277,7 @@ The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBC EXTRN_MDL_SOURCE_BASEDIR_ICS="" EXTRN_MDL_SOURCE_BASEDIR_LBCS="" -These last two variables describe where the :term:`IC` and :term:`LBC` file directories are located, respectively. For ease of reusing ``config.sh`` across experiments, it is recommended that users set up the raw :term:`IC/LBC` file paths to include the model name (e.g., FV3GFS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path-to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. +These last two variables describe where the :term:`IC ` and :term:`LBC ` file directories are located, respectively. For ease of reusing ``config.sh`` across experiments, it is recommended that users set up the raw :term:`IC/LBC ` file paths to include the model name (e.g., FV3GFS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path-to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. When files are pulled from NOAA :term:`HPSS` (rather than downloaded from the data bucket), the naming convention looks something like: diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index fe351602a9..390e9ca2d6 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -107,7 +107,7 @@ The following software is also required to run the SRW Application, but the :ter * Only **MPICH** or **OpenMPI** can be built with HPC-Stack. Other implementations must be installed separately by the user (if desired). -For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew `__ package manager for MacOS. See :numref:`Chapter %s ` and :numref:`Chapter %s ` for further guidance on installing these prerequisites on MacOS. +For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew `__ package manager for MacOS. See :ref:`Chapter %s ` and :numref:`Chapter %s ` for further guidance on installing these prerequisites on MacOS. * bash v4.x * GNU compiler suite v.11 or higher with gfortran @@ -217,7 +217,7 @@ The :term:`umbrella repository` for the SRW Application is named ``ufs-srweather The UFS Weather Model contains a number of sub-repositories, which are documented `here `__. .. note:: - The prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The `HPC-Stack `__ repository assembles these prerequisite libraries. The HPC-Stack has already been built on `preconfigured (Level 1) platforms `__. However, it must be built on other systems. :numref:`Chapter %s ` contains details on installing the HPC-Stack. + The prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The `HPC-Stack `__ repository assembles these prerequisite libraries. The HPC-Stack has already been built on `preconfigured (Level 1) platforms `__. However, it must be built on other systems. See the :doc:`HPC-Stack Documentation ` for details on installing the HPC-Stack. .. _TopLevelDirStructure: @@ -310,7 +310,7 @@ When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` scr +---------------------------+--------------------------------------------------------------------------------------------------------------+ | data_table | :term:`Cycle-independent` input file (empty) | +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | field_table | :term:`Tracers` in the `forecast model | + | field_table | :term:`Tracers ` in the `forecast model | | | `__ | +---------------------------+--------------------------------------------------------------------------------------------------------------+ | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | @@ -447,7 +447,7 @@ A list of available documentation is shown in :numref:`Table %s `. Contributions to the `ufs-srweather-app `__ repository or the `regional_workflow `__ repository should follow the guidelines contained in the :ref:`SRW App Contributor's Guide `. @@ -476,4 +474,3 @@ Users can expect to see incremental improvements and additional capabilities in - diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 90419b72bf..c0ca4d6a0a 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -9,7 +9,7 @@ This chapter provides a brief summary of how to build and run the SRW Applicatio Install the HPC-Stack =========================== -SRW App users who are not working on a `Level 1 `__ platform will need to install the :term:`HPC-Stack` prior to building the SRW App on a new machine. Installation instructions appear in both the `HPC-Stack documentation `__ and in :numref:`Chapter %s ` of this User's Guide. The steps will vary slightly depending on the user's platform. However, in all cases, the process involves cloning the `HPC-Stack repository `__, creating and entering a build directory, and invoking ``cmake`` and ``make`` commands to build the stack. This process will create a number of modulefiles and scripts that will be used for setting up the build environment for the SRW App. +SRW App users who are not working on a `Level 1 `__ platform will need to install the :term:`HPC-Stack` prior to building the SRW App on a new machine. Installation instructions appear in the :doc:`HPC-Stack documentation `. The steps will vary slightly depending on the user's platform. However, in all cases, the process involves cloning the `HPC-Stack repository `__, creating and entering a build directory, and invoking ``cmake`` and ``make`` commands to build the stack. This process will create a number of modulefiles and scripts that will be used for setting up the build environment for the SRW App. Once the HPC-Stack has been successfully installed, users can move on to building the SRW Application. @@ -66,16 +66,27 @@ For a detailed explanation of how to build and run the SRW App on any supported cmake .. -DCMAKE_INSTALL_PREFIX=.. make -j 4 >& build.out & - #. Download and stage data (both the fix files and the :term:`IC/LBC` files) according to the instructions in :numref:`Section %s ` (if on a Level 2-4 system). + #. Download and stage data (both the fix files and the :term:`IC/LBC ` files) according to the instructions in :numref:`Section %s ` (if on a Level 2-4 system). #. Configure the experiment parameters. .. code-block:: console - cd regional_workflow/ush - cp config.community.sh config.sh + cd ush + cp config.community.yaml config.yaml - Users will need to adjust the experiment parameters in the ``config.sh`` file to suit the needs of their experiment (e.g., date, time, grid, physics suite, etc.). More detailed guidance is available in :numref:`Section %s `. Parameters and valid values are listed in :numref:`Chapter %s `. + Users will need to adjust the experiment parameters in the ``config.yaml`` file to suit the needs of their experiment (e.g., date, time, grid, physics suite, etc.). More detailed guidance is available in :numref:`Section %s `. Parameters and valid values are listed in :numref:`Chapter %s `. To determine whether the ``config.yaml`` file adjustments are valid, users can run: + + .. code-block:: console + + ./config_utils.py -c $PWD/config.yaml -v $PWD/config_defaults.yaml + + A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yaml`` file with problems will output a ``FAILURE`` message describing the problem. For example: + + .. code-block:: console + + INVALID ENTRY: EXTRN_MDL_FILES_ICS=[] + FAILURE #. Load the python environment for the regional workflow. Users on Level 2-4 systems will need to use one of the existing ``wflow_`` modulefiles (e.g., ``wflow_macos``) and adapt it to their system. @@ -97,7 +108,7 @@ For a detailed explanation of how to build and run the SRW App on any supported .. code-block:: console - ./generate_FV3LAM_wflow.sh + ./generate_FV3LAM_wflow.py #. Run the regional workflow. There are several methods available for this step, which are discussed in :numref:`Section %s `. One possible method is summarized below. It requires the Rocoto Workflow Manager. diff --git a/docs/UsersGuide/source/RocotoInfo.rst b/docs/UsersGuide/source/RocotoInfo.rst index 075e029165..ac49064abf 100644 --- a/docs/UsersGuide/source/RocotoInfo.rst +++ b/docs/UsersGuide/source/RocotoInfo.rst @@ -7,7 +7,7 @@ The tasks in the SRW Application (:numref:`Table %s `) are t the Rocoto Workflow Manager. Rocoto is a Ruby program that communicates with the batch system on an :term:`HPC` system to run and manage dependencies between the tasks. Rocoto submits jobs to the HPC batch system as the task dependencies allow and runs one instance of the workflow for a set of user-defined -:term:`cycles`. More information about Rocoto can be found on the `Rocoto Wiki `__. +:term:`cycles `. More information about Rocoto can be found on the `Rocoto Wiki `__. The SRW App workflow is defined in a Jinja-enabled Rocoto XML template called ``FV3LAM_wflow.xml``, which resides in the ``regional_workflow/ush/templates`` directory. When the ``generate_FV3LAM_wflow.sh`` diff --git a/docs/UsersGuide/source/WE2Etests.rst b/docs/UsersGuide/source/WE2Etests.rst index f4803a56de..93b075781f 100644 --- a/docs/UsersGuide/source/WE2Etests.rst +++ b/docs/UsersGuide/source/WE2Etests.rst @@ -44,7 +44,7 @@ the executables have been built (see :numref:`Section %s `). I Supported Tests =================== -The full list of WE2E tests is extensive; it is not recommended to run all the tests, as some are computationally expensive. A subset of the full WE2E test suite is supported for the latest release of the SRW Application. Supported test cases can be viewed in :doc:`this table `. +The full list of WE2E tests is extensive; it is not recommended to run all the tests, as some are computationally expensive. A subset of the full WE2E test suite is supported for the latest release of the SRW Application. Supported test cases can be viewed in :doc:`this table `. Running the WE2E Tests ================================ diff --git a/docs/UsersGuide/source/conf.py b/docs/UsersGuide/source/conf.py index 5195edc819..39d812cf7c 100644 --- a/docs/UsersGuide/source/conf.py +++ b/docs/UsersGuide/source/conf.py @@ -203,7 +203,9 @@ def setup(app): # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/3/': None} +intersphinx_mapping = { + 'hpc-stack': ('https://hpc-stack.readthedocs.io/en/latest/', None), +} # -- Options for todo extension ---------------------------------------------- diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index bed2528493..d2dd7398a7 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -16,7 +16,6 @@ UFS Short-Range Weather App Users Guide ContainerQuickstart BuildRunSRW Components - Include-HPCInstall InputOutputFiles LAMGrids ConfigWorkflow diff --git a/docs/UsersGuide/source/tables/.DS_Store b/docs/UsersGuide/source/tables/.DS_Store new file mode 100644 index 0000000000..18f33935bc Binary files /dev/null and b/docs/UsersGuide/source/tables/.DS_Store differ diff --git a/docs/UsersGuide/source/SRW_NATLEV_table.csv b/docs/UsersGuide/source/tables/SRW_NATLEV_table.csv similarity index 100% rename from docs/UsersGuide/source/SRW_NATLEV_table.csv rename to docs/UsersGuide/source/tables/SRW_NATLEV_table.csv diff --git a/docs/UsersGuide/source/SRW_NATLEV_table.rst b/docs/UsersGuide/source/tables/SRW_NATLEV_table.rst similarity index 100% rename from docs/UsersGuide/source/SRW_NATLEV_table.rst rename to docs/UsersGuide/source/tables/SRW_NATLEV_table.rst diff --git a/docs/UsersGuide/source/SRW_PRSLEV_table.csv b/docs/UsersGuide/source/tables/SRW_PRSLEV_table.csv similarity index 100% rename from docs/UsersGuide/source/SRW_PRSLEV_table.csv rename to docs/UsersGuide/source/tables/SRW_PRSLEV_table.csv diff --git a/docs/UsersGuide/source/SRW_PRSLEV_table.rst b/docs/UsersGuide/source/tables/SRW_PRSLEV_table.rst similarity index 100% rename from docs/UsersGuide/source/SRW_PRSLEV_table.rst rename to docs/UsersGuide/source/tables/SRW_PRSLEV_table.rst diff --git a/docs/UsersGuide/source/Tests.csv b/docs/UsersGuide/source/tables/Tests.csv similarity index 100% rename from docs/UsersGuide/source/Tests.csv rename to docs/UsersGuide/source/tables/Tests.csv diff --git a/docs/UsersGuide/source/Tests.rst b/docs/UsersGuide/source/tables/Tests.rst similarity index 100% rename from docs/UsersGuide/source/Tests.rst rename to docs/UsersGuide/source/tables/Tests.rst diff --git a/docs/UsersGuide/source/fix_file_list.rst b/docs/UsersGuide/source/tables/fix_file_list.rst similarity index 100% rename from docs/UsersGuide/source/fix_file_list.rst rename to docs/UsersGuide/source/tables/fix_file_list.rst diff --git a/hpc-stack-mod b/hpc-stack-mod deleted file mode 160000 index af75dcf24e..0000000000 --- a/hpc-stack-mod +++ /dev/null @@ -1 +0,0 @@ -Subproject commit af75dcf24ed64486a79b017354b423bc484db681