From 370bb6c5011bb42f68740ac7649694e59f77f8c3 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 11 Feb 2022 14:07:50 -0500 Subject: [PATCH 001/158] updated docs --- .gitignore | 1 + docs/UsersGuide/source/Components.rst | 217 ++++++++++++++++++ docs/UsersGuide/source/Glossary.rst | 24 ++ docs/UsersGuide/source/Include-HPCInstall.rst | 6 + docs/UsersGuide/source/Introduction.rst | 147 +++++------- docs/UsersGuide/source/Quickstart.rst | 213 ++++++++++------- docs/UsersGuide/source/conf.py | 4 +- docs/UsersGuide/source/index.rst | 7 +- 8 files changed, 442 insertions(+), 177 deletions(-) create mode 100644 .gitignore create mode 100644 docs/UsersGuide/source/Components.rst create mode 100644 docs/UsersGuide/source/Include-HPCInstall.rst diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000..e43b0f9889 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst new file mode 100644 index 0000000000..26822fe341 --- /dev/null +++ b/docs/UsersGuide/source/Components.rst @@ -0,0 +1,217 @@ +.. _Components: + +=============== +SRW Components +=============== + +The SRW Application v2.0 release assembles a variety of components, including: +* Pre-processor Utilities & Initial Conditions +* Forecast Model +* Post-Processor +* Visualization Example +* Build System and Workflow +* User Support, Documentation, and Contributing Development + +These components are documented within this User's Guide and supported through a `community forum `_. + + +Pre-processor Utilities and Initial Conditions +============================================== + +The SRW Application includes a number of pre-processing utilities that initialize and prepare the +model. Tasks include generating a regional grid, along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. + +The SRW Application includes a number of pre-processing utilities to initialize and prepare the +model. For the limited area model (LAM), it is necessary to first generate a +regional grid ``regional_esg_grid/make_hgrid`` along with orography ``orog`` and surface climatology ``sfc_climo_gen`` files on that grid. There are additional utilities included to handle the correct number of halo ``shave`` points and topography filtering ``filter_topo``. The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format, needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. + +.. + COMMENT: "Integration" with what?!?! (1st sentence) --> Try "prepare the model data" instead of "prepare the model for integration." + COMMENT: Why are we using code/commands in an overview doc?! A newbie is going to glaze over and give up. + +The SRW Application can be initialized from a range of operational initial condition files. It is +possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (GRIB2) format and GFS in NEMSIO format for past dates. + +.. WARNING:: + Please note, for GFS data, dates prior to 1 January 2018 may work but are not guaranteed. Public archives of model data can be accessed through the `National Centers for Environmental Information `_ (NCEI) or through the `NOAA Operational Model Archive and Distribution System `_ (NOMADS). Raw external model data may be pre-staged on disk by the user. + + +Forecast Model +============== + +The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere +(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability :cite:`BlackEtAl2020`. +The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `_. + +Supported model resolutions in this release include a 3-, 13-, and 25-km predefined Contiguous +U.S. (CONUS) domain, all with 64 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 `here +`_ and on the `NOAA Geophysical +Fluid Dynamics Laboratory website `_. + +Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) +Land Surface Model options, are supported through the Common Community Physics Package +(:term:`CCPP`; described `here `_). +Atmospheric physics are a set of numerical methods describing small-scale processes such +as clouds, turbulence, radiation, and their interactions. There are two physics options +supported for the release. The first is an experimental physics suite 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) v15. 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. + +The SRW App supports the use of both GRIB2 and :term:`NEMSIO` input data. The UFS Weather Model +ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in +netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal and model +levels in the vertical. + +Post-processor +============== + +The SRW Application is distributed with the Unified Post Processor (:term:`UPP`) included in the +workflow as a way to convert the netCDF output on the native model grid to GRIB2 format on +standard isobaric vertical coordinates. UPP can also be used to compute a variety of useful +diagnostic fields, as described in the `UPP user’s guide `_. + +Output from UPP can be used with visualization, plotting, and verification packages, or for +further downstream post-processing, e.g. statistical post-processing techniques. + +Visualization Example +===================== +A Python script is provided to create basic visualization of the model output. The script +is designed to output graphics in PNG format for 14 standard meteorological variables +when using the pre-defined CONUS domain. In addition, a difference plotting script is included +to visually compare two runs for the same domain and resolution. These scripts are provided only +as an example for users familiar with Python, and may be used to do a visual check to verify +that the application is producing reasonable results. + +The scripts are available in the `regional_workflow repository +`_ +under ush/Python. Usage information and instructions are described in +:numref:`Chapter %s ` and are also included at the top of the script. + +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: the UFS Weather Model and the pre- and +post-processing software. Additional libraries (:term:`NCEPLIBS-external` and :term:`NCEPLIBS`) necessary +for the application are not included in the SRW Application build system, but are available +pre-built on pre-configured platforms. 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 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 (see `Rocoto documentation +`_) in the proper sequence. +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 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, whether to run some or all of the pre-processing, +forecast model, and post-processing steps. + +This SRW Application release has been tested on a variety of platforms widely used by +researchers, such as the NOAA Research and Development High-Performance Computing Systems +(RDHPCS), including Hera, Orion, and Jet; NOAA’s Weather and Climate Operational +Supercomputing System (WCOSS); the National Center for Atmospheric Research (NCAR) Cheyenne +system; NSSL’s HPC machine, Odin; the National Science Foundation Stampede2 system; and +generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support +`_ +have been defined for the SRW Application, including pre-configured (level 1), configurable +(level 2), limited test platforms (level 3), and build only platforms (level 4). Each +level is further described below. + +For the selected computational platforms that have been pre-configured (level 1), all the +required libraries for building the SRW Application are available in a central place. That +means bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) have both +been built. The SRW Application is expected to build and run out of the box on these +pre-configured platforms and users can proceed directly to the using the workflow, as +described in the Quick Start (:numref:`Chapter %s `). + +A few additional computational platforms are considered configurable for the SRW +Application release. Configurable platforms (level 2) are platforms where all of +the required libraries for building the SRW Application are expected to install successfully, +but are not available in a central place. Applications and models are expected to build +and run once the required bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) +are built. + +Limited-Test (level 3) and Build-Only (level 4) computational platforms are those in which +the developers have built the code but little or no pre-release testing has been conducted, +respectively. A complete description of the levels of support, along with a list of preconfigured +and configurable platforms can be found in the `SRW Application wiki page +`_. + +User Support, Documentation, and Contributing Development +========================================================= + +A forum-based, online `support system `_ organized by topic +provides a centralized location for UFS users and developers to post questions and exchange +information. + +A list of available documentation is shown in :numref:`Table %s `. + +.. _list_of_documentation: + +.. table:: Centralized list of documentation + + +----------------------------+---------------------------------------------------------------------------------+ + | **Documentation** | **Location** | + +============================+=================================================================================+ + | UFS SRW Application v1.0 | https://ufs-srweather-app.readthedocs.io/en/ufs-v1.0.0 | + | User's Guide | | + +----------------------------+---------------------------------------------------------------------------------+ + | UFS_UTILS v2.0 User's | https://noaa-emcufs-utils.readthedocs.io/en/ufs-v2.0.0/ | + | Guide | | + +----------------------------+---------------------------------------------------------------------------------+ + | UFS Weather Model v2.0 | https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0 | + | User's Guide | | + +----------------------------+---------------------------------------------------------------------------------+ + | NCEPLIBS Documentation | https://github.com/NOAA-EMC/NCEPLIBS/wiki | + +----------------------------+---------------------------------------------------------------------------------+ + | NCEPLIBS-external | https://github.com/NOAA-EMC/NCEPLIBS-external/wiki | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | FV3 Documentation | https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html | + +----------------------------+---------------------------------------------------------------------------------+ + | CCPP Scientific | https://dtcenter.ucar.edu/GMTB/v5.0.0/sci_doc/index.html | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | CCPP Technical | https://ccpp-techdoc.readthedocs.io/en/v5.0.0/ | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | ESMF manual | http://earthsystemmodeling.org/docs/release/ESMF_8_0_0/ESMF_usrdoc/ | + +----------------------------+---------------------------------------------------------------------------------+ + | Unified Post Processor | https://upp.readthedocs.io/en/upp-v9.0.0/ | + +----------------------------+---------------------------------------------------------------------------------+ + +The UFS community is encouraged to contribute to the development effort of all related +utilities, model code, and infrastructure. Issues can be posted in SRW-related GitHub repositories to report bugs or to announce upcoming contributions to the code base. For code to be accepted in the authoritative repositories, users must follow the code management rules of each component (described in the User’s Guides listed in :numref:`Table %s `. + +Future Direction +================ + +Users can expect to see incremental improvements and additional capabilities in upcoming +releases of the SRW Application to enhance research opportunities and support operational +forecast implementations. Planned advancements include: + +* A more extensive set of supported developmental physics suites. +* A larger number of pre-defined domains/resolutions and a fully supported capability to create a user-defined domain. +* Inclusion of data assimilation, cycling, and ensemble capabilities. +* A verification package (i.e., METplus) integrated into the workflow. +* Inclusion of stochastic perturbation techniques. + +In addition to the above list, other improvements will be addressed in future releases. + +.. bibliography:: references.bib diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 622814368a..d3deb40672 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -11,19 +11,34 @@ Glossary parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model. + CONUS + Continental United States + chgres_cube The preprocessing software used to create initial and boundary condition files to “coldstart” the forecast model. + 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. + + .. + COMMENT: Clarify HRRR definition! + FV3 The Finite-Volume Cubed-Sphere dynamical core (dycore). Developed at NOAA's Geophysical Fluid Dynamics Laboratory (GFDL), it is a scalable and flexible dycore capable of both hydrostatic and non-hydrostatic atmospheric simulations. It is the dycore used in the UFS Weather Model. + GFS + `Global Forecast System `_. The GFS is a National Centers for Environmental Prediction (NCEP) weather forecast model that generates data for dozens of atmospheric and land-soil variables, including temperatures, winds, precipitation, soil moisture, and atmospheric ozone concentration. The system couples four separate models (atmosphere, ocean model, land/soil model, and sea ice) that work together to accurately depict weather conditions. + GRIB2 The second version of the World Meterological Organization's (WMO) standard for distributing gridded data. + NAM + `North American Mesoscale Forecast System `_. NAM generates multiple grids (or domains) of weather forecasts over the North American continent at various horizontal resolutions. Each grid contains data for dozens of weather parameters, including temperature, precipitation, lightning, and turbulent kinetic energy. NAM uses additional numerical weather models to generate high-resolution forecasts over fixed regions, and occasionally to follow significant weather events like hurricanes. + NCEP National Centers for Environmental Prediction, an arm of the National Weather Service, consisting of nine centers. More information can be found at https://www.ncep.noaa.gov. @@ -47,6 +62,12 @@ Glossary NEMSIO A binary format for atmospheric model output from :term:`NCEP`'s Global Forecast System (GFS). + Orography + The branch of physical geography dealing with mountains + + RAP + `Rapid Refresh `. The continental-scale NOAA hourly-updated assimilation/modeling system operational at NCEP. RAP covers North America and is comprised primarily of a numerical forecast model and an analysis/assimilation system to initialize that model. RAP is complemented by the higher-resolution 3km High-Resolution Rapid Refresh (HRRR) model. + UFS The Unified Forecast System is a community-based, coupled comprehensive Earth modeling system consisting of several applications (apps). These apps span regional to global @@ -64,6 +85,9 @@ Glossary The Unified Post Processor is software developed at :term:`NCEP` and used operationally to post-process raw output from a variety of :term:`NCEP`'s NWP models, including the FV3. + Weather Enterprise + Individuals and organizations from public, private, and academic sectors that contribute to the research, development, and production of weather forecast products; primary consumers of these weather forecast products. + Weather Model A prognostic model that can be used for short- and medium-range research and operational forecasts. It can be an atmosphere-only model or an atmospheric diff --git a/docs/UsersGuide/source/Include-HPCInstall.rst b/docs/UsersGuide/source/Include-HPCInstall.rst new file mode 100644 index 0000000000..4fa2a9989b --- /dev/null +++ b/docs/UsersGuide/source/Include-HPCInstall.rst @@ -0,0 +1,6 @@ +.. _InstallHPCstack: + +====================== +Install the HPC-Stack +====================== +.. include:: ../../../docs/source/hpc-install.rst \ No newline at end of file diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index ac1bedb1b0..363bb745c5 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -4,109 +4,69 @@ Introduction ============ -The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. -It is designed to be the source system for NOAA’s operational numerical weather prediction applications -while enabling research, development, and contribution opportunities for the broader weather enterprise. -For more information about the UFS, visit the UFS Portal at https://ufscommunity.org/. - -The UFS can be configured for multiple applications (see a complete list at -https://ufscommunity.org/science/aboutapps/). The configuration described here is the UFS Short-Range -Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain -and on time scales from less than an hour out to several days. The SRW Application v1.0 release includes a -prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system -end-to-end, which are documented within the User's Guide and supported through a community forum. -Future work will include expanding the capabilities of the application to include data assimilation -(DA) and a verification package (e.g. METplus) as part of the workflow. This documentation provides an -overview of the release components, a description of the supported capabilities, a quick start guide -for running the application, and information on where to find more information and obtain support. +The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the UFS Portal at https://ufscommunity.org/. + +The UFS can be configured for multiple applications (see a complete list at https://ufscommunity.org/science/aboutapps/). The configuration described here is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v1.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g. METplus). This documentation provides a quick start guide for running the application, in addition to an overview of the release components, a description of the supported capabilities, and information on where to find more information and obtain support. The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research -conducted with the App. +conducted with the App: + +UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994 -UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application -(Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994 +.. + COMMENT: What will be the numbering for this release? It will need to be changed above and throughout the docs. + COMMENT: Can this app be used beyond the CONUS? Change "limited spatial domain" above to CONUS or something more specific. + COMMENT: Where are we on the DA and verification package? Can we update that line? + COMMENT: Update citation date & version number. What is Zenodo? + COMMENT: Disagree: "This documentation provides... information on where to find more information and obtain support." We need to add this (i.e. link in the docs) or remove the line. + COMMENT: "Components" doc created but not added to TOC. Contains more detailed info on components discussed here below. Pre-processor Utilities and Initial Conditions ============================================== -The SRW Application includes a number of pre-processing utilities to initialize and prepare the -model for integration. For the limited area model (LAM), it is necessary to first generate a -regional grid ``regional_esg_grid/make_hgrid`` along with orography ``orog`` and surface climatology ``sfc_climo_gen`` -files on that grid. There are additional utilities included to handle the correct number of halo ``shave`` -points and topography filtering ``filter_topo``. The pre-processing software ``chgres_cube`` -is used to convert the raw external model data into initial and lateral boundary condition files in netCDF -format, needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can -be found in the `UFS_UTILS User’s Guide `_. +The SRW Application includes a number of pre-processing utilities that initialize and prepare the +model. Tasks include generating a regional grid, along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. -The SRW Application can be initialized from a range of operational initial condition files. It is -possible to initialize the model from GFS, NAM, RAP, and HRRR files in Gridded Binary v2 (GRIB2) -format and GFS in NEMSIO format for past dates. Please note, for GFS data, dates prior to 1 January 2018 may work but are -not guaranteed. Public archives of model data can be accessed through the `National Centers for -Environmental Information `_ -(NCEI) or through the `NOAA Operational Model Archive and Distribution System `_ -(NOMADS). Raw external model data may be pre-staged on disk by the user. + +.. + COMMENT: "Integration" with what?!?! (1st sentence) --> Try "prepare the model data" instead of "prepare the model for integration." + COMMENT: Deleted code/commands bc it's an introduction. + COMMENT: What is a "halo shave point" or wide-halo grid?! Forecast Model ============== +Atmospheric Model +-------------------- + The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere (:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability :cite:`BlackEtAl2020`. -The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s -Guide for the UFS :term:`Weather Model` is `here `_. - -Supported model resolutions in this release include a 3-, 13-, and 25-km predefined Contiguous -U.S. (CONUS) domain, all with 64 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 `here -`_ and on the `NOAA Geophysical -Fluid Dynamics Laboratory website `_. - -Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) -Land Surface Model options, are supported through the Common Community Physics Package -(:term:`CCPP`; described `here `_). -Atmospheric physics are a set of numerical methods describing small-scale processes such -as clouds, turbulence, radiation, and their interactions. There are two physics options -supported for the release. The first is an experimental physics suite 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) v15. 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. - -The SRW App supports the use of both GRIB2 and :term:`NEMSIO` input data. The UFS Weather Model -ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in -netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal and model -levels in the vertical. +The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `_. + +Common Community Physics Package +--------------------------------- + +The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and Noah Multi-parameterization (Noah MP) Land Surface Model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions.The SRW release includes an experimental physics version and an updated operational version. + +Data Format +-------------- + +The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model +ingests initial and lateral boundary condition files produced by :term:`chgres_cube`. + Post-processor ============== -The SRW Application is distributed with the Unified Post Processor (:term:`UPP`) included in the -workflow as a way to convert the netCDF output on the native model grid to GRIB2 format on -standard isobaric vertical coordinates. UPP can also be used to compute a variety of useful -diagnostic fields, as described in the `UPP user’s guide `_. +The Unified Post Processor (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF output on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP user’s guide `_. Output from UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing, e.g. statistical post-processing techniques. -Output from UPP can be used with visualization, plotting, and verification packages, or for -further downstream post-processing, e.g. statistical post-processing techniques. Visualization Example ===================== -A Python script is provided to create basic visualization of the model output. The script -is designed to output graphics in PNG format for 14 standard meteorological variables -when using the pre-defined CONUS domain. In addition, a difference plotting script is included -to visually compare two runs for the same domain and resolution. These scripts are provided only -as an example for users familiar with Python, and may be used to do a visual check to verify -that the application is producing reasonable results. - -The scripts are available in the `regional_workflow repository -`_ -under ush/Python. Usage information and instructions are described in +This SRW Application distribution provides Python scripts to create basic visualization of the model output. The scripts are available in the ```regional_workflow`` repository +`_ +under ``ush/Python``. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. Build System and Workflow @@ -115,6 +75,9 @@ Build System and Workflow The SRW Application has a portable build system and a user-friendly, modular, and expandable workflow framework. +.. + COMMENT: Define build system and workflow... + An umbrella CMake-based build system is used for building the components necessary for running the end-to-end SRW Application: the UFS Weather Model and the pre- and post-processing software. Additional libraries (:term:`NCEPLIBS-external` and :term:`NCEPLIBS`) necessary @@ -138,12 +101,7 @@ This SRW Application release has been tested on a variety of platforms widely us researchers, such as the NOAA Research and Development High-Performance Computing Systems (RDHPCS), including Hera, Orion, and Jet; NOAA’s Weather and Climate Operational Supercomputing System (WCOSS); the National Center for Atmospheric Research (NCAR) Cheyenne -system; NSSL’s HPC machine, Odin; the National Science Foundation Stampede2 system; and -generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support -`_ -have been defined for the SRW Application, including pre-configured (level 1), configurable -(level 2), limited test platforms (level 3), and build only platforms (level 4). Each -level is further described below. +system; the National Severe Storms Laboratory (NSSL) HPC machine, called Odin; the National Science Foundation (NSF) Stampede2 system; and generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support `_have been defined for the SRW Application, including pre-configured (level 1), configurable (level 2), limited test platforms (level 3), and build only platforms (level 4). Each level is further described below. For the selected computational platforms that have been pre-configured (level 1), all the required libraries for building the SRW Application are available in a central place. That @@ -168,10 +126,9 @@ and configurable platforms can be found in the `SRW Application wiki page User Support, Documentation, and Contributing Development ========================================================= -A forum-based, online `support system `_ with topical sections +A forum-based, online `support system `_ organized by topic provides a centralized location for UFS users and developers to post questions and exchange -information. The forum complements the formal, written documentation, summarized here for ease of -use. +information. A list of available documentation is shown in :numref:`Table %s `. @@ -210,11 +167,7 @@ A list of available documentation is shown in :numref:`Table %s ` need to be followed. +utilities, model code, and infrastructure. Issues can be posted in SRW-related GitHub repositories to report bugs or to announce upcoming contributions to the code base. For code to be accepted in the authoritative repositories, users must follow the code management rules of each component (described in the User’s Guides listed in :numref:`Table %s `. Future Direction ================ @@ -231,6 +184,8 @@ forecast implementations. Planned advancements include: In addition to the above list, other improvements will be addressed in future releases. +.. + COMMENT: How is a domain different from a grid? Can we say "user-defined grid," for example? Might be clearer. How to Use This Document ======================== @@ -251,3 +206,7 @@ UFS forum at https://forums.ufscommunity.org/. in scripts, names of files and directories. .. bibliography:: references.bib + + + + diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 662d4c92b8..4bcc217076 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -3,73 +3,137 @@ ==================== Workflow Quick Start ==================== -To build and run the out-of-the-box case of the UFS Short-Range Weather (SRW) Application the user -must get the source code for multiple components, including: the regional workflow, the UFS_UTILS -pre-processor utilities, the UFS Weather Model, and the Unified Post Processor (UPP). Once the UFS -SRW Application umbrella repository is cloned, obtaining the necessary external repositories is -simplified by the use of ``manage_externals``. The out-of-the-box case uses a predefined 25-km -CONUS grid (RRFS_CONUS_25km), the GFS version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and -FV3-based GFS raw external model data for initialization. + + + +This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (UFS) Short-Range Weather (SRW) Application. The "out-of-the-box" case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (CONUS) grid (RRFS_CONUS_25km), the Global Forecast System (GFS) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and FV3-based GFS raw external model data for initialization. .. note:: - The steps described in this chapter are applicable to preconfigured (Level 1) machines where - all of the required libraries for building community releases of UFS models and applications - are available in a central place (i.e. the bundled libraries (NCEPLIBS) and third-party - libraries (NCEPLIBS-external) have both been built). The Level 1 platforms are listed `here - `_. - For more information on compiling NCEPLIBS-external and NCEPLIBS, please refer to the - NCEPLIBS-external `wiki `_. + The steps described in this chapter are most applicable to preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems as well but may require additional troubleshooting by the user. The various platform levels are listed `here `_. + + +.. _HPCstackInfo: + +Install the HPC-Stack +======================== + +.. note:: + Skip the HPC-stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion). +.. include:: ../../../hpc-stack/docs/source/hpc-intro.rst + + +After completing installation, continue to the :ref:`next section <_DownloadCode>`. + + +.. _DownloadCode: + Download the UFS SRW Application Code ===================================== -The necessary source code is publicly available on GitHub. To clone the release branch of the repository: +The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under your ``regional_workflow`` and ``src`` directories. + +Run the UFS SRW in a Singularity Container +------------------------------------------- + +Pull the Singularity container: .. code-block:: console - git clone -b ufs-v1.0.0 https://github.com/ufs-community/ufs-srweather-app.git - cd ufs-srweather-app + singularity pull ubuntu20.04-hpc-stack-0.1.sif docker://noaaepic/ubuntu20.04-hpc-stack:0.1 + +Build the container and make a ``home`` directory inside it: + +.. code-block:: console + + singularity build --sandbox ubuntu20.04-hpc-stack-0.1 ubuntu20.04-hpc-stack-0.1.sif + cd ubuntu20.04-hpc-stack-0.1 + mkdir home + +Start the container and run an interactive shell within it. This command also binds the local home directory to the container so that data can be shared between them. + +.. code-block:: console + + singularity shell -e --writable --bind /home:/home ubuntu20.04-hpc-stack + +Clone the develop branch of the UFS-SRW weather application repository: + +.. code-block:: console + + git clone https://github.com/jkbk2004/ufs-srweather-app -Then, check out the submodules for the SRW application: +Check out submodules for the SRW Application: .. code-block:: console + cd ufs-srweather-app ./manage_externals/checkout_externals -The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory -and will clone the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code -into the appropriate directories under your ``regional_workflow`` and ``src`` directories. + +Run the UFS SRW Without a Container +------------------------------------ + +Clone the release branch of the repository: + +.. code-block:: console + + git clone -b ufs-v1.0.0 https://github.com/ufs-community/ufs-srweather-app.git + +Then, check out the submodules for the SRW Application: + +.. code-block:: console + + cd ufs-srweather-app + ./manage_externals/checkout_externals .. _SetUpBuild: Set up the Build Environment ============================ -Instructions for loading the proper modules and/or setting the correct environment variables can be -found in the ``env/`` directory in files named ``build__.env``. -The commands in these files can be directly copy-pasted to the command line or the file can be sourced. -You may need to modify certain variables such as the path to NCEP libraries for your individual platform, -or use ``setenv`` rather than ``export`` depending on your environment: + +Container Approach +-------------------- +If the SRW Application has been built in an EPIC-provided Singularity container, set build environments and modules within the `ufs-srweather-app` directory as follows: .. code-block:: console - $ ls -l env/ - -rw-rw-r-- 1 user ral 1062 Apr 27 10:09 build_cheyenne_gnu.env - -rw-rw-r-- 1 user ral 1061 Apr 27 10:09 build_cheyenne_intel.env - -rw-rw-r-- 1 user ral 1023 Apr 27 10:09 build_hera_intel.env - -rw-rw-r-- 1 user ral 1017 Apr 27 10:09 build_jet_intel.env + ln -s /usr/bin/python3 /usr/bin/python + source /usr/share/lmod/6.6/init/profile + module use /opt/hpc-modules/modulefiles/stack + module load hpc hpc-gnu hpc-openmpi hpc-python + module load netcdf hdf5 bacio sfcio sigio nemsio w3emc esmf fms crtm g2 png zlib g2tmpl ip sp w3nco cmake gfsio wgrib2 upp + + +On Other Systems (Non-Container Approach) +------------------------------------------ + +Otherwise, for Level 1 and 2 systems, scripts for loading the proper modules and/or setting the +correct environment variables can be found in the ``env/`` directory of the SRW App in files named +``build__.env``. The commands in these files can be directly copy-pasted +to the command line, or the file can be sourced from the ufs-srweather-app ``env/`` directory. +For example, on Hera, run ``source env/build_hera_intel.env`` from the main ufs-srweather-app +directory to source the appropriate file. + +On Level 3-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. On systems without Lmod, this process will typically involve commands in the form `export =`. You may need to use ``setenv`` rather than ``export`` depending on your environment. + +Troubleshooting +------------------ +* If the system cannot find a module (i.e., a "module unknown" message appears), check whether the module version numbers match in ``ufs-srweather-app/env/build__.env`` and the ``hpc-stack/stack/stack_custom.yaml``. + Build the Executables ===================== -Build the executables as follows: + +Create a directory to hold the build's executables: .. code-block:: console mkdir build cd build -Run ``cmake`` to set up the ``Makefile``, then run ``make``: +From the build directory, run the ``cmake`` command below to set up the ``Makefile``, then run the ``make`` command to build the executables: .. code-block:: console @@ -78,53 +142,52 @@ Run ``cmake`` to set up the ``Makefile``, then run ``make``: Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, you should see the forecast model executable ``NEMS.exe`` and eleven -pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory which are +pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. -Generate the Workflow Experiment -================================ -Generating the workflow experiment requires three steps: +Download and Stage the Data +============================ + +The SRW requires input files to run. These include static datasets, initial and boundary conditions +files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are +already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :doc:`Input and Output Files `, Section 3. Section 1 contains useful background information on the input files required by the SRW. + -* Set experiment parameters in config.sh +Generate the Forecast Experiment +================================= +Generating the forecast experiment requires three steps: + +* Set experiment parameters * Set Python and other environment parameters -* Run the ``generate_FV3LAM_wflow.sh`` script +* Run the ``generate_FV3LAM_wflow.sh`` script to generate the experiment workflow The first two steps depend on the platform being used and are described here for each Level 1 platform. +Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. .. _SetUpConfigFile: -Set up ``config.sh`` file +Set Experiment Parameters ------------------------- -The workflow requires a file called ``config.sh`` to specify the values of your experiment parameters. -Two example templates are provided: ``config.community.sh`` and ``config.nco.sh`` and can be found in -the ``ufs-srweather-app/regional_workflow/ush directory``. The first file is a minimal example for -creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``), -while the second is an example of creating and running an experiment in the *NCO* (operational) mode -(with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be -fully supported for this release while the operational mode will be more exclusively used by NOAA/NCEP -Central Operations (NCO) and those in the NOAA/NCEP/Environmental Modeling Center (EMC) working with -NCO on pre-implementation testing. Sample config.sh files are discussed in this section for Level 1 platforms. - -Make a copy of ``config.community.sh`` to get started (under /path-to-ufs-srweather-app/regional_workflow/ush): +Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in the ``config.sh`` file. Two example ``config.sh`` templates are provided: ``config.community.sh`` and ``config.nco.sh``. They can be found in the ``ufs-srweather-app/regional_workflow/ush`` directory. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. + +Make a copy of ``config.community.sh`` to get started (under /regional_workflow/ush): .. code-block:: console cd ../regional_workflow/ush cp config.community.sh config.sh -Edit the ``config.sh`` file to set the machine you are running on to ``MACHINE``, use an account you can charge for -``ACCOUNT``, and set the name of the experiment with ``EXPT_SUBDIR``. If you have access to the NOAA HPSS from the -machine you are running on, those changes should be sufficient; however, if that is not the case (for example, -on Cheyenne), or if you have pre-staged the initialization data you would like to use, you will also want to set -``USE_USER_STAGED_EXTRN_FILES="TRUE"`` and set the paths to the data for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and -``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. +The default settings in this file include a predefined 25-km CONUS grid (RRFS_CONUS_25km), the GFS v15.2 physics suite (FV3_GFS_v15p2 CCPP), and FV3-based GFS raw external model data for initialization. + +Next, edit the new ``config.sh`` file to customize it for your machine. At a minimum, change the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If you have pre-staged the initialization data for the experiment, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and set the paths to the data for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. + +Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :doc:`Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in the section on :doc:`Limited Area Model (LAM) Grids `. .. note:: - If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will - have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. + If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. -At a minimum, the following parameters should be set for the machine you are using: +Minimum parameter settings for Level 1 machines: For Cheyenne: @@ -169,8 +232,7 @@ For Gaea: ACCOUNT="my_account" EXPT_SUBDIR="my_expt_name" -For WCOSS, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS -project code for the account parameter: +For WCOSS, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: .. code-block:: console @@ -182,37 +244,28 @@ project code for the account parameter: Set up the Python and other Environment Parameters -------------------------------------------------- -Next, it is necessary to load the appropriate Python environment for the workflow. -The workflow requires Python 3, with the packages 'PyYAML', 'Jinja2', and 'f90nml' available. -This Python environment has already been set up on Level 1 platforms, and can be activated in -the following way (when in /path-to-ufs-srweather-app/regional_workflow/ush): +Next, it is necessary to load the appropriate Python environment for the workflow. The workflow requires Python 3, with the packages 'PyYAML', 'Jinja2', and 'f90nml' available. This Python environment has already been set up on Level 1 platforms, and it can be activated in the following way (from ``/ufs-srweather-app/regional_workflow/ush``): .. code-block:: console source ../../env/wflow_.env + Run the ``generate_FV3LAM_wflow.sh`` script ------------------------------------------- -For all platforms, the workflow can then be generated with the command: +For all platforms, the workflow can then be generated from the ``ush`` directory with the command: .. code-block:: console ./generate_FV3LAM_wflow.sh -The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. A -log file called ``log.generate_FV3LAM_wflow`` is generated by this step and can also be found in -``$EXPTDIR``. The settings for these paths can be found in the output from the -``./generate_FV3LAM_wflow.sh`` script. +The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. A log file called ``log.generate_FV3LAM_wflow`` is generated by this step and can also be found in ``$EXPTDIR``. The settings for these paths can be found in the output from the ``./generate_FV3LAM_wflow.sh`` script. Run the Workflow Using Rocoto ============================= -The information in this section assumes that Rocoto is available on the desired platform. -If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts -described in :numref:`Section %s `. There are two ways you can run -the workflow with Rocoto using either the ``./launch_FV3LAM_wflow.sh`` or by hand. +The information in this section assumes that Rocoto is available on the desired platform. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two ways you can run the workflow with Rocoto using either the ``./launch_FV3LAM_wflow.sh`` or by hand. -An environment variable may be set to navigate to the ``$EXPTDIR`` more easily. If the login -shell is bash, it can be set as follows: +An environment variable may be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: .. code-block:: console @@ -231,8 +284,7 @@ To run Rocoto using the script: cd $EXPTDIR ./launch_FV3LAM_wflow.sh -Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named -``log.launch_FV3LAM_wflow`` will be created (or appended to it if it already exists) in ``EXPTDIR``. +Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named ``log.launch_FV3LAM_wflow`` will be created (or appended to it if it already exists) in ``EXPTDIR``. Or to manually call Rocoto: @@ -325,5 +377,4 @@ The workflow run is completed when all tasks have “SUCCEEDED”, and the rocot Plot the Output =============== -Two python scripts are provided to generate plots from the FV3-LAM post-processed GRIB2 output. Information -on how to generate the graphics can be found in :numref:`Chapter %s `. +Two python scripts are provided to generate plots from the FV3-LAM post-processed GRIB2 output. Information on how to generate the graphics can be found in :numref:`Chapter %s `. diff --git a/docs/UsersGuide/source/conf.py b/docs/UsersGuide/source/conf.py index 5b5b02ea4c..8e43ea2c75 100644 --- a/docs/UsersGuide/source/conf.py +++ b/docs/UsersGuide/source/conf.py @@ -17,6 +17,7 @@ sys.path.insert(0, os.path.abspath('.')) + # -- Project information ----------------------------------------------------- project = 'UFS Short-Range Weather App Users Guide' @@ -50,7 +51,8 @@ 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx.ext.napoleon', - 'sphinxcontrib.bibtex' + 'sphinxcontrib.bibtex', + 'myst_parser' ] bibtex_bibfiles = ['references.bib'] diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index f26e03482c..d9ffc68370 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -6,17 +6,22 @@ UFS Short-Range Weather App Users Guide ======================================= +.. index:: + .. toctree:: :numbered: :maxdepth: 3 + Introduction Quickstart CodeReposAndDirs SRWAppOverview + Components + Include-HPCInstall + InputOutputFiles ConfigWorkflow LAMGrids - InputOutputFiles ConfigNewPlatform WE2Etests Graphics From a907487431c0a984c9fd0df3fe691492d2f70c1d Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 11 Feb 2022 14:26:23 -0500 Subject: [PATCH 002/158] added git submodule --- .gitmodules | 3 +++ hpc-stack-mod | 1 + 2 files changed, 4 insertions(+) create mode 100644 .gitmodules create mode 160000 hpc-stack-mod diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000000..d115eb5c82 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "hpc-stack-mod"] + path = hpc-stack-mod + url = https://github.com/gspetro-NOAA/hpc-stack.git diff --git a/hpc-stack-mod b/hpc-stack-mod new file mode 160000 index 0000000000..7888f1aecf --- /dev/null +++ b/hpc-stack-mod @@ -0,0 +1 @@ +Subproject commit 7888f1aecfb655e957dd6ce0532dfd95f330fc96 From b628dd6748d31d577e0250bd9fd66f61f862caeb Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 11 Feb 2022 14:55:58 -0500 Subject: [PATCH 003/158] fix formatting --- docs/UsersGuide/source/ConfigNewPlatform.rst | 2 +- docs/UsersGuide/source/Quickstart.rst | 2 +- docs/UsersGuide/source/SRWAppOverview.rst | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index 381ffb98cb..ce2475026a 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -213,7 +213,7 @@ Once the data has been staged, setting up your experiment on a platform without ``LAYOUT_X=2`` ``LAYOUT_Y=2`` - These are the settings that control the MPI decomposition when running the weather model. There are default values, but for your machine it is recommended that you specify your own layout to achieve the correct number of MPI processes for your application. In total, your machine should be able to handle ``LAYOUT_X×LAYOUT_Y+WRTCMP_write_tasks_per_group`` tasks. ``WRTCMP_write_tasks_per_group`` is the number of MPI tasks that will be set aside for writing model output, and it is a setting dependent on the domain you have selected. You can find and edit the value of this variable in the file ``regional_workflow/ush/set_predef_grid_params.sh``. + These are the settings that control the MPI decomposition when running the weather model. There are default values, but for your machine it is recommended that you specify your own layout to achieve the correct number of MPI processes for your application. In total, your machine should be able to handle ``LAYOUT_X×LAYOUT_Y+WRTCMP_write_tasks_per_group`` tasks. ``WRTCMP_write_tasks_per_group`` is the number of MPI tasks that will be set aside for writing model output, and it is a setting dependent on the domain you have selected. You can find and edit the value of this variable in the file ``regional_workflow/ush/set_predef_grid_params.sh``. ``RUN_CMD_UTILS="mpirun -np 4"`` This is the run command for MPI-enabled pre-processing utilities. Depending on your machine and your MPI installation, you may need to use a different command for launching an MPI-enabled executable. diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 4bcc217076..523a3f1399 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -25,7 +25,7 @@ Install the HPC-Stack .. include:: ../../../hpc-stack/docs/source/hpc-intro.rst -After completing installation, continue to the :ref:`next section <_DownloadCode>`. +After completing installation, continue to the :ref:`next section `. .. _DownloadCode: diff --git a/docs/UsersGuide/source/SRWAppOverview.rst b/docs/UsersGuide/source/SRWAppOverview.rst index 5f8cf98780..61d9c057f5 100644 --- a/docs/UsersGuide/source/SRWAppOverview.rst +++ b/docs/UsersGuide/source/SRWAppOverview.rst @@ -186,12 +186,12 @@ can be found in :numref:`Chapter %s `. +----------------------+-------------------+--------------------------------+ Case-specific Configuration -=========================== +============================= .. _DefaultConfigSection: Default configuration: ``config_defaults.sh`` --------------------------------------------- +------------------------------------------------ When generating a new experiment (described in detail in :numref:`Section %s `), the ``config_defaults.sh`` file is read first and assigns default values to the experiment parameters. Important configuration variables in the ``config_defaults.sh`` file are shown in @@ -408,7 +408,7 @@ Generating a Regional Workflow Experiment ========================================= Steps to a Generate a New Experiment ----------------------------------- +---------------------------------------- Generating an experiment requires running .. code-block:: console @@ -454,7 +454,7 @@ when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own so ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, -delete these two *.db files and then call the launch script repeatedly for each task. +delete these two ``*.db`` files and then call the launch script repeatedly for each task. .. _WorkflowTasksFig: From 467071f359093ef2c0042a13741b783d5e9a9a82 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 11 Feb 2022 15:25:20 -0500 Subject: [PATCH 004/158] added new submodule commits --- docs/UsersGuide/source/ConfigNewPlatform.rst | 3 ++- docs/UsersGuide/source/Include-HPCInstall.rst | 9 +++++---- docs/UsersGuide/source/Quickstart.rst | 2 +- hpc-stack-mod | 2 +- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index ce2475026a..798a287b29 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -212,8 +212,9 @@ Once the data has been staged, setting up your experiment on a platform without These are the two ``MACHINE`` settings for generic, non-Rocoto-based platforms; you should choose the one most appropriate for your machine. ``MACOS`` has its own setting due to some differences in how command-line utilities function on Darwin-based operating systems. ``LAYOUT_X=2`` + ``LAYOUT_Y=2`` - These are the settings that control the MPI decomposition when running the weather model. There are default values, but for your machine it is recommended that you specify your own layout to achieve the correct number of MPI processes for your application. In total, your machine should be able to handle ``LAYOUT_X×LAYOUT_Y+WRTCMP_write_tasks_per_group`` tasks. ``WRTCMP_write_tasks_per_group`` is the number of MPI tasks that will be set aside for writing model output, and it is a setting dependent on the domain you have selected. You can find and edit the value of this variable in the file ``regional_workflow/ush/set_predef_grid_params.sh``. + These are the settings that control the MPI decomposition when running the weather model. There are default values, but for your machine it is recommended that you specify your own layout to achieve the correct number of MPI processes for your application. In total, your machine should be able to handle ``LAYOUT_X×LAYOUT_Y+WRTCMP_write_tasks_per_group`` tasks. ``WRTCMP_write_tasks_per_group`` is the number of MPI tasks that will be set aside for writing model output, and it is a setting dependent on the domain you have selected. You can find and edit the value of this variable in the file ``regional_workflow/ush/set_predef_grid_params.sh``. ``RUN_CMD_UTILS="mpirun -np 4"`` This is the run command for MPI-enabled pre-processing utilities. Depending on your machine and your MPI installation, you may need to use a different command for launching an MPI-enabled executable. diff --git a/docs/UsersGuide/source/Include-HPCInstall.rst b/docs/UsersGuide/source/Include-HPCInstall.rst index 4fa2a9989b..097519db2d 100644 --- a/docs/UsersGuide/source/Include-HPCInstall.rst +++ b/docs/UsersGuide/source/Include-HPCInstall.rst @@ -1,6 +1,7 @@ .. _InstallHPCstack: -====================== -Install the HPC-Stack -====================== -.. include:: ../../../docs/source/hpc-install.rst \ No newline at end of file +.. include:: ../../../hpc-stack-mod/docs/source/hpc-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 \ No newline at end of file diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 523a3f1399..e2c935f2f0 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -22,7 +22,7 @@ Install the HPC-Stack Skip the HPC-stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion). -.. include:: ../../../hpc-stack/docs/source/hpc-intro.rst +.. include:: ../../../hpc-stack-mod/docs/source/hpc-intro.rst After completing installation, continue to the :ref:`next section `. diff --git a/hpc-stack-mod b/hpc-stack-mod index 7888f1aecf..055cab8ec5 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 7888f1aecfb655e957dd6ce0532dfd95f330fc96 +Subproject commit 055cab8ec5f7f87413e73185663215b0d151fe3e From de00e4c80bd4443998ce0beb2e863b2943e3bb61 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 11 Feb 2022 15:34:50 -0500 Subject: [PATCH 005/158] fixed ref links --- docs/UsersGuide/source/Introduction.rst | 2 +- docs/UsersGuide/source/Quickstart.rst | 2 +- hpc-stack-mod | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 363bb745c5..cd5807d4c7 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -99,7 +99,7 @@ forecast model, and post-processing steps. This SRW Application release has been tested on a variety of platforms widely used by researchers, such as the NOAA Research and Development High-Performance Computing Systems -(RDHPCS), including Hera, Orion, and Jet; NOAA’s Weather and Climate Operational +(RDHPCS), including Hera, Orion, and Jet; NOAA's Weather and Climate Operational Supercomputing System (WCOSS); the National Center for Atmospheric Research (NCAR) Cheyenne system; the National Severe Storms Laboratory (NSSL) HPC machine, called Odin; the National Science Foundation (NSF) Stampede2 system; and generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support `_have been defined for the SRW Application, including pre-configured (level 1), configurable (level 2), limited test platforms (level 3), and build only platforms (level 4). Each level is further described below. diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index e2c935f2f0..59826f5609 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -22,7 +22,7 @@ Install the HPC-Stack Skip the HPC-stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion). -.. include:: ../../../hpc-stack-mod/docs/source/hpc-intro.rst +.. include:: ../../../hpc-stack-mod/docs/source/hpc-intro-text.rst After completing installation, continue to the :ref:`next section `. diff --git a/hpc-stack-mod b/hpc-stack-mod index 055cab8ec5..b038f39569 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 055cab8ec5f7f87413e73185663215b0d151fe3e +Subproject commit b038f395699af83c533c61b24563e281ee082b28 From fb341006f6ca3d9e5365831839349cc32bc9af70 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 11 Feb 2022 17:33:43 -0500 Subject: [PATCH 006/158] finished Intro --- docs/UsersGuide/source/Components.rst | 67 +------------- docs/UsersGuide/source/Introduction.rst | 117 ++++++------------------ docs/UsersGuide/source/Quickstart.rst | 1 + 3 files changed, 30 insertions(+), 155 deletions(-) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index 26822fe341..a0bb57c447 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -10,7 +10,6 @@ The SRW Application v2.0 release assembles a variety of components, including: * Post-Processor * Visualization Example * Build System and Workflow -* User Support, Documentation, and Contributing Development These components are documented within this User's Guide and supported through a `community forum `_. @@ -97,6 +96,9 @@ The scripts are available in the `regional_workflow repository under ush/Python. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. +.. + COMMENT: only after running manage_externals/checkout_externals + Build System and Workflow ========================= @@ -152,66 +154,3 @@ the developers have built the code but little or no pre-release testing has been respectively. A complete description of the levels of support, along with a list of preconfigured and configurable platforms can be found in the `SRW Application wiki page `_. - -User Support, Documentation, and Contributing Development -========================================================= - -A forum-based, online `support system `_ organized by topic -provides a centralized location for UFS users and developers to post questions and exchange -information. - -A list of available documentation is shown in :numref:`Table %s `. - -.. _list_of_documentation: - -.. table:: Centralized list of documentation - - +----------------------------+---------------------------------------------------------------------------------+ - | **Documentation** | **Location** | - +============================+=================================================================================+ - | UFS SRW Application v1.0 | https://ufs-srweather-app.readthedocs.io/en/ufs-v1.0.0 | - | User's Guide | | - +----------------------------+---------------------------------------------------------------------------------+ - | UFS_UTILS v2.0 User's | https://noaa-emcufs-utils.readthedocs.io/en/ufs-v2.0.0/ | - | Guide | | - +----------------------------+---------------------------------------------------------------------------------+ - | UFS Weather Model v2.0 | https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0 | - | User's Guide | | - +----------------------------+---------------------------------------------------------------------------------+ - | NCEPLIBS Documentation | https://github.com/NOAA-EMC/NCEPLIBS/wiki | - +----------------------------+---------------------------------------------------------------------------------+ - | NCEPLIBS-external | https://github.com/NOAA-EMC/NCEPLIBS-external/wiki | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | FV3 Documentation | https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html | - +----------------------------+---------------------------------------------------------------------------------+ - | CCPP Scientific | https://dtcenter.ucar.edu/GMTB/v5.0.0/sci_doc/index.html | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | CCPP Technical | https://ccpp-techdoc.readthedocs.io/en/v5.0.0/ | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | ESMF manual | http://earthsystemmodeling.org/docs/release/ESMF_8_0_0/ESMF_usrdoc/ | - +----------------------------+---------------------------------------------------------------------------------+ - | Unified Post Processor | https://upp.readthedocs.io/en/upp-v9.0.0/ | - +----------------------------+---------------------------------------------------------------------------------+ - -The UFS community is encouraged to contribute to the development effort of all related -utilities, model code, and infrastructure. Issues can be posted in SRW-related GitHub repositories to report bugs or to announce upcoming contributions to the code base. For code to be accepted in the authoritative repositories, users must follow the code management rules of each component (described in the User’s Guides listed in :numref:`Table %s `. - -Future Direction -================ - -Users can expect to see incremental improvements and additional capabilities in upcoming -releases of the SRW Application to enhance research opportunities and support operational -forecast implementations. Planned advancements include: - -* A more extensive set of supported developmental physics suites. -* A larger number of pre-defined domains/resolutions and a fully supported capability to create a user-defined domain. -* Inclusion of data assimilation, cycling, and ensemble capabilities. -* A verification package (i.e., METplus) integrated into the workflow. -* Inclusion of stochastic perturbation techniques. - -In addition to the above list, other improvements will be addressed in future releases. - -.. bibliography:: references.bib diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index cd5807d4c7..ae50c60ef1 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -13,13 +13,24 @@ conducted with the App: UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994 -.. - COMMENT: What will be the numbering for this release? It will need to be changed above and throughout the docs. - COMMENT: Can this app be used beyond the CONUS? Change "limited spatial domain" above to CONUS or something more specific. - COMMENT: Where are we on the DA and verification package? Can we update that line? - COMMENT: Update citation date & version number. What is Zenodo? - COMMENT: Disagree: "This documentation provides... information on where to find more information and obtain support." We need to add this (i.e. link in the docs) or remove the line. - COMMENT: "Components" doc created but not added to TOC. Contains more detailed info on components discussed here below. +How to Use This Document +======================== + +This guide instructs both novice and experienced users on downloading, building, and running the SRW Application. Please post questions in the UFS forum at https://forums.ufscommunity.org/. + +.. code-block:: console + + Throughout the guide, this presentation style indicates shell commands and options, code examples, etc. + +.. note:: + + Variables presented as ``AaBbCc123`` in this document typically refer to variables + in scripts, names of files, and directories. + +.. note:: + + File paths or code that include angle brackets (e.g., ``env/build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``env/build_aws_gcc.env``). + Pre-processor Utilities and Initial Conditions ============================================== @@ -28,12 +39,6 @@ The SRW Application includes a number of pre-processing utilities that initializ model. Tasks include generating a regional grid, along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. -.. - COMMENT: "Integration" with what?!?! (1st sentence) --> Try "prepare the model data" instead of "prepare the model for integration." - COMMENT: Deleted code/commands bc it's an introduction. - COMMENT: What is a "halo shave point" or wide-halo grid?! - - Forecast Model ============== @@ -64,71 +69,21 @@ The Unified Post Processor (:term:`UPP`) is included in the SRW Application work Visualization Example ===================== -This SRW Application distribution provides Python scripts to create basic visualization of the model output. The scripts are available in the ```regional_workflow`` repository -`_ -under ``ush/Python``. Usage information and instructions are described in -:numref:`Chapter %s ` and are also included at the top of the script. + +This SRW Application distribution provides Python scripts to create basic visualizations of the model output. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. Build System and Workflow ========================= -The SRW Application has a portable build system and a user-friendly, modular, and -expandable workflow framework. - -.. - COMMENT: Define build system and workflow... - -An umbrella CMake-based build system is used for building the components necessary -for running the end-to-end SRW Application: the UFS Weather Model and the pre- and -post-processing software. Additional libraries (:term:`NCEPLIBS-external` and :term:`NCEPLIBS`) necessary -for the application are not included in the SRW Application build system, but are available -pre-built on pre-configured platforms. 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 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 (see `Rocoto documentation -`_) in the proper sequence. -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 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, whether to run some or all of the pre-processing, -forecast model, and post-processing steps. - -This SRW Application release has been tested on a variety of platforms widely used by -researchers, such as the NOAA Research and Development High-Performance Computing Systems -(RDHPCS), including Hera, Orion, and Jet; NOAA's Weather and Climate Operational -Supercomputing System (WCOSS); the National Center for Atmospheric Research (NCAR) Cheyenne -system; the National Severe Storms Laboratory (NSSL) HPC machine, called Odin; the National Science Foundation (NSF) Stampede2 system; and generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support `_have been defined for the SRW Application, including pre-configured (level 1), configurable (level 2), limited test platforms (level 3), and build only platforms (level 4). Each level is further described below. - -For the selected computational platforms that have been pre-configured (level 1), all the -required libraries for building the SRW Application are available in a central place. That -means bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) have both -been built. The SRW Application is expected to build and run out of the box on these -pre-configured platforms and users can proceed directly to the using the workflow, as -described in the Quick Start (:numref:`Chapter %s `). - -A few additional computational platforms are considered configurable for the SRW -Application release. Configurable platforms (level 2) are platforms where all of -the required libraries for building the SRW Application are expected to install successfully, -but are not available in a central place. Applications and models are expected to build -and run once the required bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) -are built. - -Limited-Test (level 3) and Build-Only (level 4) computational platforms are those in which -the developers have built the code but little or no pre-release testing has been conducted, -respectively. A complete description of the levels of support, along with a list of preconfigured -and configurable platforms can be found in the `SRW Application wiki page -`_. +The SRW Application has a portable CMake-based build system that packages together all the components required to build the SRW Application. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see `Rocoto documentation `_). Individual components can also be run in a stand-alone, command line fashion. The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. + +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Comuting (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can proceed directly to using the workflow, as +described in the Quick Start Guide (:numref:`Section %s <_GenerateForecast>`). On other platforms, the required libraries will need to be installed via the HPC-Stack. Once these libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. User Support, Documentation, and Contributing Development ========================================================= -A forum-based, online `support system `_ organized by topic -provides a centralized location for UFS users and developers to post questions and exchange -information. +A forum-based, online `support system `_ organized by topic provides a centralized location for UFS users and developers to post questions and exchange information. A list of available documentation is shown in :numref:`Table %s `. @@ -167,7 +122,7 @@ A list of available documentation is shown in :numref:`Table %s `. +utilities, model code, and infrastructure. Issues can be posted in the related GitHub repositories to report bugs or to announce upcoming contributions to the code base. For code to be accepted in the authoritative repositories, users must follow the code management rules of each component (described in the User’s Guides listed in :numref:`Table %s `. Future Direction ================ @@ -184,26 +139,6 @@ forecast implementations. Planned advancements include: In addition to the above list, other improvements will be addressed in future releases. -.. - COMMENT: How is a domain different from a grid? Can we say "user-defined grid," for example? Might be clearer. - -How to Use This Document -======================== - -This guide instructs both novice and experienced users on downloading, -building and running the SRW Application. Please post questions in the -UFS forum at https://forums.ufscommunity.org/. - -.. code-block:: console - - Throughout the guide, this presentation style indicates shell - commands and options, code examples, etc. - - -.. note:: - - Variables presented as ``AaBbCc123`` in this document typically refer to variables - in scripts, names of files and directories. .. bibliography:: references.bib diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 59826f5609..e6e37c8c1a 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -152,6 +152,7 @@ The SRW requires input files to run. These include static datasets, initial and files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :doc:`Input and Output Files `, Section 3. Section 1 contains useful background information on the input files required by the SRW. +.. _GenerateForecast: Generate the Forecast Experiment ================================= From 701f9e9f2765d465d78d2647320d20ac9ac64864 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 14 Feb 2022 13:47:35 -0500 Subject: [PATCH 007/158] finish Components & Intro edits --- docs/UsersGuide/source/Components.rst | 121 ++++++------------------ docs/UsersGuide/source/Glossary.rst | 21 ++-- docs/UsersGuide/source/Introduction.rst | 7 +- 3 files changed, 42 insertions(+), 107 deletions(-) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index a0bb57c447..cf5180ba40 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -18,66 +18,37 @@ Pre-processor Utilities and Initial Conditions ============================================== The SRW Application includes a number of pre-processing utilities that initialize and prepare the -model. Tasks include generating a regional grid, along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. - -The SRW Application includes a number of pre-processing utilities to initialize and prepare the -model. For the limited area model (LAM), it is necessary to first generate a -regional grid ``regional_esg_grid/make_hgrid`` along with orography ``orog`` and surface climatology ``sfc_climo_gen`` files on that grid. There are additional utilities included to handle the correct number of halo ``shave`` points and topography filtering ``filter_topo``. The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format, needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. - -.. - COMMENT: "Integration" with what?!?! (1st sentence) --> Try "prepare the model data" instead of "prepare the model for integration." - COMMENT: Why are we using code/commands in an overview doc?! A newbie is going to glaze over and give up. +model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid ``regional_esg_grid/make_hgrid`` along with orography ``orog`` and surface climatology ``sfc_climo_gen`` files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of halo cells, additional utilities handle the correct number of halo shave points and topography filtering. The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format, needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. The SRW Application can be initialized from a range of operational initial condition files. It is -possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (GRIB2) format and GFS in NEMSIO format for past dates. +possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (:term:`GRIB2`) format. GFS files also come in :term:`NEMSIO` format for past dates. .. WARNING:: - Please note, for GFS data, dates prior to 1 January 2018 may work but are not guaranteed. Public archives of model data can be accessed through the `National Centers for Environmental Information `_ (NCEI) or through the `NOAA Operational Model Archive and Distribution System `_ (NOMADS). Raw external model data may be pre-staged on disk by the user. + For GFS data, dates prior to 1 January 2018 may work but are not guaranteed. Public archives of model data can be accessed through the `National Centers for Environmental Information `_ (NCEI) or through the `NOAA Operational Model Archive and Distribution System `_ (NOMADS). Raw external model data may be pre-staged on disk by the user. Forecast Model ============== The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability :cite:`BlackEtAl2020`. -The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `_. - -Supported model resolutions in this release include a 3-, 13-, and 25-km predefined Contiguous -U.S. (CONUS) domain, all with 64 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 `here -`_ and on the `NOAA Geophysical -Fluid Dynamics Laboratory website `_. - -Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) -Land Surface Model options, are supported through the Common Community Physics Package -(:term:`CCPP`; described `here `_). -Atmospheric physics are a set of numerical methods describing small-scale processes such -as clouds, turbulence, radiation, and their interactions. There are two physics options -supported for the release. The first is an experimental physics suite 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) v15. 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 +(:term:`FV3`) dynamical core configured with a Limited Area Model (:term:`LAM`) capability :cite:`BlackEtAl2020`. The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `_. + +Supported model resolutions in this release include 3-, 13-, and 25-km predefined Contiguous U.S. (:term:`CONUS`) domains, each with 64 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 `here `_ and on the `NOAA Geophysical Fluid Dynamics Laboratory website `_. + +Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) Land Surface Model options, are supported through the Common Community Physics Package (:term:`CCPP`; described `here `_).Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are two physics options supported for the release. The first is an experimental physics suite 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) v15. 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. -The SRW App supports the use of both GRIB2 and :term:`NEMSIO` input data. The UFS Weather Model +The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in -netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal and model -levels in the vertical. +netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal direction and model levels in the vertical direction. Post-processor ============== The SRW Application is distributed with the Unified Post Processor (:term:`UPP`) included in the -workflow as a way to convert the netCDF output on the native model grid to GRIB2 format on +workflow as a way to convert the netCDF output on the native model grid to :term:`GRIB2` format on standard isobaric vertical coordinates. UPP can also be used to compute a variety of useful -diagnostic fields, as described in the `UPP user’s guide `_. +diagnostic fields, as described in the `UPP User’s Guide `_. Output from UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing, e.g. statistical post-processing techniques. @@ -86,18 +57,12 @@ Visualization Example ===================== A Python script is provided to create basic visualization of the model output. The script is designed to output graphics in PNG format for 14 standard meteorological variables -when using the pre-defined CONUS domain. In addition, a difference plotting script is included +when using the pre-defined :term:`CONUS` domain. In addition, a difference plotting script is included to visually compare two runs for the same domain and resolution. These scripts are provided only -as an example for users familiar with Python, and may be used to do a visual check to verify +as an example for users familiar with Python and may be used to do a visual check to verify that the application is producing reasonable results. -The scripts are available in the `regional_workflow repository -`_ -under ush/Python. Usage information and instructions are described in -:numref:`Chapter %s ` and are also included at the top of the script. - -.. - COMMENT: only after running manage_externals/checkout_externals +After running ``manage_externals/checkout_externals``, the visualization scripts will be available in the `regional_workflow repository `_ under ush/Python. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. Build System and Workflow ========================= @@ -105,52 +70,28 @@ 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: the UFS Weather Model and the pre- and -post-processing software. Additional libraries (:term:`NCEPLIBS-external` and :term:`NCEPLIBS`) necessary -for the application are not included in the SRW Application build system, but are available -pre-built on pre-configured platforms. 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 MPI library. +An umbrella CMake-based build system is used for building the components necessary for running the end-to-end SRW Application: 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. 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 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 (see `Rocoto documentation -`_) in the proper sequence. -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 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, whether to run some or all of the pre-processing, -forecast model, and post-processing steps. +workflow file that will run each task in the system in the proper sequence (see `Rocoto documentation +`_). 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, whether to run some or all of the pre-processing, forecast model, and post-processing steps. This SRW Application release has been tested on a variety of platforms widely used by researchers, such as the NOAA Research and Development High-Performance Computing Systems (RDHPCS), including Hera, Orion, and Jet; NOAA’s Weather and Climate Operational Supercomputing System (WCOSS); the National Center for Atmospheric Research (NCAR) Cheyenne -system; NSSL’s HPC machine, Odin; the National Science Foundation Stampede2 system; and -generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support -`_ -have been defined for the SRW Application, including pre-configured (level 1), configurable -(level 2), limited test platforms (level 3), and build only platforms (level 4). Each -level is further described below. - -For the selected computational platforms that have been pre-configured (level 1), all the +system; the National Severe Storms Laboratory (NSSL) HPC machine called Odin; the National Science Foundation Stampede2 system; and generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build only platforms (Level 4). Each level is further described below. + +For the selected computational platforms that have been pre-configured (Level 1), all the required libraries for building the SRW Application are available in a central place. That means bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) have both -been built. The SRW Application is expected to build and run out of the box on these -pre-configured platforms and users can proceed directly to the using the workflow, as -described in the Quick Start (:numref:`Chapter %s `). - -A few additional computational platforms are considered configurable for the SRW -Application release. Configurable platforms (level 2) are platforms where all of -the required libraries for building the SRW Application are expected to install successfully, -but are not available in a central place. Applications and models are expected to build -and run once the required bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) -are built. - -Limited-Test (level 3) and Build-Only (level 4) computational platforms are those in which -the developers have built the code but little or no pre-release testing has been conducted, -respectively. A complete description of the levels of support, along with a list of preconfigured -and configurable platforms can be found in the `SRW Application wiki page -`_. +been built. The SRW Application is expected to build and run out-of-the-box on these +pre-configured platforms, and users can proceed directly to the using the workflow, as +described in the Quick Start (:numref:`Section %s `). + +A few additional computational platforms are considered configurable for the SRW Application release. Configurable platforms (Level 2) are platforms where all of the required libraries for building the SRW Application are expected to install successfully but are not available in a central location. Applications and models are expected to build and run once the required bundled libraries (e.g., NCEPLIBS) and third-party libraries (e.g., NCEPLIBS-external) are built. + +Limited-Test (Level 3) and Build-Only (Level 4) computational platforms are those in which the developers have built the code but little or no pre-release testing has been conducted, respectively. A complete description of the levels of support, along with a list of preconfigured and configurable platforms can be found in the `SRW Application wiki page `_. + +.. bibliography:: references.bib \ No newline at end of file diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index d3deb40672..856692c801 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -7,9 +7,7 @@ Glossary .. glossary:: CCPP - A forecast-model agnostic, vetted collection of codes containing atmospheric physical - parameterizations and suites of parameterizations for use in Numerical Weather Prediction - (NWP) along with a framework that connects the physics to the host forecast model. + `Common Community Physics Package `_. A forecast-model agnostic, vetted collection of codes containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model. CONUS Continental United States @@ -18,12 +16,6 @@ Glossary The preprocessing software used to create initial and boundary condition files to “coldstart” the forecast model. - 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. - - .. - COMMENT: Clarify HRRR definition! - FV3 The Finite-Volume Cubed-Sphere dynamical core (dycore). Developed at NOAA's Geophysical Fluid Dynamics Laboratory (GFDL), it is a scalable and flexible dycore capable of both @@ -36,24 +28,27 @@ Glossary GRIB2 The second version of the World Meterological Organization's (WMO) standard for distributing gridded data. + 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. + NAM `North American Mesoscale Forecast System `_. NAM generates multiple grids (or domains) of weather forecasts over the North American continent at various horizontal resolutions. Each grid contains data for dozens of weather parameters, including temperature, precipitation, lightning, and turbulent kinetic energy. NAM uses additional numerical weather models to generate high-resolution forecasts over fixed regions, and occasionally to follow significant weather events like hurricanes. NCEP National Centers for Environmental Prediction, an arm of the National Weather Service, - consisting of nine centers. More information can be found at https://www.ncep.noaa.gov. + consisting of nine centers. More information can be found at https://www.ncep.noaa.gov. NCEPLIBS The software libraries created and maintained by :term:`NCEP` that are required for running - :term:`chgres_cube`, the UFS Weather Model, and :term:`UPP`. + :term:`chgres_cube`, the UFS Weather Model, and :term:`UPP`. They are part of the HPC-Stack. NCEPLIBS-external A collection of third-party libraries required to build :term:`NCEPLIBS`, :term:`chgres_cube`, - the UFS Weather Model, and :term:`UPP`. + the UFS Weather Model, and :term:`UPP`. They are part of the HPC-Stack. NCL An interpreted programming language designed specifically for scientific data analysis and - visualization. More information can be found at https://www.ncl.ucar.edu. + visualization. Stands for NCAR Command Language. More information can be found at https://www.ncl.ucar.edu. NEMS The NOAA Environmental Modeling System is a common modeling framework whose purpose is diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index ae50c60ef1..1c834e47f4 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -6,7 +6,7 @@ Introduction The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the UFS Portal at https://ufscommunity.org/. -The UFS can be configured for multiple applications (see a complete list at https://ufscommunity.org/science/aboutapps/). The configuration described here is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v1.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g. METplus). This documentation provides a quick start guide for running the application, in addition to an overview of the release components, a description of the supported capabilities, and information on where to find more information and obtain support. +The UFS can be configured for multiple applications (see a complete list at https://ufscommunity.org/science/aboutapps/). The configuration described here is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g. METplus). This documentation provides a quick start guide for running the application, in addition to an overview of the release components, a description of the supported capabilities, and information on where to find more information and obtain support. The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research conducted with the App: @@ -64,7 +64,7 @@ ingests initial and lateral boundary condition files produced by :term:`chgres_c Post-processor ============== -The Unified Post Processor (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF output on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP user’s guide `_. Output from UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing, e.g. statistical post-processing techniques. +The Unified Post Processor (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF output on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing, e.g. statistical post-processing techniques. Visualization Example @@ -122,7 +122,7 @@ A list of available documentation is shown in :numref:`Table %s `. +utilities, model code, and infrastructure. Users can post issues in the related GitHub repositories to report bugs or to announce upcoming contributions to the code base. For code to be accepted in the authoritative repositories, users must follow the code management rules of each component (described in the User’s Guides listed in :numref:`Table %s `. Future Direction ================ @@ -139,7 +139,6 @@ forecast implementations. Planned advancements include: In addition to the above list, other improvements will be addressed in future releases. - .. bibliography:: references.bib From cab1c6f12ca855442af3135c24bf7d05416200e1 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 14 Feb 2022 17:16:13 -0500 Subject: [PATCH 008/158] edited Rocoto workflow section of Quickstart --- docs/UsersGuide/source/Quickstart.rst | 50 +++++++++++++++++++-------- 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index e6e37c8c1a..a214e52cb8 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -95,7 +95,7 @@ Set up the Build Environment Container Approach -------------------- -If the SRW Application has been built in an EPIC-provided Singularity container, set build environments and modules within the `ufs-srweather-app` directory as follows: +If the SRW Application has been built in a container provided by the Earth Prediction Innovation Center (EPIC), set build environments and modules within the `ufs-srweather-app` directory as follows: .. code-block:: console @@ -178,7 +178,7 @@ Make a copy of ``config.community.sh`` to get started (under `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. - + Minimum parameter settings for Level 1 machines: For Cheyenne: @@ -260,25 +260,31 @@ For all platforms, the workflow can then be generated from the ``ush`` directory ./generate_FV3LAM_wflow.sh -The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. A log file called ``log.generate_FV3LAM_wflow`` is generated by this step and can also be found in ``$EXPTDIR``. The settings for these paths can be found in the output from the ``./generate_FV3LAM_wflow.sh`` script. +This script creates an experiment directory and populates it will all the data needed to run through the workflow. The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. A log file called ``log.generate_FV3LAM_wflow`` is generated by this step and can also be found in ``$EXPTDIR``. The settings for these paths can be found in the output from the ``./generate_FV3LAM_wflow.sh`` script. + +The last line of output, which starts with ``*/1 * * * * ``, can be saved and used later to automatically run portions of the workflow. The ``1`` could be any number and simply refers to the frequency of the reruns. + Run the Workflow Using Rocoto ============================= The information in this section assumes that Rocoto is available on the desired platform. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two ways you can run the workflow with Rocoto using either the ``./launch_FV3LAM_wflow.sh`` or by hand. -An environment variable may be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: +An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: .. code-block:: console - export EXPTDIR=/path-to-experiment/directory + export EXPTDIR=// Or if the login shell is csh/tcsh, it can be set using: .. code-block:: console - setenv EXPTDIR /path-to-experiment/directory + setenv EXPTDIR // -To run Rocoto using the script: +Launch the Rocoto Workflow Using a Script +----------------------------------------------- + +To run Rocoto using the script provided: .. code-block:: console @@ -287,9 +293,10 @@ To run Rocoto using the script: Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named ``log.launch_FV3LAM_wflow`` will be created (or appended to it if it already exists) in ``EXPTDIR``. -Or to manually call Rocoto: +Launch the Rocoto Workflow Manually +--------------------------------------- -First load the Rocoto module, depending on the platform used. +Instead of running the ``./launch_FV3LAM_wflow.sh`` script, users can manually load Rocoto and any other required modules. The commands for specific Level 1 platforms are described here: For Cheyenne: @@ -337,8 +344,18 @@ For WCOSS_CRAY: module use -a /usrx/local/emc_rocoto/modulefiles module load rocoto/1.2.4 -Then manually call ``rocotorun`` to launch the tasks that have all dependencies satisfied -and ``rocotostat`` to monitor the progress: +For other systems, a variant on the following commands will be necessary: + +.. code-block:: console + + module use + module load rocoto + + +Run the Rocoto Workflow +--------------------------- + +After loading Rocoto, call ``rocotorun`` from the experiment directory to launch the workflow tasks. As the workflow progresses through its stages, ``rocotostat`` will show the state of the process and allow users to monitor progress: .. code-block:: console @@ -346,12 +363,15 @@ and ``rocotostat`` to monitor the progress: rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -For automatic resubmission of the workflow (e.g., every 3 minutes), the following line can be added -to the user's crontab (use ``crontab -e`` to edit the cron table). +Additional Options +---------------------- +For automatic resubmission of the workflow at regular intervals (e.g., every 3 minutes), the user can add a chrontab entry by entering the ``crontab -e`` command. The last line of output from the ``./generate_FV3LAM_wflow.sh``, which starts with ``*/1 * * * * ``, can be pasted into the crontab at this point. Alternatively, if users preferred to use the ``./launch_FV3LAM_wflow.sh`` to run the workflow, they can past the following command into the crontab: .. code-block:: console - */3 * * * * cd /glade/p/ral/jntp/$USER/expt_dirs/test_CONUS_25km_GFSv15p2 && ./launch_FV3LAM_wflow.sh + */3 * * * * cd && ./launch_FV3LAM_wflow.sh + +The number 3 can be changed to resubmit the workflow more or less frequently. .. note:: From 290364ec37ade1f004ca01badbc498e7d3b9b9b6 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 15 Feb 2022 11:42:11 -0500 Subject: [PATCH 009/158] added minor hpc submodule commits --- docs/UsersGuide/source/Quickstart.rst | 6 +++--- hpc-stack-mod | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index a214e52cb8..0f60ba8638 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -348,7 +348,7 @@ For other systems, a variant on the following commands will be necessary: .. code-block:: console - module use + module use module load rocoto @@ -365,13 +365,13 @@ After loading Rocoto, call ``rocotorun`` from the experiment directory to launch Additional Options ---------------------- -For automatic resubmission of the workflow at regular intervals (e.g., every 3 minutes), the user can add a chrontab entry by entering the ``crontab -e`` command. The last line of output from the ``./generate_FV3LAM_wflow.sh``, which starts with ``*/1 * * * * ``, can be pasted into the crontab at this point. Alternatively, if users preferred to use the ``./launch_FV3LAM_wflow.sh`` to run the workflow, they can past the following command into the crontab: +For automatic resubmission of the workflow at regular intervals (e.g., every 3 minutes), the user can add a chrontab entry by entering the ``crontab -e`` command. This opens a crontab file. The last line of output from the ``./generate_FV3LAM_wflow.sh``, which starts with ``*/1 * * * * ``, can be pasted into the crontab file at this point. Alternatively, if users preferred to use the ``./launch_FV3LAM_wflow.sh`` to run the workflow, they can paste the following command into the crontab: .. code-block:: console */3 * * * * cd && ./launch_FV3LAM_wflow.sh -The number 3 can be changed to resubmit the workflow more or less frequently. +The number ``3`` can be changed to resubmit the workflow more or less frequently. .. note:: diff --git a/hpc-stack-mod b/hpc-stack-mod index b038f39569..9002252d5a 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit b038f395699af83c533c61b24563e281ee082b28 +Subproject commit 9002252d5a39f69ff084ad2e969862557281bef3 From 80291a1b232f9827a726538f6f2566b55a72cb01 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 15 Feb 2022 19:49:42 -0500 Subject: [PATCH 010/158] Updates to Rocoto Workflow in Quick Start --- docs/UsersGuide/source/Glossary.rst | 2 +- docs/UsersGuide/source/Quickstart.rst | 158 +++++++++++++++----------- docs/UsersGuide/source/conf.py | 1 + 3 files changed, 91 insertions(+), 70 deletions(-) diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 856692c801..4432edc884 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -7,7 +7,7 @@ Glossary .. glossary:: CCPP - `Common Community Physics Package `_. A forecast-model agnostic, vetted collection of codes containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model. + The `Common Community Physics Package `_ is a forecast-model agnostic, vetted collection of codes containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model. CONUS Continental United States diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 0f60ba8638..00dfeb1278 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -4,13 +4,11 @@ Workflow Quick Start ==================== - - -This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (UFS) Short-Range Weather (SRW) Application. The "out-of-the-box" case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (CONUS) grid (RRFS_CONUS_25km), the Global Forecast System (GFS) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and FV3-based GFS raw external model data for initialization. +This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application. The "out-of-the-box" case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. .. note:: - The steps described in this chapter are most applicable to preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems as well but may require additional troubleshooting by the user. The various platform levels are listed `here `_. + The UFS defines `four platform levels `_. The steps described in this chapter are most applicable to preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems as well but may require additional troubleshooting by the user. .. _HPCstackInfo: @@ -32,7 +30,7 @@ After completing installation, continue to the :ref:`next section Download the UFS SRW Application Code ===================================== -The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under your ``regional_workflow`` and ``src`` directories. +The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. Run the UFS SRW in a Singularity Container ------------------------------------------- @@ -63,6 +61,9 @@ Clone the develop branch of the UFS-SRW weather application repository: git clone https://github.com/jkbk2004/ufs-srweather-app +.. + COMMENT: This will need to be changed to release branch of the SRW repo once it exists. + Check out submodules for the SRW Application: .. code-block:: console @@ -80,7 +81,10 @@ Clone the release branch of the repository: git clone -b ufs-v1.0.0 https://github.com/ufs-community/ufs-srweather-app.git -Then, check out the submodules for the SRW Application: +.. + COMMENT: This will need to be changed to the updated release branch of the SRW repo once it exists. + +Then, run the executable that pulls in the submodules for the SRW Application: .. code-block:: console @@ -180,7 +184,14 @@ Make a copy of ``config.community.sh`` to get started (under `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in the section on :doc:`Limited Area Model (LAM) Grids `. @@ -190,50 +201,30 @@ Sample settings are indicated below for Level 1 platforms. Detailed guidance app Minimum parameter settings for Level 1 machines: -For Cheyenne: +**Cheyenne:** .. code-block:: console MACHINE="cheyenne" - ACCOUNT="my_account" - EXPT_SUBDIR="my_expt_name" + ACCOUNT="" + EXPT_SUBDIR="" USE_USER_STAGED_EXTRN_FILES="TRUE" EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_app/model_data/FV3GFS" EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_app/model_data/FV3GFS" -For Hera: +**Hera:** .. code-block:: console MACHINE="hera" - ACCOUNT="my_account" - EXPT_SUBDIR="my_expt_name" - -For Jet: - -.. code-block:: console - - MACHINE="jet" - ACCOUNT="my_account" - EXPT_SUBDIR="my_expt_name" - -For Orion: - -.. code-block:: console - - MACHINE="orion" - ACCOUNT="my_account" - EXPT_SUBDIR="my_expt_name" - -For Gaea: + ACCOUNT="" + EXPT_SUBDIR="" -.. code-block:: console +**Jet, Orion, Gaea:** - MACHINE="gaea" - ACCOUNT="my_account" - EXPT_SUBDIR="my_expt_name" +The settings are the same as for Hera, except that ``"hera"`` should be switched to ``"jet"``, ``"orion"``, or ``"gaea"``, respectively. -For WCOSS, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: +For **WCOSS**, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: .. code-block:: console @@ -241,33 +232,37 @@ For WCOSS, edit ``config.sh`` with these WCOSS-specific parameters, and use a va ACCOUNT="my_account" EXPT_SUBDIR="my_expt_name" + .. _SetUpPythonEnv: Set up the Python and other Environment Parameters -------------------------------------------------- -Next, it is necessary to load the appropriate Python environment for the workflow. The workflow requires Python 3, with the packages 'PyYAML', 'Jinja2', and 'f90nml' available. This Python environment has already been set up on Level 1 platforms, and it can be activated in the following way (from ``/ufs-srweather-app/regional_workflow/ush``): +Next, load the appropriate Python environment for the workflow. The workflow requires Python 3, with the packages 'PyYAML', 'Jinja2', and 'f90nml' available. This Python environment has already been set up on Level 1 platforms, and it can be activated in the following way (from ``/ufs-srweather-app/regional_workflow/ush``): .. code-block:: console source ../../env/wflow_.env -Run the ``generate_FV3LAM_wflow.sh`` script +.. _GenerateWorkflow:: + +Generate the Regional Workflow ------------------------------------------- -For all platforms, the workflow can then be generated from the ``ush`` directory with the command: +First, activate the regional workflow from the ``ush`` directory: .. code-block:: console - ./generate_FV3LAM_wflow.sh + conda activate regional_workflow -This script creates an experiment directory and populates it will all the data needed to run through the workflow. The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. A log file called ``log.generate_FV3LAM_wflow`` is generated by this step and can also be found in ``$EXPTDIR``. The settings for these paths can be found in the output from the ``./generate_FV3LAM_wflow.sh`` script. +Then, run the following command to generate the workflow: + +.. code-block:: console -The last line of output, which starts with ``*/1 * * * * ``, can be saved and used later to automatically run portions of the workflow. The ``1`` could be any number and simply refers to the frequency of the reruns. + ./generate_FV3LAM_wflow.sh +The last line of output from this script, starting with ``*/1 * * * * ``, can be saved and `used later ` to automatically run portions of the workflow. -Run the Workflow Using Rocoto -============================= -The information in this section assumes that Rocoto is available on the desired platform. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two ways you can run the workflow with Rocoto using either the ``./launch_FV3LAM_wflow.sh`` or by hand. +This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in `Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in $EXPTDIR. An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: @@ -275,11 +270,12 @@ An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. export EXPTDIR=// -Or if the login shell is csh/tcsh, it can be set using: +If the login shell is csh/tcsh, replace ``export`` with ``setenv`` in the command above. -.. code-block:: console - setenv EXPTDIR // +Run the Workflow Using Rocoto +============================= +The information in this section assumes that Rocoto is available on the desired platform. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: using the ``./launch_FV3LAM_wflow.sh`` or by hand. Launch the Rocoto Workflow Using a Script ----------------------------------------------- @@ -291,42 +287,60 @@ To run Rocoto using the script provided: cd $EXPTDIR ./launch_FV3LAM_wflow.sh -Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named ``log.launch_FV3LAM_wflow`` will be created (or appended to it if it already exists) in ``EXPTDIR``. +Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named ``log.launch_FV3LAM_wflow`` will be created (or appended) in the ``EXPTDIR``. Check the end of the log file periodically to see how the experiment is progressing: + +.. code-block:: console + + cd $EXPTDIR + vi ``log.launch_FV3LAM_wflow`` + Launch the Rocoto Workflow Manually --------------------------------------- -Instead of running the ``./launch_FV3LAM_wflow.sh`` script, users can manually load Rocoto and any other required modules. The commands for specific Level 1 platforms are described here: +Load Rocoto +^^^^^^^^^^^^^^^^ + +Instead of running the ``./launch_FV3LAM_wflow.sh`` script, users can manually load Rocoto and any other required modules. This gives the user more control over the process and allows them to view experiment progress more easily. + +For most systems, a variant on the following commands will be necessary to load the Rocoto module: + +.. code-block:: console + + module use + module load rocoto -For Cheyenne: +The commands for specific Level 1 platforms are described here: + +Cheyenne: .. code-block:: console module use -a /glade/p/ral/jntp/UFS_SRW_app/modules/ module load rocoto -For Hera or Jet: +Hera and Jet: .. code-block:: console module purge module load rocoto -For Orion: +Orion: .. code-block:: console module purge module load contrib rocoto -For Gaea: +Gaea: .. code-block:: console module use /lustre/f2/pdata/esrl/gsd/contrib/modulefiles module load rocoto/1.3.3 -For WCOSS_DELL_P3: +WCOSS_DELL_P3: .. code-block:: console @@ -335,7 +349,7 @@ For WCOSS_DELL_P3: module use /gpfs/dell3/usrx/local/dev/emc_rocoto/modulefiles/ module load ruby/2.5.1 rocoto/1.2.4 -For WCOSS_CRAY: +WCOSS_CRAY: .. code-block:: console @@ -344,18 +358,11 @@ For WCOSS_CRAY: module use -a /usrx/local/emc_rocoto/modulefiles module load rocoto/1.2.4 -For other systems, a variant on the following commands will be necessary: - -.. code-block:: console - - module use - module load rocoto - Run the Rocoto Workflow ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ -After loading Rocoto, call ``rocotorun`` from the experiment directory to launch the workflow tasks. As the workflow progresses through its stages, ``rocotostat`` will show the state of the process and allow users to monitor progress: +After loading Rocoto, call ``rocotorun`` from the experiment directory to launch the workflow tasks. This will start any tasks that do not have a dependency. As the workflow progresses through its stages, ``rocotostat`` will show the state of each task and allow users to monitor progress: .. code-block:: console @@ -363,19 +370,32 @@ After loading Rocoto, call ``rocotorun`` from the experiment directory to launch rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 +The ``rocotorun`` and ``rocotostat`` commands will need to be resubmitted regularly and repeatedlyuntil the experiment is finished. In part, this is to avoid having the system time out. This also ensures that when one task ends, tasks dependent on it will run as soon as possible, and ``rocotostat`` will capture the new progress. + +If the experiment fails, the ``rocotostat`` command will indicate which task failed. Users can look at the log file in the ``log`` subdirectory for the failed task to determine what caused the failure. For example, if the ``make_grid`` task failed: + +.. code-block:: console + + cd $EXPTDIR/log + vi make_grid.log + +If users have the `Slurm workload manager `_ on their system, they can run the ``squeue`` command in lieu of ``rocotostat`` to check what jobs are currently running. + +.. _AdditionalOptions:: + Additional Options ---------------------- -For automatic resubmission of the workflow at regular intervals (e.g., every 3 minutes), the user can add a chrontab entry by entering the ``crontab -e`` command. This opens a crontab file. The last line of output from the ``./generate_FV3LAM_wflow.sh``, which starts with ``*/1 * * * * ``, can be pasted into the crontab file at this point. Alternatively, if users preferred to use the ``./launch_FV3LAM_wflow.sh`` to run the workflow, they can paste the following command into the crontab: +For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry by entering the ``crontab -e`` command, which opens a crontab file. As mentioned in `Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * * ``), can be pasted into the crontab file. It can also be found in the``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: .. code-block:: console - */3 * * * * cd && ./launch_FV3LAM_wflow.sh + */1 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -The number ``3`` can be changed to resubmit the workflow more or less frequently. +where is changed to correspond to the user's machine, and "/apps/rocoto/1.3.3/bin/rocotorun" corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can also be changed and simply means that the workflow will be resubmitted every minute. .. note:: - Currently cron is only available on the orion-login-1 node, so please use that node. + On Orion, cron is only available on the orion-login-1 node, so please use that node when running cron jobs on Orion. The workflow run is completed when all tasks have “SUCCEEDED”, and the rocotostat command will output the following: diff --git a/docs/UsersGuide/source/conf.py b/docs/UsersGuide/source/conf.py index 8e43ea2c75..3d7e48c137 100644 --- a/docs/UsersGuide/source/conf.py +++ b/docs/UsersGuide/source/conf.py @@ -56,6 +56,7 @@ ] bibtex_bibfiles = ['references.bib'] +#bibtex_bibfiles = ['refs.bib'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] From ab97b749d009ee7eb8571a4b4f24ddf6d340ea2f Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 16 Feb 2022 16:59:15 -0500 Subject: [PATCH 011/158] add to HPC-stack intro --- docs/UsersGuide/source/Quickstart.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 00dfeb1278..4e08b02cf7 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -19,6 +19,7 @@ Install the HPC-Stack .. note:: Skip the HPC-stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion). +The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF etc) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `_ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW. .. include:: ../../../hpc-stack-mod/docs/source/hpc-intro-text.rst @@ -370,7 +371,7 @@ After loading Rocoto, call ``rocotorun`` from the experiment directory to launch rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -The ``rocotorun`` and ``rocotostat`` commands will need to be resubmitted regularly and repeatedlyuntil the experiment is finished. In part, this is to avoid having the system time out. This also ensures that when one task ends, tasks dependent on it will run as soon as possible, and ``rocotostat`` will capture the new progress. +The ``rocotorun`` and ``rocotostat`` commands will need to be resubmitted regularly and repeatedly until the experiment is finished. In part, this is to avoid having the system time out. This also ensures that when one task ends, tasks dependent on it will run as soon as possible, and ``rocotostat`` will capture the new progress. If the experiment fails, the ``rocotostat`` command will indicate which task failed. Users can look at the log file in the ``log`` subdirectory for the failed task to determine what caused the failure. For example, if the ``make_grid`` task failed: From 805620031b13a10d4210771a128381187010919d Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 16 Feb 2022 17:08:56 -0500 Subject: [PATCH 012/158] submodule updates --- hpc-stack-mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hpc-stack-mod b/hpc-stack-mod index 9002252d5a..b2e87e1d5e 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 9002252d5a39f69ff084ad2e969862557281bef3 +Subproject commit b2e87e1d5ecc6208903cb00e715b6ed25000d41c From 17504fcfe21ca4b581f4b82ffcc433b748884da6 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 17 Feb 2022 14:54:51 -0500 Subject: [PATCH 013/158] added submodule docs edits --- docs/UsersGuide/build/.gitignore | 4 ---- docs/UsersGuide/source/Quickstart.rst | 22 ++++++++++++++++++++-- docs/UsersGuide/source/conf.py | 6 +++--- hpc-stack-mod | 2 +- 4 files changed, 24 insertions(+), 10 deletions(-) delete mode 100644 docs/UsersGuide/build/.gitignore diff --git a/docs/UsersGuide/build/.gitignore b/docs/UsersGuide/build/.gitignore deleted file mode 100644 index 5e7d2734cf..0000000000 --- a/docs/UsersGuide/build/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -# Ignore everything in this directory -* -# Except this file -!.gitignore diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 4e08b02cf7..09fd88fc29 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -295,6 +295,14 @@ Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log cd $EXPTDIR vi ``log.launch_FV3LAM_wflow`` +Alternatively, to (re)launch the workflow and check its progress on a single line: + +.. code-block:: console + + ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow + +This will output the last 40 lines of the log file. The number 40 can be changed according to the user's preferences. + Launch the Rocoto Workflow Manually --------------------------------------- @@ -380,7 +388,9 @@ If the experiment fails, the ``rocotostat`` command will indicate which task fai cd $EXPTDIR/log vi make_grid.log -If users have the `Slurm workload manager `_ on their system, they can run the ``squeue`` command in lieu of ``rocotostat`` to check what jobs are currently running. +.. note:: + + If users have the `Slurm workload manager `_ on their system, they can run the ``squeue`` command in lieu of ``rocotostat`` to check what jobs are currently running. .. _AdditionalOptions:: @@ -390,10 +400,18 @@ For automatic resubmission of the workflow at regular intervals (e.g., every min .. code-block:: console - */1 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 + */1 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 where is changed to correspond to the user's machine, and "/apps/rocoto/1.3.3/bin/rocotorun" corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can also be changed and simply means that the workflow will be resubmitted every minute. +Then, check the experiment progress with: + +.. code-block:: console + + cd $EXPTDIR + rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 + + .. note:: On Orion, cron is only available on the orion-login-1 node, so please use that node when running cron jobs on Orion. diff --git a/docs/UsersGuide/source/conf.py b/docs/UsersGuide/source/conf.py index 3d7e48c137..93f6bcb9a5 100644 --- a/docs/UsersGuide/source/conf.py +++ b/docs/UsersGuide/source/conf.py @@ -107,9 +107,9 @@ html_static_path = ['_static'] html_context = { - 'css_files': [ - '_static/theme_overrides.css', # override wide tables in RTD theme - ], + # 'css_files': [ + # '_static/theme_overrides.css', # override wide tables in RTD theme +# ], } def setup(app): diff --git a/hpc-stack-mod b/hpc-stack-mod index b2e87e1d5e..485e7c6280 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit b2e87e1d5ecc6208903cb00e715b6ed25000d41c +Subproject commit 485e7c62808566e35cfaf37ba850c08cab4c1683 From 357e151213231aa0691cfc511c348d91eda94d2f Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 17 Feb 2022 18:22:46 -0500 Subject: [PATCH 014/158] hpc-stack updates & formatting fixes --- docs/UsersGuide/source/CodeReposAndDirs.rst | 4 ++-- docs/UsersGuide/source/Components.rst | 8 +++---- docs/UsersGuide/source/ConfigNewPlatform.rst | 2 +- docs/UsersGuide/source/Glossary.rst | 9 ++++++++ docs/UsersGuide/source/InputOutputFiles.rst | 22 ++++++++++---------- docs/UsersGuide/source/Introduction.rst | 4 ++-- docs/UsersGuide/source/Quickstart.rst | 21 ++++++++++--------- docs/UsersGuide/source/conf.py | 8 ++----- docs/UsersGuide/source/index.rst | 2 -- hpc-stack-mod | 2 +- 10 files changed, 42 insertions(+), 40 deletions(-) diff --git a/docs/UsersGuide/source/CodeReposAndDirs.rst b/docs/UsersGuide/source/CodeReposAndDirs.rst index e52f5512c0..3031f84573 100644 --- a/docs/UsersGuide/source/CodeReposAndDirs.rst +++ b/docs/UsersGuide/source/CodeReposAndDirs.rst @@ -42,7 +42,7 @@ repositories associated with this umbrella repo (see :numref:`Table %s `_. +documented `here `__. Note that the prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The source code for these components resides in @@ -50,7 +50,7 @@ the repositories `NCEPLIBS `_ and `NCEPLIB `_. These external components are already built on the preconfigured platforms listed `here -`_. +`__. However, they must be cloned and built on other platforms according to the instructions provided in the wiki pages of those repositories: https://github.com/NOAA-EMC/NCEPLIBS/wiki and https://github.com/NOAA-EMC/NCEPLIBS-external/wiki. diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index cf5180ba40..9562242a59 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -31,11 +31,11 @@ Forecast Model ============== The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (:term:`LAM`) capability :cite:`BlackEtAl2020`. The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `_. +(:term:`FV3`) dynamical core configured with a Limited Area Model (:term:`LAM`) capability :cite:`BlackEtAl2020`. The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `__. -Supported model resolutions in this release include 3-, 13-, and 25-km predefined Contiguous U.S. (:term:`CONUS`) domains, each with 64 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 `here `_ and on the `NOAA Geophysical Fluid Dynamics Laboratory website `_. +Supported model resolutions in this release include 3-, 13-, and 25-km predefined Contiguous U.S. (:term:`CONUS`) domains, each with 64 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 `here `__ and on the `NOAA Geophysical Fluid Dynamics Laboratory website `_. -Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) Land Surface Model options, are supported through the Common Community Physics Package (:term:`CCPP`; described `here `_).Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are two physics options supported for the release. The first is an experimental physics suite 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) v15. 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 +Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) Land Surface Model options, are supported through the Common Community Physics Package (:term:`CCPP`; described `here `__).Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are two physics options supported for the release. The first is an experimental physics suite 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) v15. 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. The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model @@ -93,5 +93,3 @@ described in the Quick Start (:numref:`Section %s `). A few additional computational platforms are considered configurable for the SRW Application release. Configurable platforms (Level 2) are platforms where all of the required libraries for building the SRW Application are expected to install successfully but are not available in a central location. Applications and models are expected to build and run once the required bundled libraries (e.g., NCEPLIBS) and third-party libraries (e.g., NCEPLIBS-external) are built. Limited-Test (Level 3) and Build-Only (Level 4) computational platforms are those in which the developers have built the code but little or no pre-release testing has been conducted, respectively. A complete description of the levels of support, along with a list of preconfigured and configurable platforms can be found in the `SRW Application wiki page `_. - -.. bibliography:: references.bib \ No newline at end of file diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index 798a287b29..4d972d7e31 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -4,7 +4,7 @@ Configuring a New Platform ========================== -The UFS SRW Application has been designed to work primarily on a number of Level 1 and 2 support platforms, as specified `here `_. However, it is also designed with flexibility in mind, so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. A full list of prerequisites for installing the UFS SRW App and running the Graduate Student Test can be found in :numref:`Section %s `. +The UFS SRW Application has been designed to work primarily on a number of Level 1 and 2 support platforms, as specified `here `__. However, it is also designed with flexibility in mind, so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. A full list of prerequisites for installing the UFS SRW App and running the Graduate Student Test can be found in :numref:`Section %s `. The first step to installing on a new machine is to install :term:`NCEPLIBS` (https://github.com/NOAA-EMC/NCEPLIBS), the NCEP libraries package, which is a set of libraries created and maintained by NCEP and EMC that are used in many parts of the UFS. NCEPLIBS comes with a large number of prerequisites (see :numref:`Section %s ` for more info), but the only required software prior to starting the installation process are as follows: diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 4432edc884..1cd7cb8e5d 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -16,6 +16,9 @@ Glossary The preprocessing software used to create initial and boundary condition files to “coldstart” the forecast model. + dynamical core + Global atmospheric model based on fluid dynamics principles, including Euler's equations of motion. + FV3 The Finite-Volume Cubed-Sphere dynamical core (dycore). Developed at NOAA's Geophysical Fluid Dynamics Laboratory (GFDL), it is a scalable and flexible dycore capable of both @@ -28,9 +31,15 @@ Glossary GRIB2 The second version of the World Meterological Organization's (WMO) standard for distributing gridded data. + 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. + 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. + LAM + Limited Area Model. LAM grids use a regional (rather than global) configuration of the FV3 dynamical core. + NAM `North American Mesoscale Forecast System `_. NAM generates multiple grids (or domains) of weather forecasts over the North American continent at various horizontal resolutions. Each grid contains data for dozens of weather parameters, including temperature, precipitation, lightning, and turbulent kinetic energy. NAM uses additional numerical weather models to generate high-resolution forecasts over fixed regions, and occasionally to follow significant weather events like hurricanes. diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 2cce0786d2..a103de9131 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -31,7 +31,7 @@ from a location on disk to your experiment directory by the workflow generation pre-processing utilities use many different datasets to create grids, and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here -`_. +`__. UFS Weather Model ----------------- @@ -41,14 +41,14 @@ must be staged by the user unless you are running on a pre-configured platform, you can link to the existing copy on that machine. See :numref:`Section %s ` for more information. The static, grid, and date specific files are linked in the experiment directory by the workflow scripts. An extensive description of the input files for the weather -model can be found in the `UFS Weather Model User's Guide `_. +model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow, as described in :numref:`Section %s `. Unified Post Processor (UPP) ---------------------------- Documentation for the UPP input files can be found in the `UPP User's Guide -`_. +`__. .. _WorkflowTemplates: @@ -110,7 +110,7 @@ and are shown in :numref:`Table %s `. Additional information related to the ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``, ``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide -`_, +`__, while information on the ``regional_grid.nml`` can be found in the `UFS_UTILS User’s Guide `_. @@ -162,7 +162,7 @@ experiment run directory ``EXPTDIR/YYYYMMDDHH/INPUT`` and consist of the followi * ``sfc_data.nc -> sfc_data.tile7.halo0.nc`` These output files are used as inputs for the UFS weather model, and are described in the `Users Guide -`_. +`__. UFS Weather Model ----------------- @@ -182,11 +182,11 @@ the file names are specified in the input file ``model_configure`` and are set t * ``phyfHHH.nc`` Additional details may be found in the UFS Weather Model `Users Guide -`_. +`__. Unified Post Processor (UPP) ---------------------------- -Documentation for the UPP output files can be found `here `_. +Documentation for the UPP output files can be found `here `__. For the SRW Application, the weather model netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH/postprd`` directory and have the naming convention (file->linked to): @@ -205,7 +205,7 @@ located in ``ufs-srweather-app/src/UPP/parm``. .. note:: This process requires advanced knowledge of which fields can be output for the UFS Weather Model. -Use the directions in the `UPP User's Guide `_ +Use the directions in the `UPP User's Guide `__ for details on how to make modifications to the ``fv3lam.xml`` file and for remaking the flat text file that the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default). @@ -240,8 +240,8 @@ where the static files are located. If you are on a pre-configured or configurab need to stage the fixed files manually because they have been prestaged and the paths are set in ``regional_workflow/ush/setup.sh``. If the user's platform is not defined in that file, the static files can be pulled individually or as a full tar file from the `FTP data repository -`_ or from `Amazon Web Services (AWS) cloud storage -`_ +`__ or from `Amazon Web Services (AWS) cloud storage +`__ and staged on your machine. The paths to the staged files must then be set in ``config.sh`` as follows: @@ -268,7 +268,7 @@ not have access to the NOAA HPSS and you need to pull and stage the data manuall set ``USE_USER_STAGED_EXTRN_FILES`` to ``TRUE`` and then set the paths to the where the IC/LBC files are located. A small sample of IC/LBCs is available at the `FTP data repository -`_ or from `AWS cloud storage +`__ or from `AWS cloud storage `_. Initial and Lateral Boundary Condition Organization diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 1c834e47f4..f7c84f02a1 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -47,7 +47,7 @@ Atmospheric Model The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere (:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability :cite:`BlackEtAl2020`. -The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `_. +The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. Common Community Physics Package --------------------------------- @@ -78,7 +78,7 @@ Build System and Workflow The SRW Application has a portable CMake-based build system that packages together all the components required to build the SRW Application. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see `Rocoto documentation `_). Individual components can also be run in a stand-alone, command line fashion. The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Comuting (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can proceed directly to using the workflow, as -described in the Quick Start Guide (:numref:`Section %s <_GenerateForecast>`). On other platforms, the required libraries will need to be installed via the HPC-Stack. Once these libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. +described in the Quick Start Guide (:numref:`Section %s `). On other platforms, the required libraries will need to be installed via the HPC-Stack. Once these libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. User Support, Documentation, and Contributing Development ========================================================= diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 09fd88fc29..865c863db1 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -6,7 +6,7 @@ Workflow Quick Start This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application. The "out-of-the-box" case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. -.. note:: +.. attention:: The UFS defines `four platform levels `_. The steps described in this chapter are most applicable to preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems as well but may require additional troubleshooting by the user. @@ -16,10 +16,10 @@ This Workflow Quick Start Guide will help users to build and run the "out-of-the Install the HPC-Stack ======================== -.. note:: +.. Hint:: Skip the HPC-stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion). -The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF etc) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `_ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW. +The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF etc) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `__ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW. .. include:: ../../../hpc-stack-mod/docs/source/hpc-intro-text.rst @@ -245,7 +245,7 @@ Next, load the appropriate Python environment for the workflow. The workflow req source ../../env/wflow_.env -.. _GenerateWorkflow:: +.. _GenerateWorkflow: Generate the Regional Workflow ------------------------------------------- @@ -261,9 +261,9 @@ Then, run the following command to generate the workflow: ./generate_FV3LAM_wflow.sh -The last line of output from this script, starting with ``*/1 * * * * ``, can be saved and `used later ` to automatically run portions of the workflow. +The last line of output from this script, starting with ``*/1 * * * *``, can be saved and :ref:`used later ` to automatically run portions of the workflow. -This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in `Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in $EXPTDIR. +This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in $EXPTDIR. An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: @@ -392,17 +392,17 @@ If the experiment fails, the ``rocotostat`` command will indicate which task fai If users have the `Slurm workload manager `_ on their system, they can run the ``squeue`` command in lieu of ``rocotostat`` to check what jobs are currently running. -.. _AdditionalOptions:: +.. _AdditionalOptions: Additional Options ---------------------- -For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry by entering the ``crontab -e`` command, which opens a crontab file. As mentioned in `Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * * ``), can be pasted into the crontab file. It can also be found in the``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: +For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry by entering the ``crontab -e`` command, which opens a crontab file. As mentioned in `Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *``), can be pasted into the crontab file. It can also be found in the``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: .. code-block:: console - */1 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 + */1 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -where is changed to correspond to the user's machine, and "/apps/rocoto/1.3.3/bin/rocotorun" corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can also be changed and simply means that the workflow will be resubmitted every minute. +where ```` is changed to correspond to the user's machine, and ``"/apps/rocoto/1.3.3/bin/rocotorun"`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can also be changed and simply means that the workflow will be resubmitted every minute. Then, check the experiment progress with: @@ -411,6 +411,7 @@ Then, check the experiment progress with: cd $EXPTDIR rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 +After finishing the experiment, open the crontab using `` crontab -e`` and delete the crontab entry. .. note:: diff --git a/docs/UsersGuide/source/conf.py b/docs/UsersGuide/source/conf.py index 93f6bcb9a5..42148bea63 100644 --- a/docs/UsersGuide/source/conf.py +++ b/docs/UsersGuide/source/conf.py @@ -104,13 +104,9 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] -html_context = { - # 'css_files': [ - # '_static/theme_overrides.css', # override wide tables in RTD theme -# ], - } +html_context = {} def setup(app): app.add_css_file('custom.css') # may also be an URL diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index d9ffc68370..96ac2e51c4 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -5,8 +5,6 @@ UFS Short-Range Weather App Users Guide ======================================= - -.. index:: .. toctree:: :numbered: diff --git a/hpc-stack-mod b/hpc-stack-mod index 485e7c6280..52d227f571 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 485e7c62808566e35cfaf37ba850c08cab4c1683 +Subproject commit 52d227f5718f46eee017f55b17a51f3fc1354cf3 From acf555b4ef1d1125b160d6eebefcfbbacd3ae939 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 17 Feb 2022 18:37:55 -0500 Subject: [PATCH 015/158] hpc-stack intro edits --- docs/UsersGuide/source/Quickstart.rst | 10 +++++++++- hpc-stack-mod | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 865c863db1..4df02d1993 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -19,10 +19,18 @@ Install the HPC-Stack .. Hint:: Skip the HPC-stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion). +**Definition:** HPC-stack is a repository that provides a unified, shell script-based build system that builds the software stack required for the `Unified Forecast System (UFS) `_ and applications. + +Background +---------------- + The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF etc) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `__ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW. -.. include:: ../../../hpc-stack-mod/docs/source/hpc-intro-text.rst +Instructions +------------------------- +`Level 1 `_ platforms (e.g. Cheyenne, Hera) already have the HPC-Stack installed. Users on those platforms do *not* need to install the HPC-Stack before building applications or models that require the HPC-Stack. Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to run applications or models that depend on it. +Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. After completing installation, continue to the :ref:`next section `. diff --git a/hpc-stack-mod b/hpc-stack-mod index 52d227f571..174286c1fe 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 52d227f5718f46eee017f55b17a51f3fc1354cf3 +Subproject commit 174286c1fe8ee3c59f54539389ce9fbe2d1ef0d1 From 36349a610e1a6c163986af84a5c0d6d56c5af5dd Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 18 Feb 2022 13:12:26 -0500 Subject: [PATCH 016/158] bibtex attempted fix --- docs/UsersGuide/requirements.txt | 2 +- docs/UsersGuide/source/Quickstart.rst | 24 ++++++++++++------------ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/UsersGuide/requirements.txt b/docs/UsersGuide/requirements.txt index 9c7258463b..8e21f437b4 100644 --- a/docs/UsersGuide/requirements.txt +++ b/docs/UsersGuide/requirements.txt @@ -1,2 +1,2 @@ -sphinxcontrib-bibtex +sphinxcontrib-bibtex==1.0.0 sphinx_rtd_theme diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 4df02d1993..a312748d08 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -16,10 +16,10 @@ This Workflow Quick Start Guide will help users to build and run the "out-of-the Install the HPC-Stack ======================== -.. Hint:: +.. Attention:: Skip the HPC-stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion). -**Definition:** HPC-stack is a repository that provides a unified, shell script-based build system that builds the software stack required for the `Unified Forecast System (UFS) `_ and applications. +**Definition:** :term:`HPC-stack` is a repository that provides a unified, shell script-based build system that builds the software stack required for the `Unified Forecast System (UFS) `_ and applications. Background ---------------- @@ -32,8 +32,7 @@ Instructions Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. -After completing installation, continue to the :ref:`next section `. - +After completing installation, continue to the next section. .. _DownloadCode: @@ -129,11 +128,12 @@ to the command line, or the file can be sourced from the ufs-srweather-app ``env For example, on Hera, run ``source env/build_hera_intel.env`` from the main ufs-srweather-app directory to source the appropriate file. -On Level 3-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. On systems without Lmod, this process will typically involve commands in the form `export =`. You may need to use ``setenv`` rather than ``export`` depending on your environment. +On Level 3-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. On systems without Lmod, this process will typically involve commands in the form ``export =``. You may need to use ``setenv`` rather than ``export`` depending on your environment. + -Troubleshooting ------------------- -* If the system cannot find a module (i.e., a "module unknown" message appears), check whether the module version numbers match in ``ufs-srweather-app/env/build__.env`` and the ``hpc-stack/stack/stack_custom.yaml``. +.. hint:: + + If the system cannot find a module (i.e., a "module unknown" message appears), check whether the module version numbers match in ``ufs-srweather-app/env/build__.env`` and the ``hpc-stack/stack/stack_custom.yaml``. Build the Executables @@ -184,7 +184,7 @@ Set Experiment Parameters ------------------------- Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in the ``config.sh`` file. Two example ``config.sh`` templates are provided: ``config.community.sh`` and ``config.nco.sh``. They can be found in the ``ufs-srweather-app/regional_workflow/ush`` directory. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. -Make a copy of ``config.community.sh`` to get started (under /regional_workflow/ush): +Make a copy of ``config.community.sh`` to get started (under ``/regional_workflow/ush``): .. code-block:: console @@ -204,7 +204,7 @@ Next, edit the new ``config.sh`` file to customize it for your machine. At a min Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :doc:`Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in the section on :doc:`Limited Area Model (LAM) Grids `. -.. note:: +.. Important:: If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. @@ -410,7 +410,7 @@ For automatic resubmission of the workflow at regular intervals (e.g., every min */1 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -where ```` is changed to correspond to the user's machine, and ``"/apps/rocoto/1.3.3/bin/rocotorun"`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can also be changed and simply means that the workflow will be resubmitted every minute. +where ```` is changed to correspond to the user's machine, and ``/apps/rocoto/1.3.3/bin/rocotorun`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can also be changed and simply means that the workflow will be resubmitted every minute. Then, check the experiment progress with: @@ -423,7 +423,7 @@ After finishing the experiment, open the crontab using `` crontab -e`` and delet .. note:: - On Orion, cron is only available on the orion-login-1 node, so please use that node when running cron jobs on Orion. + On Orion, *cron* is only available on the orion-login-1 node, so please use that node when running cron jobs on Orion. The workflow run is completed when all tasks have “SUCCEEDED”, and the rocotostat command will output the following: From 838271f80aa2be403ecf172fa045052bb1c9bfa9 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 18 Feb 2022 17:06:08 -0500 Subject: [PATCH 017/158] add hpc-stack module edits --- hpc-stack-mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hpc-stack-mod b/hpc-stack-mod index 174286c1fe..d1b88151e3 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 174286c1fe8ee3c59f54539389ce9fbe2d1ef0d1 +Subproject commit d1b88151e367255748b150db9de0d77b90aec5ba From 863b7de5cfe0af769b6f4b4351db0f307c816cc9 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 13:19:32 -0500 Subject: [PATCH 018/158] update sphinxcontrib version --- docs/UsersGuide/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/requirements.txt b/docs/UsersGuide/requirements.txt index 8e21f437b4..d3a02244d2 100644 --- a/docs/UsersGuide/requirements.txt +++ b/docs/UsersGuide/requirements.txt @@ -1,2 +1,2 @@ -sphinxcontrib-bibtex==1.0.0 +sphinxcontrib-bibtex<2.0.0 sphinx_rtd_theme From 2b100d9dd14d0757ca6fdbc302e0d8a04f00eb9d Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 13:25:48 -0500 Subject: [PATCH 019/158] add .readthedocs.yaml file --- .readthedocs.yaml | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..e6f30f6274 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,29 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-20.04 + tools: + python: "3.9" + # You can also specify other tool versions: + # nodejs: "16" + # rust: "1.55" + # golang: "1.17" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# If using Sphinx, optionally build your docs in additional formats such as PDF +# formats: +# - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt From 9e58e67ebe8a61b23d057c76fa4938e09a267abf Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 13:28:35 -0500 Subject: [PATCH 020/158] update .readthedocs.yaml file --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index e6f30f6274..dc8246b926 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -26,4 +26,4 @@ sphinx: # Optionally declare the Python requirements required to build your docs python: install: - - requirements: docs/requirements.txt + - requirements: docs/UsersGuide/requirements.txt From 1830b4935e943abe0eb546813b47603ffa7f84d7 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 13:51:10 -0500 Subject: [PATCH 021/158] update .readthedocs.yaml file --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index dc8246b926..6fd3e6514e 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -17,7 +17,7 @@ build: # Build documentation in the docs/ directory with Sphinx sphinx: - configuration: docs/conf.py + configuration: docs/UsersGuide/source/conf.py # If using Sphinx, optionally build your docs in additional formats such as PDF # formats: From 54a647e251a5ed66383bbbf34d90ae78b32f3aca Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 13:53:43 -0500 Subject: [PATCH 022/158] update conf.py --- docs/UsersGuide/source/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/UsersGuide/source/conf.py b/docs/UsersGuide/source/conf.py index 42148bea63..d4404bb8b5 100644 --- a/docs/UsersGuide/source/conf.py +++ b/docs/UsersGuide/source/conf.py @@ -52,7 +52,6 @@ 'sphinx.ext.githubpages', 'sphinx.ext.napoleon', 'sphinxcontrib.bibtex', - 'myst_parser' ] bibtex_bibfiles = ['references.bib'] From 46d381fa10dffcde964c50041e9100ffcefbc26d Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 15:20:01 -0500 Subject: [PATCH 023/158] updates .readthedocs.yaml with submodules --- .readthedocs.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6fd3e6514e..6879430f88 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -27,3 +27,9 @@ sphinx: python: install: - requirements: docs/UsersGuide/requirements.txt + +submodules: + include: + - hpc-stack-mod + #recursive: true + From 91af03d335a786ccd6e4e671b31edc577d3855c7 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 15:35:24 -0500 Subject: [PATCH 024/158] updates .readthedocs.yaml with submodules --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6879430f88..e0987f8926 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -31,5 +31,5 @@ python: submodules: include: - hpc-stack-mod - #recursive: true + recursive: true From 97616fdc204fccd2cee9e35dac57fca368b19394 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 15:51:19 -0500 Subject: [PATCH 025/158] submodule updates --- hpc-stack-mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hpc-stack-mod b/hpc-stack-mod index d1b88151e3..bf2320bc5c 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit d1b88151e367255748b150db9de0d77b90aec5ba +Subproject commit bf2320bc5ceb6926bca9cebc0dcb94a8e8a60c01 From 21d3e271939a8160fde1ca2636ec2a1fff7326a5 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Feb 2022 16:10:30 -0500 Subject: [PATCH 026/158] submodule updates --- hpc-stack-mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hpc-stack-mod b/hpc-stack-mod index bf2320bc5c..5784e7b9a9 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit bf2320bc5ceb6926bca9cebc0dcb94a8e8a60c01 +Subproject commit 5784e7b9a9db83bbc76f04da13ff7b7f4bbaa067 From 5af69e522e5dd0812d3953e740938d1be61e662c Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Feb 2022 12:17:29 -0500 Subject: [PATCH 027/158] minor Intro edits --- docs/UsersGuide/requirements.txt | 2 +- docs/UsersGuide/source/Introduction.rst | 44 +++++++++++-------------- 2 files changed, 21 insertions(+), 25 deletions(-) diff --git a/docs/UsersGuide/requirements.txt b/docs/UsersGuide/requirements.txt index d3a02244d2..9c7258463b 100644 --- a/docs/UsersGuide/requirements.txt +++ b/docs/UsersGuide/requirements.txt @@ -1,2 +1,2 @@ -sphinxcontrib-bibtex<2.0.0 +sphinxcontrib-bibtex sphinx_rtd_theme diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index f7c84f02a1..f052e741ea 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -4,39 +4,34 @@ Introduction ============ -The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the UFS Portal at https://ufscommunity.org/. +The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. -The UFS can be configured for multiple applications (see a complete list at https://ufscommunity.org/science/aboutapps/). The configuration described here is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g. METplus). This documentation provides a quick start guide for running the application, in addition to an overview of the release components, a description of the supported capabilities, and information on where to find more information and obtain support. +The UFS can be configured for multiple applications (see the `complete list here `__). The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a `Quick Start Guide ` for running the application, in addition to an overview of the `release components `, a description of the supported capabilities, and details on where to find more information and obtain support. -The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research -conducted with the App: +The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research conducted with the App: UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994 How to Use This Document ======================== -This guide instructs both novice and experienced users on downloading, building, and running the SRW Application. Please post questions in the UFS forum at https://forums.ufscommunity.org/. +This guide instructs both novice and experienced users on downloading, building, and running the SRW Application. Please post questions in the `UFS forum `__. .. code-block:: console - Throughout the guide, this presentation style indicates shell commands and options, code examples, etc. + Throughout the guide, this presentation style indicates shell commands and options, + code examples, etc. -.. note:: +Variables presented as ``AaBbCc123`` in this document typically refer to variables in scripts, names of files, and directories. - Variables presented as ``AaBbCc123`` in this document typically refer to variables - in scripts, names of files, and directories. - -.. note:: - - File paths or code that include angle brackets (e.g., ``env/build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``env/build_aws_gcc.env``). +File paths or code that include angle brackets (e.g., ``env/build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``env/build_aws_gcc.env``). Pre-processor Utilities and Initial Conditions ============================================== The SRW Application includes a number of pre-processing utilities that initialize and prepare the -model. Tasks include generating a regional grid, along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. +model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. Forecast Model @@ -46,7 +41,7 @@ Atmospheric Model -------------------- The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability :cite:`BlackEtAl2020`. +(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability :cite:t:`BlackEtAl2020`. The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. Common Community Physics Package @@ -64,21 +59,22 @@ ingests initial and lateral boundary condition files produced by :term:`chgres_c Post-processor ============== -The Unified Post Processor (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF output on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing, e.g. statistical post-processing techniques. +The `Unified Post Processor `__ (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF format on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). Visualization Example ===================== -This SRW Application distribution provides Python scripts to create basic visualizations of the model output. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. +This SRW Application provides Python scripts to create basic visualizations of the model output. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. Build System and Workflow ========================= -The SRW Application has a portable CMake-based build system that packages together all the components required to build the SRW Application. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see `Rocoto documentation `_). Individual components can also be run in a stand-alone, command line fashion. The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. +The SRW Application has a portable CMake-based build system that packages together all the components required to build the SRW Application. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see `Rocoto documentation `__ for more on workflow management). Individual components can also be run in a stand-alone, command line fashion. + +The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. -This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Comuting (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can proceed directly to using the workflow, as -described in the Quick Start Guide (:numref:`Section %s `). On other platforms, the required libraries will need to be installed via the HPC-Stack. Once these libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Comuting (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can proceed directly to using the workflow to generate an experiment, as described in the Quick Start Guide (:numref:`Section %s Generate the Forecast Experiment `). On other platforms, the required libraries will need to be installed via the HPC_Stack (see :numref:`Section %s Installing the HPC-Stack `). Once these libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. User Support, Documentation, and Contributing Development ========================================================= @@ -89,7 +85,7 @@ A list of available documentation is shown in :numref:`Table %s `. +utilities, model code, and infrastructure. Users can post issues in the related GitHub repositories to report bugs or to announce upcoming contributions to the code base. For code to be accepted in the authoritative repositories, users must follow the code management rules of each component (described in the User’s Guides listed in :numref:`Table %s `). Future Direction ================ Users can expect to see incremental improvements and additional capabilities in upcoming releases of the SRW Application to enhance research opportunities and support operational -forecast implementations. Planned advancements include: +forecast implementations. Planned enhancements include: * A more extensive set of supported developmental physics suites. * A larger number of pre-defined domains/resolutions and a fully supported capability to create a user-defined domain. * Inclusion of data assimilation, cycling, and ensemble capabilities. -* A verification package (i.e., METplus) integrated into the workflow. +* A verification package (e.g., METplus) integrated into the workflow. * Inclusion of stochastic perturbation techniques. In addition to the above list, other improvements will be addressed in future releases. From ee901e6c9c45b3aa4636bf1f95758c5d02e56e10 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Feb 2022 13:53:29 -0500 Subject: [PATCH 028/158] minor Intro edits --- docs/UsersGuide/source/Introduction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index f052e741ea..21517a36c0 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -6,7 +6,7 @@ Introduction The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. -The UFS can be configured for multiple applications (see the `complete list here `__). The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a `Quick Start Guide ` for running the application, in addition to an overview of the `release components `, a description of the supported capabilities, and details on where to find more information and obtain support. +The UFS can be configured for multiple applications (see the `complete list here `__). The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a :ref:`Quick Start Guide ` for running the application, in addition to an overview of the :ref:`release components `, a description of the supported capabilities, and details on where to find more information and obtain support. The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research conducted with the App: @@ -41,7 +41,7 @@ Atmospheric Model -------------------- The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability :cite:t:`BlackEtAl2020`. +(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability (:cite:t:`BlackEtAl2020`). The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. Common Community Physics Package From f77cba93a6db2ff6ac75d4c516633d85c89cb188 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Feb 2022 15:13:22 -0500 Subject: [PATCH 029/158] minor Intro edits --- docs/UsersGuide/source/Glossary.rst | 5 ++++- docs/UsersGuide/source/Introduction.rst | 23 ++++++++++------------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 1cd7cb8e5d..db0b1cd140 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -66,6 +66,9 @@ Glossary NEMSIO A binary format for atmospheric model output from :term:`NCEP`'s Global Forecast System (GFS). + NWP + Numerical Weather Prediction + Orography The branch of physical geography dealing with mountains @@ -86,7 +89,7 @@ Glossary part of this collection. UPP - The Unified Post Processor is software developed at :term:`NCEP` and used operationally to + The `Unified Post Processor `__ is software developed at :term:`NCEP` and used operationally to post-process raw output from a variety of :term:`NCEP`'s NWP models, including the FV3. Weather Enterprise diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 21517a36c0..877dee4ada 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -1,8 +1,8 @@ .. _Introduction: -============ +============= Introduction -============ +============= The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. @@ -47,19 +47,18 @@ The dynamical core is the computational part of a model that solves the equation Common Community Physics Package --------------------------------- -The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and Noah Multi-parameterization (Noah MP) Land Surface Model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions.The SRW release includes an experimental physics version and an updated operational version. +The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and Noah Multi-parameterization (Noah MP) Land Surface Model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW release includes an experimental physics version and an updated operational version. Data Format -------------- -The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model -ingests initial and lateral boundary condition files produced by :term:`chgres_cube`. +The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube`. Post-processor ============== -The `Unified Post Processor `__ (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF format on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). +The `Unified Post Processor `__ (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF format on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from the UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). Visualization Example @@ -74,10 +73,10 @@ The SRW Application has a portable CMake-based build system that packages togeth The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. -This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Comuting (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can proceed directly to using the workflow to generate an experiment, as described in the Quick Start Guide (:numref:`Section %s Generate the Forecast Experiment `). On other platforms, the required libraries will need to be installed via the HPC_Stack (see :numref:`Section %s Installing the HPC-Stack `). Once these libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can proceed directly to using the workflow to generate an experiment, as described in the Quick Start Guide :numref:`Section %s Generate the Forecast Experiment `. On other platforms, the required libraries will need to be installed via the HPC-Stack (see :numref:`Section %s Installing the HPC-Stack `). Once these libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. -User Support, Documentation, and Contributing Development -========================================================= +User Support, Documentation, and Contributions to Development +=============================================================== A forum-based, online `support system `_ organized by topic provides a centralized location for UFS users and developers to post questions and exchange information. @@ -118,10 +117,10 @@ A list of available documentation is shown in :numref:`Table %s `). +utilities, model code, and infrastructure. Users can post issues in the related GitHub repositories to report bugs or to announce upcoming contributions to the code base. For code to be accepted in the authoritative repositories, users must follow the code management rules of each component, which are outlined in the respective User's Guides listed in :numref:`Table %s `. Future Direction -================ +================= Users can expect to see incremental improvements and additional capabilities in upcoming releases of the SRW Application to enhance research opportunities and support operational @@ -133,8 +132,6 @@ forecast implementations. Planned enhancements include: * A verification package (e.g., METplus) integrated into the workflow. * Inclusion of stochastic perturbation techniques. -In addition to the above list, other improvements will be addressed in future releases. - .. bibliography:: references.bib From bc0748c81a8464cad1079887b8bb0a280a8afafb Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Feb 2022 15:31:20 -0500 Subject: [PATCH 030/158] submodule updates --- hpc-stack-mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hpc-stack-mod b/hpc-stack-mod index 5784e7b9a9..f8b32160eb 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 5784e7b9a9db83bbc76f04da13ff7b7f4bbaa067 +Subproject commit f8b32160eb1c1165a51b2df7479b2e9a158aadfc From fef6d27824968bcca681a9f82221691901542fbc Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Feb 2022 18:24:06 -0500 Subject: [PATCH 031/158] fixed typos in QS --- docs/UsersGuide/source/Quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index a312748d08..018e295312 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -61,7 +61,7 @@ Start the container and run an interactive shell within it. This command also bi .. code-block:: console - singularity shell -e --writable --bind /home:/home ubuntu20.04-hpc-stack + singularity shell -e --writable --bind /home:/home ubuntu20.04-hpc-stack-0.1 Clone the develop branch of the UFS-SRW weather application repository: @@ -121,7 +121,7 @@ If the SRW Application has been built in a container provided by the Earth Predi On Other Systems (Non-Container Approach) ------------------------------------------ -Otherwise, for Level 1 and 2 systems, scripts for loading the proper modules and/or setting the +For Level 1 and 2 systems, scripts for loading the proper modules and/or setting the correct environment variables can be found in the ``env/`` directory of the SRW App in files named ``build__.env``. The commands in these files can be directly copy-pasted to the command line, or the file can be sourced from the ufs-srweather-app ``env/`` directory. From 0d16101ce9d82689deb1ccd186dddd6721d93fb1 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 24 Feb 2022 18:02:09 -0500 Subject: [PATCH 032/158] QS updates --- docs/UsersGuide/source/Quickstart.rst | 33 +++++++++++++++------------ 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 018e295312..7cd52c7dc1 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -47,21 +47,22 @@ Pull the Singularity container: .. code-block:: console - singularity pull ubuntu20.04-hpc-stack-0.1.sif docker://noaaepic/ubuntu20.04-hpc-stack:0.1 + singularity pull ubuntu20.04-epic-srwapp-1.0.sif docker://noaaepic/ubuntu20.04-epic-srwapp:1.0 -Build the container and make a ``home`` directory inside it: +Build the container and make a ``contrib`` directory inside it if one does not already exist: .. code-block:: console - singularity build --sandbox ubuntu20.04-hpc-stack-0.1 ubuntu20.04-hpc-stack-0.1.sif - cd ubuntu20.04-hpc-stack-0.1 - mkdir home + singularity build --sandbox ubuntu20.04-epic-srwapp-1.0 ubuntu20.04-epic-srwapp-1.0.sif + cd ubuntu20.04-epic-srwapp-1.0 + mkdir contrib + cd .. Start the container and run an interactive shell within it. This command also binds the local home directory to the container so that data can be shared between them. .. code-block:: console - singularity shell -e --writable --bind /home:/home ubuntu20.04-hpc-stack-0.1 + singularity shell -e --writable --bind /:/contrib ubuntu20.04-epic-srwapp-1.0 Clone the develop branch of the UFS-SRW weather application repository: @@ -79,6 +80,7 @@ Check out submodules for the SRW Application: cd ufs-srweather-app ./manage_externals/checkout_externals +If the ``manage_externals`` command brings up an error, it may be necessary to run ``ln -s /usr/bin/python3 /usr/bin/python`` first. Run the UFS SRW Without a Container ------------------------------------ @@ -173,10 +175,9 @@ Generating the forecast experiment requires three steps: * Set experiment parameters * Set Python and other environment parameters -* Run the ``generate_FV3LAM_wflow.sh`` script to generate the experiment workflow +* Run a script to generate the experiment workflow -The first two steps depend on the platform being used and are described here for each Level 1 platform. -Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. +The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. .. _SetUpConfigFile: @@ -252,18 +253,20 @@ Next, load the appropriate Python environment for the workflow. The workflow req source ../../env/wflow_.env +This command will activate the ``regional_workflow``. The user should see ``(regional_workflow)`` in front of the Terminal prompt at this point. If this is not the case, activate the regional workflow from the ``ush`` directory by running: + +.. code-block:: console + + conda activate regional_workflow + + .. _GenerateWorkflow: Generate the Regional Workflow ------------------------------------------- -First, activate the regional workflow from the ``ush`` directory: - -.. code-block:: console - - conda activate regional_workflow -Then, run the following command to generate the workflow: +Run the following command to generate the workflow: .. code-block:: console From 418a40bfa828bb09a94439a8c107d9509ae445d0 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 24 Feb 2022 18:57:28 -0500 Subject: [PATCH 033/158] QS updates --- docs/UsersGuide/source/Quickstart.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 7cd52c7dc1..2609b91797 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -155,17 +155,17 @@ From the build directory, run the ``cmake`` command below to set up the ``Makefi cmake .. -DCMAKE_INSTALL_PREFIX=.. make -j 4 >& build.out & -Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. -When the build completes, you should see the forecast model executable ``NEMS.exe`` and eleven -pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are -described in :numref:`Table %s `. +The build will take a few minutes to complete. Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, you should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. + +.. hint:: + + If you do not see a ``ufs-srweather-app/bin`` directory, wait a few more minutes for the build to complete. Download and Stage the Data ============================ The SRW requires input files to run. These include static datasets, initial and boundary conditions -files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are -already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :doc:`Input and Output Files `, Section 3. Section 1 contains useful background information on the input files required by the SRW. +files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :doc:`Input and Output Files `, Section 3. Section 1 contains useful background information on the input files required by the SRW. .. _GenerateForecast: @@ -185,11 +185,11 @@ Set Experiment Parameters ------------------------- Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in the ``config.sh`` file. Two example ``config.sh`` templates are provided: ``config.community.sh`` and ``config.nco.sh``. They can be found in the ``ufs-srweather-app/regional_workflow/ush`` directory. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. -Make a copy of ``config.community.sh`` to get started (under ``/regional_workflow/ush``): +Make a copy of ``config.community.sh`` to get started (under ``/regional_workflow/ush``). From the ``ufs-srweather-app`` directory, run: .. code-block:: console - cd ../regional_workflow/ush + cd regional_workflow/ush cp config.community.sh config.sh The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. @@ -203,7 +203,7 @@ Next, edit the new ``config.sh`` file to customize it for your machine. At a min EXPT_SUBDIR="GST" EXPT_BASEDIR="home/$USER/expt_dirs" -Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :doc:`Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in the section on :doc:`Limited Area Model (LAM) Grids `. +Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :ref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :ref:`Chapter %s: Limited Area Model (LAM) Grids `. .. Important:: From 77d565db54acf9cb39c2c294e5183186d2e8d197 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 24 Feb 2022 19:03:43 -0500 Subject: [PATCH 034/158] QS updates --- docs/UsersGuide/source/Quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 2609b91797..0c0782a708 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -203,7 +203,7 @@ Next, edit the new ``config.sh`` file to customize it for your machine. At a min EXPT_SUBDIR="GST" EXPT_BASEDIR="home/$USER/expt_dirs" -Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :ref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :ref:`Chapter %s: Limited Area Model (LAM) Grids `. +Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. .. Important:: From 2e1a03fc6f90f6a11e85a9306740370c13f69c6e Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 25 Feb 2022 18:36:37 -0500 Subject: [PATCH 035/158] updates to InputOutput and QS --- docs/UsersGuide/source/Glossary.rst | 7 +- docs/UsersGuide/source/InputOutputFiles.rst | 156 +++++++++----------- docs/UsersGuide/source/Quickstart.rst | 24 ++- 3 files changed, 94 insertions(+), 93 deletions(-) diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index db0b1cd140..f426ac8a9c 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -37,6 +37,9 @@ 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 + Initial conditions/lateral boundary conditions + LAM Limited Area Model. LAM grids use a regional (rather than global) configuration of the FV3 dynamical core. @@ -66,8 +69,8 @@ Glossary NEMSIO A binary format for atmospheric model output from :term:`NCEP`'s Global Forecast System (GFS). - NWP - Numerical Weather Prediction + NWP (Numerical Weather Prediction) + Numerical Weather Prediction (NWP) takes current observations of weather and processes them with computer models to forecast the future state of the weather. Orography The branch of physical geography dealing with mountains diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index a103de9131..c508bcda85 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -4,8 +4,7 @@ Input and Output Files ====================== This chapter provides an overview of the input and output files needed by the components -of the UFS SRW Application (:term:`UFS_UTILS`, the UFS :term:`Weather Model`, and :term:`UPP`). -Links to more detailed documentation for each of the components are provided. +of the UFS SRW Application (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`). Links to more detailed documentation for each of the components are provided. Input Files =========== @@ -19,31 +18,19 @@ The external model files needed for initializing the runs can be obtained in a n ways, including: pulled directly from `NOMADS `_; limited data availability), pulled from the NOAA HPSS during the workflow execution (requires user access), or obtained and staged by the user from a different source. The data format for -these files can be :term:`GRIB2` or :term:`NEMSIO`. More information on downloading and staging -the external model data can be found in :numref:`Section %s `. Once staged, -the end-to-end application will run the system and write output files to disk. +these files can be :term:`GRIB2` or :term:`NEMSIO`. More information on downloading and setting up +the external model data can be found in :numref:`Section %s `. Once the data is set up, the end-to-end application will run the system and write output files to disk. Pre-processing (UFS_UTILS) -------------------------- -When a user runs the SRW Application as described in the quickstart guide -:numref:`Section %s `, input data for the pre-processing utilities is linked -from a location on disk to your experiment directory by the workflow generation step. The -pre-processing utilities use many different datasets to create grids, and to generate model -input datasets from the external model files. A detailed description of the input files -for the pre-processing utilities can be found `here -`__. +When a user runs the SRW Application as described in the Quick Start Guide :numref:`Chapter %s `, the workflow generation step (:numref:`Step %s `) links the input data for the pre-processing utilities from a location on disk to the experiment directory. The +pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here `__. UFS Weather Model ----------------- The input files for the weather model include both static (fixed) files and grid and date specific files (terrain, initial conditions, boundary conditions, etc). The static fix files -must be staged by the user unless you are running on a pre-configured platform, in which case -you can link to the existing copy on that machine. See :numref:`Section %s ` -for more information. The static, grid, and date specific files are linked in the experiment -directory by the workflow scripts. An extensive description of the input files for the weather -model can be found in the `UFS Weather Model User's Guide `__. -The namelists and configuration files for the SRW Application are created from templates by the -workflow, as described in :numref:`Section %s `. +must be staged by the user unless you are running on a Level 1/pre-configured platform, in which case you can link to the existing copy of the data on that machine. See :numref:`Section %s ` for more information. The static, grid, and date-specific files are linked in the experiment directory by the workflow scripts. An extensive description of the input files for the weather model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow, as described in :numref:`Section %s `. Unified Post Processor (UPP) ---------------------------- @@ -54,10 +41,10 @@ Documentation for the UPP input files can be found in the `UPP User's Guide Workflow -------- -The SRW Application uses a series of template files, combined with user selected settings, +The SRW Application uses a series of template files, combined with user-selected settings, to create the required namelists and parameter files needed by the Application. These -templates can be reviewed to see what defaults are being used, and where configuration parameters -are assigned from the ``config.sh`` file. +templates can be reviewed to see what defaults are being used and where configuration parameters +from the ``config.sh`` file are assigned. List of Template Files ^^^^^^^^^^^^^^^^^^^^^^ @@ -81,7 +68,7 @@ and are shown in :numref:`Table %s `. +-----------------------------+-------------------------------------------------------------+ | field_table_[CCPP] | Cycle-independent file that the forecast model reads in at | | | the start of each forecast. It specifies the tracers that | - | | the forecast model will advect. A different field_table | + | | the forecast model will advect. A different field_table | | | may be needed for different CCPP suites. | +-----------------------------+-------------------------------------------------------------+ | FV3.input.yml | YAML configuration file containing the forecast model’s | @@ -108,9 +95,7 @@ and are shown in :numref:`Table %s `. | README.xml_templating.md | Instruction of Rocoto XML templating with Jinja. | +-----------------------------+-------------------------------------------------------------+ -Additional information related to the ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``, -``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide -`__, +Additional information related to the ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``, ``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, while information on the ``regional_grid.nml`` can be found in the `UFS_UTILS User’s Guide `_. @@ -119,13 +104,8 @@ Migratory Route of the Input Files in the Workflow :numref:`Figure %s ` shows how the case-specific input files in the ``ufs-srweather-app/regional_workflow/ush/templates/`` directory flow to the experiment directory. The value of ``CCPP_PHYS_SUITE`` is specified in the configuration file ``config.sh``. The template -input files corresponding to ``CCPP_PHYS_SUITE``, such as ``field_table`` and ``nems_configure``, are -copied to the experiment directory ``EXPTDIR`` and the namelist file of the weather model ``input.nml`` -is created from the ``input.nml.FV3`` and ``FV3.input.yml`` files by running the script ``generate_FV3LAM_wflow.sh``. -While running the task ``RUN_FCST`` in the regional workflow as shown in :numref:`Figure %s `, -the ``field_table``, ``nems.configure``, and ``input.nml`` files, located in ``EXPTDIR`` are linked to the -cycle directory ``CYCLE_DIR/``, and ``diag_table`` and ``model_configure`` are copied from the ``templates`` -directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. +input files corresponding to ``CCPP_PHYS_SUITE``, such as ``field_table`` and ``nems_configure``, are copied to the experiment directory ``EXPTDIR``, and the namelist file of the weather model ``input.nml`` is created from the ``input.nml.FV3`` and ``FV3.input.yml`` files by running the script ``generate_FV3LAM_wflow.sh``. +While running the task ``RUN_FCST`` in the regional workflow as shown in :numref:`Figure %s `, the ``field_table``, ``nems.configure``, and ``input.nml`` files, located in ``EXPTDIR``, are linked to the cycle directory ``CYCLE_DIR/``. Additionally, ``diag_table`` and ``model_configure`` are copied from the ``templates`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. .. _MigratoryRoute: @@ -194,20 +174,15 @@ directory and have the naming convention (file->linked to): * ``BGRD3D_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgrd3df{fhr}.tmXX.grib2`` * ``BGDAWP_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgdawpf{fhr}.tmXX.grib2`` -The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by -the user in the ``config.sh`` settings. +The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by the user in the ``config.sh`` settings. If you wish to modify the fields or levels that are output from the UPP, you will need to make -modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW -Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be -located in ``ufs-srweather-app/src/UPP/parm``. +modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. .. note:: This process requires advanced knowledge of which fields can be output for the UFS Weather Model. -Use the directions in the `UPP User's Guide `__ -for details on how to make modifications to the ``fv3lam.xml`` file and for remaking the flat text file that -the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default). +Use the directions in the `UPP User's Guide `__ for details on how to make modifications to the ``fv3lam.xml`` file and for remaking the flat text file that the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default). Once you have created the new flat text file reflecting your changes, you will need to modify your ``config.sh`` to point the workflow to the new text file. In your ``config.sh``, set the following: @@ -215,11 +190,10 @@ Once you have created the new flat text file reflecting your changes, you will n .. code-block:: console USE_CUSTOM_POST_CONFIG_FILE=”TRUE” - CUSTOM_POST_CONFIG_PATH=”/path/to/custom/postxconfig-NT-fv3lam.txt” + CUSTOM_POST_CONFIG_PATH=”” which tells the workflow to use the custom file located in the user-defined path. The path should -include the filename. If this is set to true and the file path is not found, then an error will occur -when trying to generate the SRW Application workflow. +include the filename. If this is set to true and the file path is not found, then an error will occur when trying to generate the SRW Application workflow. You may then start your case workflow as usual and the UPP will use the new flat ``*.txt`` file. @@ -228,22 +202,21 @@ You may then start your case workflow as usual and the UPP will use the new flat Downloading and Staging Input Data ================================== A set of input files, including static (fix) data and raw initial and lateral boundary conditions -(IC/LBCs), are needed to run the SRW Application. +(:term:`IC/LBC`'s), are needed to run the SRW Application. .. _StaticFixFiles: Static Files ------------ -A set of fix files are necessary to run the SRW Application. Environment variables describe the -location of the static files: ``FIXgsm``, ``TOPO_DIR``, and ``SFC_CLIMO_INPUT_DIR`` are the directories -where the static files are located. If you are on a pre-configured or configurable platform, there is no -need to stage the fixed files manually because they have been prestaged and the paths -are set in ``regional_workflow/ush/setup.sh``. If the user's platform is not defined -in that file, the static files can be pulled individually or as a full tar file from the `FTP data repository -`__ or from `Amazon Web Services (AWS) cloud storage -`__ -and staged on your machine. The paths to the staged files must then be set in ``config.sh`` -as follows: +The environment variables ``FIXgsm``, ``TOPO_DIR``, and ``SFC_CLIMO_INPUT_DIR`` indicate the path to +the directories where the static files are located. If you are on a pre-configured or configurable platform (i.e., a Level 1 or 2 platform), there is no need to stage the fixed files manually because they have been prestaged, and the paths are set in ``regional_workflow/ush/setup.sh``. On Level 3 & 4 systems, the static files can be downloaded individually or as a full tar file from the `FTP data repository `__ or from `Amazon Web Services (AWS) cloud storage `__ using the ``wget`` command. Then ``tar -xf `` will extract the compressed file: + +.. code-block:: console + + wget https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/fix/fix_files.tar.gz + tar -xf fix_files.tar.gz + +The paths to the staged files must then be set in ``config.sh``. Add the following code or alter the variable paths if they are already listed in the ``config.sh`` file: * ``FIXgsm=/path-to/fix/fix_am`` * ``TOPO_DIR=/path-to/fix/fix_am/fix_orog`` @@ -251,25 +224,35 @@ as follows: Initial Condition Formats and Source ------------------------------------ -The SRW Application currently supports raw initial and lateral boundary conditions from numerous models -(i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, netCDF, -or :term:`GRIB2`. The SRW Application currently only supports the use of NEMSIO and netCDF input files -from the GFS. - -Environment variables describe what IC/LBC files to use (pre-staged files or files to be automatically -pulled from the NOAA HPSS) and the location of the and IC/LBC files: ``USE_USER_STAGED_EXTRN_FILES`` -is the ``T/F`` flag defining what raw data files to use, ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` is the -directory where the initial conditions are located, and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` is the -directory where the lateral boundary conditions are located. - -If you have access to the NOAA HPSS and want to automatically download the IC/LBC files using the -workflow, these environment variables can be left out of the ``config.sh`` file. However, if you do -not have access to the NOAA HPSS and you need to pull and stage the data manually, you will need to -set ``USE_USER_STAGED_EXTRN_FILES`` to ``TRUE`` and then set the paths to the where the IC/LBC files are located. - -A small sample of IC/LBCs is available at the `FTP data repository -`__ or from `AWS cloud storage -`_. +The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, netCDF, or :term:`GRIB2`. The SRW Application currently only supports the use of NEMSIO and netCDF input files from the GFS. + +The data required to run the "out-of'the-box" SRW case described in :numref:`Chapter %s ` is already preinstalled on `Level 1 `__ systems. Users on other systems can find the required IC/LBC data in the `FTP data repository `__ or on `AWS cloud storage `_. + +To add this data to your system, run the following commands from the ``ufs-srweather-app`` directory: + +.. code-block:: console + + wget https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/simple_test_case/gst_model_data.tar.gz + tar -xf gst_model_data.tar.gz + +This will extract the files and place them within a new ``model_data`` directory inside the ``ufs-srweather-app``. + +Then, the paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` must be set in the ``config.sh`` file. + +.. code-block:: console + + cd + vi config.sh + +Then, in ``config.sh``, set the following environment variables: + +.. code-block:: console + + USE_USER_STAGED_EXTRN_FILES=TRUE + EXTRN_MDL_SOURCE_BASEDIR_ICS= + EXTRN_MDL_SOURCE_BASEDIR_LBCS= + +These environment variables describe what :term:`IC/LBC` files to use (pre-staged files or files to be automatically pulled from the NOAA HPSS) and the location of the IC/LBC files. ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` is the directory where the initial conditions are located, and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` is the directory where the lateral boundary conditions are located. Initial and Lateral Boundary Condition Organization --------------------------------------------------- @@ -278,10 +261,9 @@ below. While there is flexibility to modify these settings, this will provide th for multiple dates when using the SRW Application workflow. For ease of reusing the ``config.sh`` for multiple dates and cycles, it is recommended to set up -your raw IC/LBC files such that it includes the model name (e.g., FV3GFS, NAM, RAP, HRRR) and -``YYYYMMDDHH``, for example: ``/path-to/model_data/FV3GFS/2019061518``. Since both initial +your raw :term:`IC/LBC` files such that it includes the model name (e.g., FV3GFS, NAM, RAP, HRRR) and ``YYYYMMDDHH``, for example: ``/path-to/model_data/FV3GFS/2019061518``. Since both initial and lateral boundary condition files are necessary, you can also include an ICS and LBCS directory. -The sample IC/LBCs available at the FTP data repository are structured as follows: +The sample IC/LBC's available at the FTP data repository are structured as follows: * ``/path-to/model_data/MODEL/YYYYMMDDHH/ICS`` * ``/path-to/model_data/MODEL/YYYYMMDDHH/LBCS`` @@ -289,8 +271,9 @@ The sample IC/LBCs available at the FTP data repository are structured as follow When files are pulled from the NOAA HPSS, the naming convention looks something like: * FV3GFS (GRIB2): ``gfs.t{cycle}z.pgrb2.0p25.f{fhr}`` -* FV3GFS (NEMSIO): ICs: ``gfs.t{cycle}z.atmanl.nemsio`` and ``gfs.t{cycle}z.sfcanl.nemsio``; - LBCs: ``gfs.t{cycle}z.atmf{fhr}.nemsio`` +* FV3GFS (NEMSIO): + *ICs: ``gfs.t{cycle}z.atmanl.nemsio`` and ``gfs.t{cycle}z.sfcanl.nemsio``; + *LBCs: ``gfs.t{cycle}z.atmf{fhr}.nemsio`` * RAP (GRIB2): ``rap.t{cycle}z.wrfprsf{fhr}.grib2`` * HRRR (GRIB2): ``hrrr.t{cycle}z.wrfprsf{fhr}.grib2`` @@ -313,7 +296,7 @@ Doing this allows for the following to be set in the ``config.sh`` regardless of EXTRN_MDL_SOURCE_BASEDIR_LBCS="/path-to/model_data/RAP" EXTRN_MDL_FILES_LBCS=( "rap.wrfprsf03.grib2" "rap.wrfprsf06.grib2" ) -If you choose to forgo the extra ``ICS`` and ``LBCS`` directory, you may also simply either +If you choose to forgo the extra ``ICS`` and ``LBCS`` directory, you may either rename the original files to remove the cycle or modify the ``config.sh`` to set: .. code-block:: console @@ -327,15 +310,14 @@ The default initial and lateral boundary condition files are set to be a severe from 20190615 at 00 UTC. FV3GFS GRIB2 files are the default model and file format. A tar file (``gst_model_data.tar.gz``) containing the model data for this case is available on EMC's FTP data repository at https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/simple_test_case/. It is -also available on Amazon Web Services (AWS) at -https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/ic/gst_model_data.tar.gz. +also available on Amazon Web Services (AWS) at https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/ic/gst_model_data.tar.gz. Running the App for Different Dates ----------------------------------- If users want to run the SRW Application for dates other than 06-15-2019, you will need to make a change in the case to specify the desired data. This is done by modifying the ``config.sh`` ``DATE_FIRST_CYCL``, ``DATE_LAST_CYCL``, and ``CYCL_HRS`` settings. The -forecast length can be modified by changed the ``FCST_LEN_HRS``. In addition, the lateral +forecast length can be modified by changing the ``FCST_LEN_HRS``. In addition, the lateral boundary interval can be specified using the ``LBC_SPEC_INTVL_HRS`` variable. Users will need to ensure that the initial and lateral boundary condition files are available @@ -346,7 +328,7 @@ Staging Initial Conditions Manually If users want to run the SRW Application with raw model files for dates other than what are currently available on the preconfigured platforms, they need to stage the data manually. The data should be placed in ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. -Raw model files may be available from a number of sources. A few examples are provided here for convenience. +The path to these variables can be set in the ``config.sh`` file. Raw model files are available from a number of sources. A few examples are provided here for convenience. NOMADS: https://nomads.ncep.noaa.gov/pub/data/nccf/com/{model}/prod, where model may be: @@ -392,7 +374,7 @@ GRIB2 and NEMSIO files your directory structure might look like: /path-to/model_data/FV3GFS/YYYYMMDDHH/ICS and LBCS /path-to/model_data/FV3GFS_nemsio/YYYYMMDDHH/ICS and LBCS -If you want to use GRIB2 format files for FV3GFS you must also set two additional environment +If you want to use GRIB2 format files for FV3GFS you must also set additional environment variables, including: .. code-block:: console @@ -411,6 +393,4 @@ that the users share the same ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_S directories. That way, if raw model input files are already on disk for a given date they do not need to be replicated. -The files in the subdirectories of the ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` -directories should be write-protected. This prevents these files from being accidentally modified or deleted. -The directories should generally be group writable so the directory can be shared among multiple users. +The files in the subdirectories of the ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` directories should be write-protected. This prevents these files from being accidentally modified or deleted. The directories should generally be group writable so the directory can be shared among multiple users. diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 0c0782a708..179acdf9e4 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -68,7 +68,7 @@ Clone the develop branch of the UFS-SRW weather application repository: .. code-block:: console - git clone https://github.com/jkbk2004/ufs-srweather-app + git clone -b feature/singularity --single-branch https://github.com/NOAA-EPIC/ufs-srweather-app.git .. COMMENT: This will need to be changed to release branch of the SRW repo once it exists. @@ -202,6 +202,7 @@ Next, edit the new ``config.sh`` file to customize it for your machine. At a min ACCOUNT="none" EXPT_SUBDIR="GST" EXPT_BASEDIR="home/$USER/expt_dirs" + COMPILER="gnu" Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. @@ -243,6 +244,22 @@ For **WCOSS**, edit ``config.sh`` with these WCOSS-specific parameters, and use EXPT_SUBDIR="my_expt_name" +**NOAA Cloud Systems:** + +.. code-block:: console + + MACHINE="" + ACCOUNT="none" + EXPT_SUBDIR="" + EXPT_BASEDIR="lustre/$USER/expt_dirs" + COMPILER="gnu" + USE_USER_STAGED_EXTRN_FILES="TRUE" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/GST/model_data/FV3GFS" + EXTRN_MDL_FILES_ICS=( "gfs.pgrb2.0p25.f000" ) + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/GST/model_data/FV3GFS" + EXTRN_MDL_FILES_LBCS=( "gfs.pgrb2.0p25.f006" "gfs.pgrb2.0p25.f012" ) + + .. _SetUpPythonEnv: Set up the Python and other Environment Parameters @@ -257,8 +274,9 @@ This command will activate the ``regional_workflow``. The user should see ``(reg .. code-block:: console - conda activate regional_workflow - + conda init + source ~/.bashrc + conda activate regional_workflow .. _GenerateWorkflow: From 80519d4731bc209b5fe976247b6ae370e7cecc5f Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 25 Feb 2022 18:47:52 -0500 Subject: [PATCH 036/158] fix I/O doc typos --- docs/UsersGuide/source/InputOutputFiles.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index c508bcda85..4cfae309e8 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -272,8 +272,8 @@ When files are pulled from the NOAA HPSS, the naming convention looks something * FV3GFS (GRIB2): ``gfs.t{cycle}z.pgrb2.0p25.f{fhr}`` * FV3GFS (NEMSIO): - *ICs: ``gfs.t{cycle}z.atmanl.nemsio`` and ``gfs.t{cycle}z.sfcanl.nemsio``; - *LBCs: ``gfs.t{cycle}z.atmf{fhr}.nemsio`` + * ICs: ``gfs.t{cycle}z.atmanl.nemsio`` and ``gfs.t{cycle}z.sfcanl.nemsio``; + * LBCs: ``gfs.t{cycle}z.atmf{fhr}.nemsio`` * RAP (GRIB2): ``rap.t{cycle}z.wrfprsf{fhr}.grib2`` * HRRR (GRIB2): ``hrrr.t{cycle}z.wrfprsf{fhr}.grib2`` From 6f11030326e80e1f93035f10fa90d20721148c30 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 28 Feb 2022 16:52:39 -0500 Subject: [PATCH 037/158] pull updates to hpc-stack docs --- hpc-stack-mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hpc-stack-mod b/hpc-stack-mod index f8b32160eb..66d3cd635c 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit f8b32160eb1c1165a51b2df7479b2e9a158aadfc +Subproject commit 66d3cd635c836930e821a6a500572e81505f25d3 From 999a417f4b26d5bfdb4b375e9ee635607f0a3347 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 28 Feb 2022 19:10:55 -0500 Subject: [PATCH 038/158] pull updates to hpc-stack docs --- docs/UsersGuide/source/InputOutputFiles.rst | 11 +++++------ docs/UsersGuide/source/_static/theme_overrides.css | 1 + hpc-stack-mod | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 4cfae309e8..3ae544e9cc 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -4,7 +4,7 @@ Input and Output Files ====================== This chapter provides an overview of the input and output files needed by the components -of the UFS SRW Application (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`). Links to more detailed documentation for each of the components are provided. +of the UFS SRW Application (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`). Links to more detailed documentation for each of the components are provided. For SRW users who want to jump straight to downloading and staging the files, see :numref:`Section %s `. Input Files =========== @@ -23,13 +23,12 @@ the external model data can be found in :numref:`Section %s `, the workflow generation step (:numref:`Step %s `) links the input data for the pre-processing utilities from a location on disk to the experiment directory. The +When a user runs the SRW Application as described in the Quick Start Guide :numref:`Chapter %s `, :numref:`Step %s Generate the Forecast Experiment ` links the input data for the pre-processing utilities from a location on disk to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here `__. UFS Weather Model ----------------- -The input files for the weather model include both static (fixed) files and grid and date -specific files (terrain, initial conditions, boundary conditions, etc). The static fix files +The input files for the weather model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix files must be staged by the user unless you are running on a Level 1/pre-configured platform, in which case you can link to the existing copy of the data on that machine. See :numref:`Section %s ` for more information. The static, grid, and date-specific files are linked in the experiment directory by the workflow scripts. An extensive description of the input files for the weather model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow, as described in :numref:`Section %s `. Unified Post Processor (UPP) @@ -53,7 +52,7 @@ and are shown in :numref:`Table %s `. .. _TemplateFiles: -.. table:: Template files for a regional workflow. +.. table:: Template Files for a Regional Workflow +-----------------------------+-------------------------------------------------------------+ | **File Name** | **Description** | @@ -68,7 +67,7 @@ and are shown in :numref:`Table %s `. +-----------------------------+-------------------------------------------------------------+ | field_table_[CCPP] | Cycle-independent file that the forecast model reads in at | | | the start of each forecast. It specifies the tracers that | - | | the forecast model will advect. A different field_table | + | | the forecast model will advect. A different field_table | | | may be needed for different CCPP suites. | +-----------------------------+-------------------------------------------------------------+ | FV3.input.yml | YAML configuration file containing the forecast model’s | diff --git a/docs/UsersGuide/source/_static/theme_overrides.css b/docs/UsersGuide/source/_static/theme_overrides.css index 63ee6cc74c..f2b48b594c 100644 --- a/docs/UsersGuide/source/_static/theme_overrides.css +++ b/docs/UsersGuide/source/_static/theme_overrides.css @@ -11,3 +11,4 @@ overflow: visible !important; } } + diff --git a/hpc-stack-mod b/hpc-stack-mod index 66d3cd635c..5e73fc49cd 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 66d3cd635c836930e821a6a500572e81505f25d3 +Subproject commit 5e73fc49cd0053833e78266c15ee996df48ce855 From f07fe8ab05b73da4c2e1729580e8722a5b8768fb Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 28 Feb 2022 19:30:48 -0500 Subject: [PATCH 039/158] fix table wrapping --- docs/UsersGuide/source/Include-HPCInstall.rst | 3 ++- docs/UsersGuide/source/conf.py | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/Include-HPCInstall.rst b/docs/UsersGuide/source/Include-HPCInstall.rst index 097519db2d..b467d96d23 100644 --- a/docs/UsersGuide/source/Include-HPCInstall.rst +++ b/docs/UsersGuide/source/Include-HPCInstall.rst @@ -4,4 +4,5 @@ .. 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 \ No newline at end of file +.. 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/conf.py b/docs/UsersGuide/source/conf.py index d4404bb8b5..4f96cbed60 100644 --- a/docs/UsersGuide/source/conf.py +++ b/docs/UsersGuide/source/conf.py @@ -103,12 +103,13 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] - +#html_static_path = [] +html_static_path = ['_static'] html_context = {} def setup(app): app.add_css_file('custom.css') # may also be an URL + app.add_css_file('theme_overrides.css') # may also be a URL # Custom sidebar templates, must be a dictionary that maps document names # to template names. From b58d66173f77e72dbbd61f5f95f314ed10fa8194 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 3 Mar 2022 14:39:38 -0500 Subject: [PATCH 040/158] updates to QS for cloud --- .gitmodules | 3 -- docs/UsersGuide/source/InputOutputFiles.rst | 2 + docs/UsersGuide/source/Introduction.rst | 3 ++ docs/UsersGuide/source/Quickstart.rst | 46 +++++++++++---------- docs/UsersGuide/source/SRWAppOverview.rst | 22 +++++++++- hpc-stack-mod | 1 - 6 files changed, 49 insertions(+), 28 deletions(-) delete mode 160000 hpc-stack-mod diff --git a/.gitmodules b/.gitmodules index d115eb5c82..e69de29bb2 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +0,0 @@ -[submodule "hpc-stack-mod"] - path = hpc-stack-mod - url = https://github.com/gspetro-NOAA/hpc-stack.git diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 3ae544e9cc..1f298211af 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -6,6 +6,8 @@ Input and Output Files This chapter provides an overview of the input and output files needed by the components of the UFS SRW Application (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`). Links to more detailed documentation for each of the components are provided. For SRW users who want to jump straight to downloading and staging the files, see :numref:`Section %s `. +.. _Input: + Input Files =========== The SRW Application requires numerous input files to run: static datasets (fix files diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 877dee4ada..66e89337af 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -26,6 +26,9 @@ Variables presented as ``AaBbCc123`` in this document typically refer to variabl File paths or code that include angle brackets (e.g., ``env/build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``env/build_aws_gcc.env``). +.. hint:: + To get started running the SRW, see the :ref:`Quick Start Guide ` sections on running the SRW in a container. + Pre-processor Utilities and Initial Conditions ============================================== diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 179acdf9e4..9acd0da091 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -43,26 +43,34 @@ The SRW Application source code is publicly available on GitHub and can be run i Run the UFS SRW in a Singularity Container ------------------------------------------- -Pull the Singularity container: +.. note:: + On NOAA Cloud systems, certain environment variables must be set *before* building the container: + + .. code-block:: console + sudo su + export SINGULARITY_CACHEDIR=/lustre/cache + export SINGULARITY_TEMPDIR=/lustre/tmp -.. code-block:: console + If the ``cache`` and ``tmp`` directories do not exist already, they must be created. - singularity pull ubuntu20.04-epic-srwapp-1.0.sif docker://noaaepic/ubuntu20.04-epic-srwapp:1.0 +.. important:: + ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, tar the file and move it to your ``/contrib`` directory, which is much slower but persistent. -Build the container and make a ``contrib`` directory inside it if one does not already exist: +Build the container: .. code-block:: console - singularity build --sandbox ubuntu20.04-epic-srwapp-1.0 ubuntu20.04-epic-srwapp-1.0.sif - cd ubuntu20.04-epic-srwapp-1.0 - mkdir contrib - cd .. + singularity build --sandbox ubuntu20.04-epic-srwapp-1.0 docker://noaaepic/ubuntu20.04-epic-srwapp:1.0 + +.. note:: + If a ``singularity: command not found`` error message appears, try running: ``module load singularity``. + Start the container and run an interactive shell within it. This command also binds the local home directory to the container so that data can be shared between them. .. code-block:: console - singularity shell -e --writable --bind /:/contrib ubuntu20.04-epic-srwapp-1.0 + singularity shell -e --writable --bind /:/lustre ubuntu20.04-epic-srwapp-1.0 Clone the develop branch of the UFS-SRW weather application repository: @@ -70,8 +78,8 @@ Clone the develop branch of the UFS-SRW weather application repository: git clone -b feature/singularity --single-branch https://github.com/NOAA-EPIC/ufs-srweather-app.git -.. - COMMENT: This will need to be changed to release branch of the SRW repo once it exists. +.. + COMMENT: change repo for release Check out submodules for the SRW Application: @@ -109,7 +117,7 @@ Set up the Build Environment Container Approach -------------------- -If the SRW Application has been built in a container provided by the Earth Prediction Innovation Center (EPIC), set build environments and modules within the `ufs-srweather-app` directory as follows: +If the SRW Application has been built in a container provided by the Earth Prediction Innovation Center (EPIC), set build environments and modules within the ``ufs-srweather-app`` directory as follows: .. code-block:: console @@ -133,11 +141,6 @@ directory to source the appropriate file. On Level 3-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. On systems without Lmod, this process will typically involve commands in the form ``export =``. You may need to use ``setenv`` rather than ``export`` depending on your environment. -.. hint:: - - If the system cannot find a module (i.e., a "module unknown" message appears), check whether the module version numbers match in ``ufs-srweather-app/env/build__.env`` and the ``hpc-stack/stack/stack_custom.yaml``. - - Build the Executables ===================== @@ -155,17 +158,17 @@ From the build directory, run the ``cmake`` command below to set up the ``Makefi cmake .. -DCMAKE_INSTALL_PREFIX=.. make -j 4 >& build.out & -The build will take a few minutes to complete. Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, you should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. +The build will take a few minutes to complete. When it starts, a random number is printed to the console, and when it is done, a ``[1]+ Done`` message is printed to the console when you list the files in ``ufs-srweather-app/bin`` (``[1]+ Exit`` may indicate an error). Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, you should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. .. hint:: - If you do not see a ``ufs-srweather-app/bin`` directory, wait a few more minutes for the build to complete. + If you see the build.out file, but there is no ``ufs-srweather-app/bin`` directory, wait a few more minutes for the build to complete. Download and Stage the Data ============================ The SRW requires input files to run. These include static datasets, initial and boundary conditions -files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :doc:`Input and Output Files `, Section 3. Section 1 contains useful background information on the input files required by the SRW. +files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. .. _GenerateForecast: @@ -302,10 +305,9 @@ An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is csh/tcsh, replace ``export`` with ``setenv`` in the command above. - Run the Workflow Using Rocoto ============================= -The information in this section assumes that Rocoto is available on the desired platform. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: using the ``./launch_FV3LAM_wflow.sh`` or by hand. +The information in this section assumes that Rocoto is available on the desired platform. Rocoto cannot be used when running the workflow within a container. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: using the ``./launch_FV3LAM_wflow.sh`` or by hand. Launch the Rocoto Workflow Using a Script ----------------------------------------------- diff --git a/docs/UsersGuide/source/SRWAppOverview.rst b/docs/UsersGuide/source/SRWAppOverview.rst index 61d9c057f5..1e2c96766f 100644 --- a/docs/UsersGuide/source/SRWAppOverview.rst +++ b/docs/UsersGuide/source/SRWAppOverview.rst @@ -140,9 +140,9 @@ executables listed in :numref:`Table %s ` will be located in th +------------------------+---------------------------------------------------------------------------------+ | make_solo_mosaic | Creates mosaic files with halos | +------------------------+---------------------------------------------------------------------------------+ - | ncep_post | Post-processor for the model output | + | upp.x | Post-processor for the model output | +------------------------+---------------------------------------------------------------------------------+ - | NEMS.exe | UFS Weather Model executable | + | ufs_model | UFS Weather Model executable | +------------------------+---------------------------------------------------------------------------------+ | orog | Generates orography, land mask, and gravity wave drag files from fixed files | +------------------------+---------------------------------------------------------------------------------+ @@ -155,6 +155,24 @@ executables listed in :numref:`Table %s ` will be located in th +------------------------+---------------------------------------------------------------------------------+ | vcoord_gen | Generates hybrid coordinate interface profiles | +------------------------+---------------------------------------------------------------------------------+ + | fvcom_to_FV3 | | + +------------------------+---------------------------------------------------------------------------------+ + | make_hgrid | | + +------------------------+---------------------------------------------------------------------------------+ + | emcsfc_ice_blend | | + +------------------------+---------------------------------------------------------------------------------+ + | emcsfc_snow2mdl | | + +------------------------+---------------------------------------------------------------------------------+ + | global_cycle | | + +------------------------+---------------------------------------------------------------------------------+ + | inland | | + +------------------------+---------------------------------------------------------------------------------+ + | orog_gsl | | + +------------------------+---------------------------------------------------------------------------------+ + | fregrid | | + +------------------------+---------------------------------------------------------------------------------+ + | lakefrac | | + +------------------------+---------------------------------------------------------------------------------+ .. _GridSpecificConfig: diff --git a/hpc-stack-mod b/hpc-stack-mod deleted file mode 160000 index 5e73fc49cd..0000000000 --- a/hpc-stack-mod +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 5e73fc49cd0053833e78266c15ee996df48ce855 From 0b50e046e310e856ad905184fb25e86e1863033d Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 3 Mar 2022 15:06:32 -0500 Subject: [PATCH 041/158] fix QS export statements --- docs/UsersGuide/source/Quickstart.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 9acd0da091..1f35407cfd 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -46,14 +46,13 @@ Run the UFS SRW in a Singularity Container .. note:: On NOAA Cloud systems, certain environment variables must be set *before* building the container: - .. code-block:: console - sudo su - export SINGULARITY_CACHEDIR=/lustre/cache - export SINGULARITY_TEMPDIR=/lustre/tmp + ``sudo su`` + ``export SINGULARITY_CACHEDIR=/lustre/cache`` + ``export SINGULARITY_TEMPDIR=/lustre/tmp`` If the ``cache`` and ``tmp`` directories do not exist already, they must be created. -.. important:: +.. note:: ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, tar the file and move it to your ``/contrib`` directory, which is much slower but persistent. Build the container: @@ -76,7 +75,7 @@ Clone the develop branch of the UFS-SRW weather application repository: .. code-block:: console - git clone -b feature/singularity --single-branch https://github.com/NOAA-EPIC/ufs-srweather-app.git + git clone -b feature/singularity-addition https://github.com/EdwardSnyder-NOAA/ufs-srweather-app .. COMMENT: change repo for release From 8786b3246c47db3b628a0dfa29e00039fd96928f Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 3 Mar 2022 15:09:48 -0500 Subject: [PATCH 042/158] fix QS export statements --- docs/UsersGuide/source/Quickstart.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 1f35407cfd..044d920b65 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -47,7 +47,9 @@ Run the UFS SRW in a Singularity Container On NOAA Cloud systems, certain environment variables must be set *before* building the container: ``sudo su`` + ``export SINGULARITY_CACHEDIR=/lustre/cache`` + ``export SINGULARITY_TEMPDIR=/lustre/tmp`` If the ``cache`` and ``tmp`` directories do not exist already, they must be created. From 3a442d668d66d3d3c564a6966ce44d18884d3705 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 3 Mar 2022 17:15:46 -0500 Subject: [PATCH 043/158] QS edits on bind, config --- docs/UsersGuide/source/Quickstart.rst | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 044d920b65..b4a9c55275 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -46,16 +46,15 @@ Run the UFS SRW in a Singularity Container .. note:: On NOAA Cloud systems, certain environment variables must be set *before* building the container: - ``sudo su`` - - ``export SINGULARITY_CACHEDIR=/lustre/cache`` - - ``export SINGULARITY_TEMPDIR=/lustre/tmp`` + .. code-block:: + + sudo su + export SINGULARITY_CACHEDIR=/lustre/cache + export SINGULARITY_TEMPDIR=/lustre/tmp If the ``cache`` and ``tmp`` directories do not exist already, they must be created. -.. note:: - ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, tar the file and move it to your ``/contrib`` directory, which is much slower but persistent. + ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, tar the file and move it to the ``/contrib`` directory, which is much slower but persistent. Build the container: @@ -67,11 +66,16 @@ Build the container: If a ``singularity: command not found`` error message appears, try running: ``module load singularity``. -Start the container and run an interactive shell within it. This command also binds the local home directory to the container so that data can be shared between them. +Start the container and run an interactive shell within it. This command also binds the local directory to the container so that data can be shared between them. On NOAA systems, the local directory is usually the topmost/base/root directory (e.g., /lustre, /contrib, /work, or /home). Additional directories can be bound by adding another ``--bind /:/`` argument before the name of the container. .. code-block:: console - singularity shell -e --writable --bind /:/lustre ubuntu20.04-epic-srwapp-1.0 + singularity shell -e --writable --bind /:/ ubuntu20.04-epic-srwapp-1.0 + +.. important:: + When binding the two directories, they must have the same name! It may be necessary to create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. + + Be sure to bind the directory that contains the data the experiment will access. Clone the develop branch of the UFS-SRW weather application repository: @@ -202,7 +206,7 @@ Next, edit the new ``config.sh`` file to customize it for your machine. At a min .. code-block:: console - MACHINE="AWS" + MACHINE="SINGULARITY" ACCOUNT="none" EXPT_SUBDIR="GST" EXPT_BASEDIR="home/$USER/expt_dirs" @@ -252,7 +256,7 @@ For **WCOSS**, edit ``config.sh`` with these WCOSS-specific parameters, and use .. code-block:: console - MACHINE="" + MACHINE="SINGULARITY" ACCOUNT="none" EXPT_SUBDIR="" EXPT_BASEDIR="lustre/$USER/expt_dirs" From 0cae1601464d95c8596f502bee542ec6ea40e184 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 4 Mar 2022 10:48:40 -0500 Subject: [PATCH 044/158] add bullet points to notes --- docs/UsersGuide/source/Quickstart.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index b4a9c55275..6007744424 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -52,9 +52,9 @@ Run the UFS SRW in a Singularity Container export SINGULARITY_CACHEDIR=/lustre/cache export SINGULARITY_TEMPDIR=/lustre/tmp - If the ``cache`` and ``tmp`` directories do not exist already, they must be created. + * If the ``cache`` and ``tmp`` directories do not exist already, they must be created. - ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, tar the file and move it to the ``/contrib`` directory, which is much slower but persistent. + * ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, tar the file and move it to the ``/contrib`` directory, which is much slower but persistent. Build the container: @@ -73,9 +73,8 @@ Start the container and run an interactive shell within it. This command also bi singularity shell -e --writable --bind /:/ ubuntu20.04-epic-srwapp-1.0 .. important:: - When binding the two directories, they must have the same name! It may be necessary to create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. - - Be sure to bind the directory that contains the data the experiment will access. + * When binding two directories, they must have the same name. It may be necessary to create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. + * Be sure to bind the directory that contains the data the experiment will access. Clone the develop branch of the UFS-SRW weather application repository: From 27247a5cac1ab30a8968afe05fb62b1538b9cd1a Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 4 Mar 2022 13:59:10 -0500 Subject: [PATCH 045/158] running without rocoto --- docs/UsersGuide/source/Quickstart.rst | 2 +- docs/UsersGuide/source/SRWAppOverview.rst | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 6007744424..a894f580e2 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -196,7 +196,7 @@ Make a copy of ``config.community.sh`` to get started (under `` Date: Fri, 4 Mar 2022 14:11:10 -0500 Subject: [PATCH 046/158] add HPC-Stack submodule w/docs --- .gitmodules | 3 +++ hpc-stack-mod | 1 + 2 files changed, 4 insertions(+) create mode 160000 hpc-stack-mod diff --git a/.gitmodules b/.gitmodules index e69de29bb2..ca914133d5 100644 --- a/.gitmodules +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "hpc-stack-mod"] + path = hpc-stack-mod + url = https://github.com/NOAA-EMC/hpc-stack.git diff --git a/hpc-stack-mod b/hpc-stack-mod new file mode 160000 index 0000000000..0199b163a2 --- /dev/null +++ b/hpc-stack-mod @@ -0,0 +1 @@ +Subproject commit 0199b163a28d410524ebd9586699ca20620aa509 From 29cf292b94ba18eb26b427f1c7064d14f9b35682 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 8 Mar 2022 16:10:34 -0500 Subject: [PATCH 047/158] split QS into container/non-container approaches --- docs/UsersGuide/source/Components.rst | 3 +- docs/UsersGuide/source/FAQ.rst | 2 +- docs/UsersGuide/source/Glossary.rst | 3 + docs/UsersGuide/source/InputOutputFiles.rst | 4 +- docs/UsersGuide/source/Introduction.rst | 6 +- .../source/Quickstart_Container.rst | 306 ++++++++++++++++++ ...kstart.rst => Quickstart_NonContainer.rst} | 98 +----- docs/UsersGuide/source/SRWAppOverview.rst | 63 ++-- docs/UsersGuide/source/WE2Etests.rst | 2 +- docs/UsersGuide/source/index.rst | 3 +- 10 files changed, 365 insertions(+), 125 deletions(-) create mode 100644 docs/UsersGuide/source/Quickstart_Container.rst rename docs/UsersGuide/source/{Quickstart.rst => Quickstart_NonContainer.rst} (85%) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index 9562242a59..50513a303e 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -87,8 +87,7 @@ For the selected computational platforms that have been pre-configured (Level 1) required libraries for building the SRW Application are available in a central place. That means bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) have both been built. The SRW Application is expected to build and run out-of-the-box on these -pre-configured platforms, and users can proceed directly to the using the workflow, as -described in the Quick Start (:numref:`Section %s `). +pre-configured platforms. Users can download the SRW code and choose whether to run it :ref:`in a container ` or :ref:`locally `. A few additional computational platforms are considered configurable for the SRW Application release. Configurable platforms (Level 2) are platforms where all of the required libraries for building the SRW Application are expected to install successfully but are not available in a central location. Applications and models are expected to build and run once the required bundled libraries (e.g., NCEPLIBS) and third-party libraries (e.g., NCEPLIBS-external) are built. diff --git a/docs/UsersGuide/source/FAQ.rst b/docs/UsersGuide/source/FAQ.rst index 05313a998c..ee744db726 100644 --- a/docs/UsersGuide/source/FAQ.rst +++ b/docs/UsersGuide/source/FAQ.rst @@ -36,7 +36,7 @@ run the ``make_grid``, ``make_orog``, and ``make_sfc_climo`` tasks. How do I define an experiment name? =================================== The name of the experiment is set in the ``config.sh`` file using the variable ``EXPT_SUBDIR``. -See :numref:`Section %s ` for more details. +See :numref:`Section %s ` for more details. ================================================ How do I change the Suite Definition File (SDF)? diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index f426ac8a9c..dbac0aca42 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -43,6 +43,9 @@ Glossary LAM Limited Area Model. LAM grids use a regional (rather than global) configuration of the FV3 dynamical core. + MPI + MPI stands for Message Passing Interface. An MPI is a standardized communication system used in parallel programming. It establishes portable and efficient syntax for the exchange of messages and data between multiple processors that are used by a single computer program. An MPI is required for high-performance computing (HPC). + NAM `North American Mesoscale Forecast System `_. NAM generates multiple grids (or domains) of weather forecasts over the North American continent at various horizontal resolutions. Each grid contains data for dozens of weather parameters, including temperature, precipitation, lightning, and turbulent kinetic energy. NAM uses additional numerical weather models to generate high-resolution forecasts over fixed regions, and occasionally to follow significant weather events like hurricanes. diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 1f298211af..65883c796f 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -25,7 +25,7 @@ the external model data can be found in :numref:`Section %s `, :numref:`Step %s Generate the Forecast Experiment ` links the input data for the pre-processing utilities from a location on disk to the experiment directory. The +When a user runs the SRW Application as described in the Quick Start Guide :numref:`Chapter %s `, :numref:`Step %s Generate the Forecast Experiment ` links the input data for the pre-processing utilities from a location on disk to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here `__. UFS Weather Model @@ -227,7 +227,7 @@ Initial Condition Formats and Source ------------------------------------ The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, netCDF, or :term:`GRIB2`. The SRW Application currently only supports the use of NEMSIO and netCDF input files from the GFS. -The data required to run the "out-of'the-box" SRW case described in :numref:`Chapter %s ` is already preinstalled on `Level 1 `__ systems. Users on other systems can find the required IC/LBC data in the `FTP data repository `__ or on `AWS cloud storage `_. +The data required to run the "out-of'the-box" SRW case described in :numref:`Chapter %s ` is already preinstalled on `Level 1 `__ systems. Users on other systems can find the required IC/LBC data in the `FTP data repository `__ or on `AWS cloud storage `_. To add this data to your system, run the following commands from the ``ufs-srweather-app`` directory: diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 66e89337af..0a4ba41d9a 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -6,7 +6,7 @@ Introduction The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. -The UFS can be configured for multiple applications (see the `complete list here `__). The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a :ref:`Quick Start Guide ` for running the application, in addition to an overview of the :ref:`release components `, a description of the supported capabilities, and details on where to find more information and obtain support. +The UFS can be configured for multiple applications (see the `complete list here `__). The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides two Quick Start Guides for running the application :ref:`in a conainer ` or :ref:`locally `, in addition to an overview of the :ref:`release components `, a description of the supported capabilities, and details on where to find more information and obtain support. The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research conducted with the App: @@ -27,7 +27,7 @@ Variables presented as ``AaBbCc123`` in this document typically refer to variabl File paths or code that include angle brackets (e.g., ``env/build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``env/build_aws_gcc.env``). .. hint:: - To get started running the SRW, see the :ref:`Quick Start Guide ` sections on running the SRW in a container. + To get started running the SRW, see the :ref:`Containerized Quick Start Guide `. Pre-processor Utilities and Initial Conditions @@ -76,7 +76,7 @@ The SRW Application has a portable CMake-based build system that packages togeth The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. -This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can proceed directly to using the workflow to generate an experiment, as described in the Quick Start Guide :numref:`Section %s Generate the Forecast Experiment `. On other platforms, the required libraries will need to be installed via the HPC-Stack (see :numref:`Section %s Installing the HPC-Stack `). Once these libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW code ` without first installing prerequisites. On other platforms, the SRW must be :ref:`run within a container ` that contains the HPC-Stack, or the required libraries (i.e., HPC-Stack) will need to be installed as part of the :ref:`non-container `) SRW installation process. Once these prerequisite libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. User Support, Documentation, and Contributions to Development =============================================================== diff --git a/docs/UsersGuide/source/Quickstart_Container.rst b/docs/UsersGuide/source/Quickstart_Container.rst new file mode 100644 index 0000000000..c8ae4cafca --- /dev/null +++ b/docs/UsersGuide/source/Quickstart_Container.rst @@ -0,0 +1,306 @@ +.. _QuickstartC: + +================================================= +Containerized Workflow Quick Start (Recommended) +================================================= + +This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a container. The container approach provides a uniform enviroment in which to build and run the SRW. Normally, the details of building and running the SRW vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions. Installation via an EPIC-provided container reduces this variability and allows for a smoother SRW build and run experience. + +The "out-of-the-box" SRW case described in this guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. + +.. _DownloadCodeC: + +Download the UFS SRW Application Code +=========================================== +The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. + +Working in the Cloud +----------------------- + +Users building the SRW using NOAA's Cloud resources must complete a few additional steps to ensure the SRW builds and runs correctly. For those working on non-cloud-based systems, skip to :numref:`Step %s `. + +On NOAA Cloud systems, certain environment variables must be set *before* building the container: + +.. code-block:: + + sudo su + export SINGULARITY_CACHEDIR=/lustre/cache + export SINGULARITY_TEMPDIR=/lustre/tmp + +* If the ``cache`` and ``tmp`` directories do not exist already, they must be created. + +* ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, `tar the file `__ and move it to the ``/contrib`` directory, which is much slower but persistent. + +On NOAA Cloud systems, allocate a compute node on which to run the SRW. Then, build and run the SRW from that node: + +.. code-block:: console + + salloc -N 1 + module load gnu openmpi + mpirun -n 1 hostname + +This last command will output a hostname. Next, run ``ssh ``, replacing ```` with the actual hostname output in the prior command. + +.. _BuildC: + +Set Up the Container +------------------------ + +Build the container: + +.. code-block:: console + + singularity build --sandbox ubuntu20.04-epic-srwapp-1.0 docker://noaaepic/ubuntu20.04-epic-srwapp:1.0 + +.. hint:: + If a ``singularity: command not found`` error message appears, try running: ``module load singularity``. + +Start the container and run an interactive shell within it: + +.. code-block:: console + + singularity shell -e --writable --bind /:/ ubuntu20.04-epic-srwapp-1.0 + +The command above also binds the local directory to the container so that data can be shared between them. On NOAA systems, the local directory is usually the topmost directory (e.g., /lustre, /contrib, /work, or /home). Additional directories can be bound by adding another ``--bind /:/`` argument before the name of the container. + +.. important:: + * When binding two directories, they must have the same name. It may be necessary to ``cd`` into the container and create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. + * Be sure to bind the directory that contains the data the experiment will access. + +Download the SRW Code +------------------------ + +Clone the develop branch of the UFS-SRW weather application repository: + +.. code-block:: console + + git clone -b feature/singularity-addition https://github.com/EdwardSnyder-NOAA/ufs-srweather-app + +.. + COMMENT: change repo for release + +Check out submodules for the SRW Application: + +.. code-block:: console + + cd ufs-srweather-app + ./manage_externals/checkout_externals + +If the ``manage_externals`` command brings up an error, it may be necessary to run ``ln -s /usr/bin/python3 /usr/bin/python`` first. + + +.. _SetUpBuildC: + +Set up the Build Environment +============================ + +If the SRW Application has been built in a container provided by the Earth Prediction Innovation Center (EPIC), set build environments and modules within the ``ufs-srweather-app`` directory as follows: + +.. code-block:: console + + ln -s /usr/bin/python3 /usr/bin/python + source /usr/share/lmod/6.6/init/profile + module use /opt/hpc-modules/modulefiles/stack + module load hpc hpc-gnu hpc-openmpi hpc-python + module load netcdf hdf5 bacio sfcio sigio nemsio w3emc esmf fms crtm g2 png zlib g2tmpl ip sp w3nco cmake gfsio wgrib2 upp + + + +Build the Executables +===================== + +Create a directory to hold the build's executables: + +.. code-block:: console + + mkdir build + cd build + +From the build directory, run the ``cmake`` command below to set up the ``Makefile``, then run the ``make`` command to build the executables: + +.. code-block:: console + + cmake .. -DCMAKE_INSTALL_PREFIX=.. + make -j 4 >& build.out & + +The build will take a few minutes to complete. When it starts, a random number is printed to the console, and when it is done, a ``[1]+ Done`` message is printed to the console when you list the files in ``ufs-srweather-app/bin`` (``[1]+ Exit`` may indicate an error). Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, you should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. + +.. hint:: + + If you see the build.out file, but there is no ``ufs-srweather-app/bin`` directory, wait a few more minutes for the build to complete. + +Download and Stage the Data +============================ + +The SRW requires input files to run. These include static datasets, initial and boundary conditions +files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. + +.. _GenerateForecastC: + +Generate the Forecast Experiment +================================= +Generating the forecast experiment requires three steps: + +* Set experiment parameters +* Set Python and other environment parameters +* Run a script to generate the experiment workflow + +The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. + +.. _SetUpConfigFileC: + +Set Experiment Parameters +------------------------- +Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in the ``config.sh`` file. Two example ``config.sh`` templates are provided: ``config.community.sh`` and ``config.nco.sh``. They can be found in the ``ufs-srweather-app/regional_workflow/ush`` directory. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. + +Make a copy of ``config.community.sh`` to get started (under ``/regional_workflow/ush``). From the ``ufs-srweather-app`` directory, run: + +.. code-block:: console + + cd ../regional_workflow/ush + cp config.community.sh config.sh + +The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. + +Next, edit the new ``config.sh`` file to customize it for your machine. At a minimum, change the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If you have pre-staged the initialization data for the experiment, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and set the paths to the data for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. For example: + +.. code-block:: console + + MACHINE="SINGULARITY" + ACCOUNT="none" + EXPT_SUBDIR="GST" + EXPT_BASEDIR="home/$USER/expt_dirs" + COMPILER="gnu" + +Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. + +.. Important:: + + If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. + +Minimum parameter settings for Level 1 machines: + +**Cheyenne:** + +.. code-block:: console + + MACHINE="cheyenne" + ACCOUNT="" + EXPT_SUBDIR="" + USE_USER_STAGED_EXTRN_FILES="TRUE" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_app/model_data/FV3GFS" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_app/model_data/FV3GFS" + +**Hera:** + +.. code-block:: console + + MACHINE="hera" + ACCOUNT="" + EXPT_SUBDIR="" + +**Jet, Orion, Gaea:** + +The settings are the same as for Hera, except that ``"hera"`` should be switched to ``"jet"``, ``"orion"``, or ``"gaea"``, respectively. + +For **WCOSS**, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: + +.. code-block:: console + + MACHINE=”wcoss_cray” or MACHINE=”wcoss_dell_p3” + ACCOUNT="my_account" + EXPT_SUBDIR="my_expt_name" + + +**NOAA Cloud Systems:** + +.. code-block:: console + + MACHINE="SINGULARITY" + ACCOUNT="none" + EXPT_SUBDIR="" + EXPT_BASEDIR="lustre/$USER/expt_dirs" + COMPILER="gnu" + USE_USER_STAGED_EXTRN_FILES="TRUE" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/GST/model_data/FV3GFS" + EXTRN_MDL_FILES_ICS=( "gfs.pgrb2.0p25.f000" ) + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/GST/model_data/FV3GFS" + EXTRN_MDL_FILES_LBCS=( "gfs.pgrb2.0p25.f006" "gfs.pgrb2.0p25.f012" ) + + +.. _SetUpPythonEnvC: + +Activate the Regional Workflow +---------------------------------------------- +Next, activate the regional workflow. + +.. code-block:: console + + conda init + source ~/.bashrc + conda activate regional_workflow + +The user should see ``(regional_workflow)`` in front of the Terminal prompt at this point. + + +.. _GenerateWorkflowC: + +Generate the Regional Workflow +------------------------------------------- + +Run the following command to generate the workflow: + +.. code-block:: console + + ./generate_FV3LAM_wflow.sh + +This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The last line of output from this script should start with ``*/1 * * * *`` or ``*/3 * * * *``. + +The generated workflow will be in experiment directory specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in the experiment directory. + +Run the Workflow Using Stand-Alone Scripts +============================================= + +.. note:: + The Rocoto workflow manager cannot be used inside a container. + +#. ``cd`` into the experiment directory + +#. Set the environment variable ``EXPTDIR`` for either bash or csh, respectively: + + .. code-block:: console + + export EXPTDIR=`pwd` + setenv EXPTDIR `pwd` + +#. COPY the wrapper scripts from the regional_workflow directory into your experiment directory: + + .. code-block:: console + + cp ufs-srweather-app/regional_workflow/ush/wrappers/* . + +#. Set the OMP_NUM_THREADS variable and fix dash/bash shell issue (this ensures the system does not use an alias of ``sh`` to dash). + + .. code-block:: console + + export OMP_NUM_THREADS=1 + sed -i 's/bin\/sh/bin\/bash/g' *sh + +#. RUN each of the listed scripts in order. Scripts with the same stage number (listed in :numref:`Table %s `) may be run simultaneously. + + .. code-block:: console + + ./run_make_grid.sh + ./run_get_ics.sh + ./run_get_lbcs.sh + ./run_make_orog.sh + ./run_make_sfc_climo.sh + ./run_make_ics.sh + ./run_make_lbcs.sh + ./run_fcst.sh + ./run_post.sh + + +Plot the Output +=============== +Two python scripts are provided to generate plots from the FV3-LAM post-processed GRIB2 output. Information on how to generate the graphics can be found in :numref:`Chapter %s `. diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart_NonContainer.rst similarity index 85% rename from docs/UsersGuide/source/Quickstart.rst rename to docs/UsersGuide/source/Quickstart_NonContainer.rst index a894f580e2..ad6c20ee04 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart_NonContainer.rst @@ -1,8 +1,8 @@ -.. _Quickstart: +.. _QuickstartNC: -==================== -Workflow Quick Start -==================== +====================================== +Workflow Quick Start (Non-Container) +====================================== This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application. The "out-of-the-box" case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. @@ -10,6 +10,9 @@ This Workflow Quick Start Guide will help users to build and run the "out-of-the The UFS defines `four platform levels `_. The steps described in this chapter are most applicable to preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems as well but may require additional troubleshooting by the user. +.. note:: + The :ref:`container approach ` is recommended when possible for a smoother build and run experience. Building without a container allows for use of the Rocoto workflow manager and may allow for more cutomization; however, this comes at the expense of more in-depth troubleshooting, especially on Level 3 and 4 systems. + .. _HPCstackInfo: @@ -34,69 +37,12 @@ Users can either build the HPC-stack on their local system or use the centrally After completing installation, continue to the next section. -.. _DownloadCode: +.. _DownloadCodeNC: Download the UFS SRW Application Code ===================================== The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. -Run the UFS SRW in a Singularity Container -------------------------------------------- - -.. note:: - On NOAA Cloud systems, certain environment variables must be set *before* building the container: - - .. code-block:: - - sudo su - export SINGULARITY_CACHEDIR=/lustre/cache - export SINGULARITY_TEMPDIR=/lustre/tmp - - * If the ``cache`` and ``tmp`` directories do not exist already, they must be created. - - * ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, tar the file and move it to the ``/contrib`` directory, which is much slower but persistent. - -Build the container: - -.. code-block:: console - - singularity build --sandbox ubuntu20.04-epic-srwapp-1.0 docker://noaaepic/ubuntu20.04-epic-srwapp:1.0 - -.. note:: - If a ``singularity: command not found`` error message appears, try running: ``module load singularity``. - - -Start the container and run an interactive shell within it. This command also binds the local directory to the container so that data can be shared between them. On NOAA systems, the local directory is usually the topmost/base/root directory (e.g., /lustre, /contrib, /work, or /home). Additional directories can be bound by adding another ``--bind /:/`` argument before the name of the container. - -.. code-block:: console - - singularity shell -e --writable --bind /:/ ubuntu20.04-epic-srwapp-1.0 - -.. important:: - * When binding two directories, they must have the same name. It may be necessary to create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. - * Be sure to bind the directory that contains the data the experiment will access. - -Clone the develop branch of the UFS-SRW weather application repository: - -.. code-block:: console - - git clone -b feature/singularity-addition https://github.com/EdwardSnyder-NOAA/ufs-srweather-app - -.. - COMMENT: change repo for release - -Check out submodules for the SRW Application: - -.. code-block:: console - - cd ufs-srweather-app - ./manage_externals/checkout_externals - -If the ``manage_externals`` command brings up an error, it may be necessary to run ``ln -s /usr/bin/python3 /usr/bin/python`` first. - -Run the UFS SRW Without a Container ------------------------------------- - Clone the release branch of the repository: .. code-block:: console @@ -114,27 +60,11 @@ Then, run the executable that pulls in the submodules for the SRW Application: ./manage_externals/checkout_externals -.. _SetUpBuild: +.. _SetUpBuildNC: Set up the Build Environment ============================ -Container Approach --------------------- -If the SRW Application has been built in a container provided by the Earth Prediction Innovation Center (EPIC), set build environments and modules within the ``ufs-srweather-app`` directory as follows: - -.. code-block:: console - - ln -s /usr/bin/python3 /usr/bin/python - source /usr/share/lmod/6.6/init/profile - module use /opt/hpc-modules/modulefiles/stack - module load hpc hpc-gnu hpc-openmpi hpc-python - module load netcdf hdf5 bacio sfcio sigio nemsio w3emc esmf fms crtm g2 png zlib g2tmpl ip sp w3nco cmake gfsio wgrib2 upp - - -On Other Systems (Non-Container Approach) ------------------------------------------- - For Level 1 and 2 systems, scripts for loading the proper modules and/or setting the correct environment variables can be found in the ``env/`` directory of the SRW App in files named ``build__.env``. The commands in these files can be directly copy-pasted @@ -174,7 +104,7 @@ Download and Stage the Data The SRW requires input files to run. These include static datasets, initial and boundary conditions files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. -.. _GenerateForecast: +.. _GenerateForecastNC: Generate the Forecast Experiment ================================= @@ -186,7 +116,7 @@ Generating the forecast experiment requires three steps: The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. -.. _SetUpConfigFile: +.. _SetUpConfigFileNC: Set Experiment Parameters ------------------------- @@ -215,7 +145,7 @@ Sample settings are indicated below for Level 1 platforms. Detailed guidance app .. Important:: - If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. + If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. Minimum parameter settings for Level 1 machines: @@ -286,7 +216,7 @@ This command will activate the ``regional_workflow``. The user should see ``(reg conda activate regional_workflow -.. _GenerateWorkflow: +.. _GenerateWorkflowNC: Generate the Regional Workflow ------------------------------------------- @@ -299,7 +229,7 @@ Run the following command to generate the workflow: The last line of output from this script, starting with ``*/1 * * * *``, can be saved and :ref:`used later ` to automatically run portions of the workflow. -This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in $EXPTDIR. +This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in $EXPTDIR. An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: diff --git a/docs/UsersGuide/source/SRWAppOverview.rst b/docs/UsersGuide/source/SRWAppOverview.rst index c93b9e8a28..9810f9955b 100644 --- a/docs/UsersGuide/source/SRWAppOverview.rst +++ b/docs/UsersGuide/source/SRWAppOverview.rst @@ -155,23 +155,23 @@ executables listed in :numref:`Table %s ` will be located in th +------------------------+---------------------------------------------------------------------------------+ | vcoord_gen | Generates hybrid coordinate interface profiles | +------------------------+---------------------------------------------------------------------------------+ - | fvcom_to_FV3 | | + | fvcom_to_FV3 | | +------------------------+---------------------------------------------------------------------------------+ - | make_hgrid | | + | make_hgrid | | +------------------------+---------------------------------------------------------------------------------+ - | emcsfc_ice_blend | | + | emcsfc_ice_blend | | +------------------------+---------------------------------------------------------------------------------+ - | emcsfc_snow2mdl | | + | emcsfc_snow2mdl | | +------------------------+---------------------------------------------------------------------------------+ - | global_cycle | | + | global_cycle | | +------------------------+---------------------------------------------------------------------------------+ - | inland | | + | inland | | +------------------------+---------------------------------------------------------------------------------+ - | orog_gsl | | + | orog_gsl | | +------------------------+---------------------------------------------------------------------------------+ - | fregrid | | + | fregrid | | +------------------------+---------------------------------------------------------------------------------+ - | lakefrac | | + | lakefrac | | +------------------------+---------------------------------------------------------------------------------+ .. _GridSpecificConfig: @@ -640,20 +640,11 @@ Wait a few seconds and issue a second set of ``rocotorun`` and ``rocotostat`` co Run the Workflow Using the Stand-alone Scripts ---------------------------------------------- -The regional workflow has the capability to be run using standalone shell scripts if the -Rocoto software is not available on a given platform. These scripts are located in the -``ufs-srweather-app/regional_workflow/ush/wrappers`` directory. Each workflow task has -a wrapper script to set environment variables and run the job script. +The regional workflow has the capability to be run using standalone shell scripts if the Rocoto software is not available on a given platform. These scripts are located in the ``ufs-srweather-app/regional_workflow/ush/wrappers`` directory. Each workflow task has a wrapper script to set environment variables and run the job script. Example batch-submit scripts for Hera (Slurm) and Cheyenne (PBS) are included: ``sq_job.sh`` -and ``qsub_job.sh``, respectively. These examples set the build and run environment for Hera or Cheyenne -so that run-time libraries match the compiled libraries (i.e. netCDF, MPI). Users may either -modify the submit batch script as each task is submitted, or duplicate this batch wrapper -for their system settings for each task. Alternatively, some batch systems allow users to -specify most of the settings on the command line (with the ``sbatch`` or ``qsub`` command, -for example). This piece will be unique to your platform. The tasks run by the regional workflow -are shown in :numref:`Table %s `. Tasks with the same stage level may -be run concurrently (no dependency). +and ``qsub_job.sh``, respectively. These examples set the build and run environment for Hera or Cheyenne so that run-time libraries match the compiled libraries (i.e. netCDF, MPI). Users may either modify the submit batch script as each task is submitted, or duplicate this batch wrapper +for their system settings for each task. Alternatively, some batch systems allow users to specify most of the settings on the command line (with the ``sbatch`` or ``qsub`` command, for example). This piece will be unique to your platform. The tasks run by the regional workflow are shown in :numref:`Table %s `. Tasks with the same stage level may be run concurrently (no dependency). .. _RegionalWflowTasks: @@ -713,15 +704,14 @@ The steps to run the standalone scripts are as follows: cp ufs-srweather-app/regional_workflow/ush/wrappers/* . -#. f00 +#. Set the OMP_NUM_THREADS variable and fix dash/bash shell issue (this ensures the system does not use an alias of ``sh`` to dash). -.. code-block:: + .. code-block:: console - export OMP_NUM_THREADS=1 - sed -i 's/bin\/sh/bin\/bash/g' *sh + export OMP_NUM_THREADS=1 + sed -i 's/bin\/sh/bin\/bash/g' *sh -#. RUN each of the listed scripts in order. Scripts with the same stage number - may be run simultaneously. +#. RUN each of the listed scripts in order. Scripts with the same stage number (listed in :numref:`Table %s `) may be run simultaneously. .. code-block:: console @@ -735,14 +725,25 @@ The steps to run the standalone scripts are as follows: ./run_fcst.sh ./run_post.sh + .. note:: + If any of the scripts return an error that "Primary job terminated normally, but one process returned a non-zero exit code," there may not be enough space on one node to run the process. To allocate a second node: + + .. code-block:: console + + salloc -N 1 + module load gnu openmpi + mpirun -n 1 hostname + + This last command will output a hostname. Then, run ``ssh ``, replacing ```` with the actual hostname output in the prior command. + - #. On most HPC systems, you will need to submit a batch job to run multi-processor jobs. + #. On most HPC systems, you will need to submit a batch job to run multi-processor jobs. - #. On some HPC systems, you may be able to run the first two jobs (serial) on a login node/command-line + #. On some HPC systems, you may be able to run the first two jobs (serial) on a login node/command-line - #. Example scripts for Slurm (Hera) and PBS (Cheyenne) are provided. These will need to be adapted to your system. + #. Example scripts for Slurm (Hera) and PBS (Cheyenne) are provided. These will need to be adapted to your system. - #. This submit batch script is hard-coded per task, so will need to be modified or copied to run each task. + #. This submit batch script is hard-coded per task, so will need to be modified or copied to run each task. Check the batch script output file in your experiment directory for a “SUCCESS” message near the end of the file. diff --git a/docs/UsersGuide/source/WE2Etests.rst b/docs/UsersGuide/source/WE2Etests.rst index 7332bc4b5f..3afa207d2a 100644 --- a/docs/UsersGuide/source/WE2Etests.rst +++ b/docs/UsersGuide/source/WE2Etests.rst @@ -15,7 +15,7 @@ in the file ``testlist.release_public_v1.txt``. The base experiment configuration file for each test is located in the ``baseline_configs`` subdirectory. Each file is named ``config.${expt_name}.sh``, where ``${expt_name}`` is the name of the corresponding test configuration. These base configuration files are subsets of -the full ``config.sh`` experiment configuration file used in :numref:`Section %s ` +the full ``config.sh`` experiment configuration file used in :numref:`Section %s ` and described in :numref:`Section %s `. For each test that the user wants to run, the ``run_experiments.sh`` script reads in its base configuration file and generates from it a full ``config.sh`` file (a copy of which is placed in the experiment directory for the test). diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index 96ac2e51c4..290b1ec482 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -12,7 +12,8 @@ UFS Short-Range Weather App Users Guide Introduction - Quickstart + Quickstart_Container + Quickstart_NonContainer CodeReposAndDirs SRWAppOverview Components From 3e300980ed04e41b2a9a3287855485eab5fe79bc Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 9 Mar 2022 16:50:09 -0500 Subject: [PATCH 048/158] added filepath changes for running in container on Orion, et al. --- docs/UsersGuide/source/InputOutputFiles.rst | 2 + .../source/Quickstart_Container.rst | 97 +++++++++---------- .../source/Quickstart_NonContainer.rst | 2 +- 3 files changed, 49 insertions(+), 52 deletions(-) diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 65883c796f..d1079c78fb 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -223,6 +223,8 @@ The paths to the staged files must then be set in ``config.sh``. Add the followi * ``TOPO_DIR=/path-to/fix/fix_am/fix_orog`` * ``SFC_CLIMO_INPUT_DIR=/path-to/fix_am/fix/sfc_climo/`` +.. _InitialConditions: + Initial Condition Formats and Source ------------------------------------ The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, netCDF, or :term:`GRIB2`. The SRW Application currently only supports the use of NEMSIO and netCDF input files from the GFS. diff --git a/docs/UsersGuide/source/Quickstart_Container.rst b/docs/UsersGuide/source/Quickstart_Container.rst index c8ae4cafca..87b65a31a6 100644 --- a/docs/UsersGuide/source/Quickstart_Container.rst +++ b/docs/UsersGuide/source/Quickstart_Container.rst @@ -14,6 +14,15 @@ Download the UFS SRW Application Code =========================================== The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. +Prerequisites: 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 HPC's. Therefore, it is not possible to build the HPC-Stack inside a Docker container on an HPC system. A Docker image may be pulled, but it must be run inside a container such as Singularity. + + Working in the Cloud ----------------------- @@ -63,7 +72,7 @@ Start the container and run an interactive shell within it: The command above also binds the local directory to the container so that data can be shared between them. On NOAA systems, the local directory is usually the topmost directory (e.g., /lustre, /contrib, /work, or /home). Additional directories can be bound by adding another ``--bind /:/`` argument before the name of the container. -.. important:: +.. attention:: * When binding two directories, they must have the same name. It may be necessary to ``cd`` into the container and create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. * Be sure to bind the directory that contains the data the experiment will access. @@ -74,7 +83,7 @@ Clone the develop branch of the UFS-SRW weather application repository: .. code-block:: console - git clone -b feature/singularity-addition https://github.com/EdwardSnyder-NOAA/ufs-srweather-app + git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git .. COMMENT: change repo for release @@ -141,9 +150,9 @@ Generate the Forecast Experiment ================================= Generating the forecast experiment requires three steps: -* Set experiment parameters -* Set Python and other environment parameters -* Run a script to generate the experiment workflow +* :ref:`Set experiment parameters ` +* :ref:`Set Python and other environment parameters ` +* :ref:`Run a script to generate the experiment workflow ` The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. @@ -162,71 +171,57 @@ Make a copy of ``config.community.sh`` to get started (under ```, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. - -.. Important:: +Additionally, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and add the correct paths to the data. The following is a sample for a 48-hour forecast: - If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. +.. code-block:: -Minimum parameter settings for Level 1 machines: - -**Cheyenne:** - -.. code-block:: console - - MACHINE="cheyenne" - ACCOUNT="" - EXPT_SUBDIR="" USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_app/model_data/FV3GFS" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_app/model_data/FV3GFS" - -**Hera:** - -.. code-block:: console - - MACHINE="hera" - ACCOUNT="" - EXPT_SUBDIR="" - -**Jet, Orion, Gaea:** + EXTRN_MDL_SOURCE_BASEDIR_ICS="/path/to/model_data/FV3GFS" + EXTRN_MDL_FILES_ICS=( "gfs.pgrb2.0p25.f000" ) + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/path/to/model_data/FV3GFS" + EXTRN_MDL_FILES_LBCS=( "gfs.pgrb2.0p25.f006" "gfs.pgrb2.0p25.f012" "gfs.pgrb2.0p25.f018" "gfs.pgrb2.0p25.f024" \ "gfs.pgrb2.0p25.f030" "gfs.pgrb2.0p25.f036" "gfs.pgrb2.0p25.f042" "gfs.pgrb2.0p25.f048" ) -The settings are the same as for Hera, except that ``"hera"`` should be switched to ``"jet"``, ``"orion"``, or ``"gaea"``, respectively. +On Level 1 systems, ``/path/to/model_data/FV3GFS`` should correspond to the location of the machine's global data. Alternatively, the user can add the path to their local data if they downloaded it as described in :numref:`Step %s `. -For **WCOSS**, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: +On NOAA Cloud platforms, users may continue to the :ref:`next step `. On other Level 1 systems, additional file paths must be set: -.. code-block:: console + #. From the ``regional_workflow/ush`` directory, run: ``cd machine``. + #. Open the file corresponding to the Level 1 platform in use (e.g., ``vi orion.sh``). + #. Copy the section of code starting after ``#UFS SRW App specific paths``. For example, on Orion, the following text must be copied: - MACHINE=”wcoss_cray” or MACHINE=”wcoss_dell_p3” - ACCOUNT="my_account" - EXPT_SUBDIR="my_expt_name" + .. code-block:: console + FIXgsm=${FIXgsm:-"/work/noaa/global/glopara/fix/fix_am"} + FIXaer=${FIXaer:-"/work/noaa/global/glopara/fix/fix_aer"} + FIXlut=${FIXlut:-"/work/noaa/global/glopara/fix/fix_lut"} + TOPO_DIR=${TOPO_DIR:-"/work/noaa/global/glopara/fix/fix_orog"} + SFC_CLIMO_INPUT_DIR=${SFC_CLIMO_INPUT_DIR:-"/work/noaa/global/glopara/fix/fix_sfc_climo"} + FIXLAM_NCO_BASEDIR=${FIXLAM_NCO_BASEDIR:-"/needs/to/be/specified"} -**NOAA Cloud Systems:** + #. Exit the system-specific file and open the ``singularity.sh`` file. + #. Comment out or delete the corresponding chunk of text in the ``singularity.sh`` file, and paste the correct paths from the system-specific file in its place. For example, on Orion, delete the text below, and replace it with the Orion-specific text copied in the previous step. -.. code-block:: console + .. code-block:: console - MACHINE="SINGULARITY" - ACCOUNT="none" - EXPT_SUBDIR="" - EXPT_BASEDIR="lustre/$USER/expt_dirs" - COMPILER="gnu" - USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/GST/model_data/FV3GFS" - EXTRN_MDL_FILES_ICS=( "gfs.pgrb2.0p25.f000" ) - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/GST/model_data/FV3GFS" - EXTRN_MDL_FILES_LBCS=( "gfs.pgrb2.0p25.f006" "gfs.pgrb2.0p25.f012" ) + # UFS SRW App specific paths + FIXgsm=${FIXgsm:-"/contrib/global/glopara/fix/fix_am"} + FIXaer=${FIXaer:-"/contrib/global/glopara/fix/fix_aer"} + FIXlut=${FIXlut:-"/contrib/global/glopara/fix/fix_lut"} + TOPO_DIR=${TOPO_DIR:-"/contrib/global/glopara/fix/fix_orog"} + SFC_CLIMO_INPUT_DIR=${SFC_CLIMO_INPUT_DIR:-"/contrib/global/glopara/fix/fix_sfc_climo"} + FIXLAM_NCO_BASEDIR=${FIXLAM_NCO_BASEDIR:-"/needs/to/be/specified"} +From here, it should be possible to continue to the :ref:`next step ` on Level 1 systems. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. .. _SetUpPythonEnvC: diff --git a/docs/UsersGuide/source/Quickstart_NonContainer.rst b/docs/UsersGuide/source/Quickstart_NonContainer.rst index ad6c20ee04..4339c5ab79 100644 --- a/docs/UsersGuide/source/Quickstart_NonContainer.rst +++ b/docs/UsersGuide/source/Quickstart_NonContainer.rst @@ -47,7 +47,7 @@ Clone the release branch of the repository: .. code-block:: console - git clone -b ufs-v1.0.0 https://github.com/ufs-community/ufs-srweather-app.git + git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git .. COMMENT: This will need to be changed to the updated release branch of the SRW repo once it exists. From 53807fa7f18917b1501119eb07a41538b62aec8b Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 10 Mar 2022 16:55:03 -0500 Subject: [PATCH 049/158] edits to overview and container QS --- .../source/Quickstart_Container.rst | 19 +++-- docs/UsersGuide/source/SRWAppOverview.rst | 70 ++++++++----------- 2 files changed, 41 insertions(+), 48 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart_Container.rst b/docs/UsersGuide/source/Quickstart_Container.rst index 87b65a31a6..413c72e283 100644 --- a/docs/UsersGuide/source/Quickstart_Container.rst +++ b/docs/UsersGuide/source/Quickstart_Container.rst @@ -20,13 +20,13 @@ Prerequisites: 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 HPC's. Therefore, it is not possible to build the HPC-Stack inside a Docker container on an HPC system. A Docker image may be pulled, but it must be run inside a container such as Singularity. + Docker containers can only be run with root privileges, and users cannot have root privileges on HPC's. Therefore, it is not possible to build the SRW, which uses the HPC-Stack, inside a Docker container on an HPC system. A Docker image may be pulled, but it must be run inside a container such as Singularity. Working in the Cloud ----------------------- -Users building the SRW using NOAA's Cloud resources must complete a few additional steps to ensure the SRW builds and runs correctly. For those working on non-cloud-based systems, skip to :numref:`Step %s `. +For those working on non-cloud-based systems, skip to :numref:`Step %s `. Users building the SRW using NOAA's Cloud resources must complete a few additional steps to ensure the SRW builds and runs correctly. On NOAA Cloud systems, certain environment variables must be set *before* building the container: @@ -40,15 +40,22 @@ On NOAA Cloud systems, certain environment variables must be set *before* buildi * ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, `tar the file `__ and move it to the ``/contrib`` directory, which is much slower but persistent. -On NOAA Cloud systems, allocate a compute node on which to run the SRW. Then, build and run the SRW from that node: +.. _WorkOnHPC: + +Working on HPC Systems +-------------------------- + +Those *not* working on HPC systems may skip to the `next step `. +On HPC systems (including NOAA's Cloud platforms), allocate a compute node on which to run the SRW. On some systems, it may be necessary to run the command ``module load singularity`` first. .. code-block:: console salloc -N 1 - module load gnu openmpi + module load openmpi mpirun -n 1 hostname - -This last command will output a hostname. Next, run ``ssh ``, replacing ```` with the actual hostname output in the prior command. + ssh + +The compiler options are ``gnu`` or ``intel``. The third command will output a hostname. This hostname should replace ```` in the last command. After "ssh-ing" to the compute node in the last command, build and run the SRW from that node. .. _BuildC: diff --git a/docs/UsersGuide/source/SRWAppOverview.rst b/docs/UsersGuide/source/SRWAppOverview.rst index 9810f9955b..cc4c88d8f2 100644 --- a/docs/UsersGuide/source/SRWAppOverview.rst +++ b/docs/UsersGuide/source/SRWAppOverview.rst @@ -3,14 +3,10 @@ ======================================== Short-Range Weather Application Overview ======================================== -The UFS Short-Range Weather Application (SRW App) is an umbrella repository that contains the tool -``manage_externals`` to check out all of the components required for the application. Once the + +The UFS Short-Range Weather Application (SRW App) is an umbrella repository consisting of a number of different :ref:`components ` housed in external repositories. The SRW APP assembles the required components using the ``manage_externals/checkout_externals`` script. Once the build process is complete, all the files and executables necessary for a regional experiment are -located in the ``regional_workflow`` and ``bin`` directories, respectively, under the ``ufs-srweather-app`` directory. -Users can utilize the pre-defined domains or build their own domain (details provided in :numref:`Chapter %s `). -In either case, users must create/modify the case-specific (``config.sh``) and/or grid-specific configuration -files (``set_predef_grid_params.sh``). The overall procedure is shown in :numref:`Figure %s `, -with the scripts to generate and run the workflow shown in red. The steps are as follows: +located in the ``regional_workflow`` and ``bin`` directories, respectively, under the ``ufs-srweather-app`` directory. Users can utilize the pre-defined domains (grids) or build their own domain (details provided in :numref:`Chapter %s `). In either case, users must create/modify the case-specific (``config.sh``) and/or grid-specific configuration files (``set_predef_grid_params.sh``). The overall procedure is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. The steps are as follows: #. Clone the UFS Short Range Weather Application from GitHub. #. Check out the external repositories. @@ -27,7 +23,7 @@ Each step will be described in detail in the following sections. .. figure:: _static/FV3LAM_wflow_overall.png - *Overall layout of the SRW App.* + *Overall layout of the SRW App* .. _DownloadSRWApp: @@ -40,12 +36,15 @@ Retrieve the UFS Short Range Weather Application (SRW App) repository from GitHu git clone -b ufs-v1.0.0 https://github.com/ufs-community/ufs-srweather-app.git cd ufs-srweather-app +.. + COMMENT: Change version number in 2 places above! + The cloned repository contains the configuration files and sub-directories shown in :numref:`Table %s `. .. _FilesAndSubDirs: -.. table:: Files and sub-directories of the ufs-srweather-app repository. +.. table:: Files and sub-directories of the ufs-srweather-app repository +--------------------------------+--------------------------------------------------------+ | **File/directory Name** | **Description** | @@ -57,7 +56,7 @@ The cloned repository contains the configuration files and sub-directories shown +--------------------------------+--------------------------------------------------------+ | LICENSE.md | CC0 license information | +--------------------------------+--------------------------------------------------------+ - | README.md | Quick start guide | + | README.md | Quick Start Guide | +--------------------------------+--------------------------------------------------------+ | ufs_srweather_app_meta.h.in | Meta information for SRW App which can be used by | | | other packages | @@ -78,14 +77,13 @@ The cloned repository contains the configuration files and sub-directories shown External Components =================== -Check out the external repositories, including regional_workflow, ufs-weather-model, ufs_utils, and emc_post for the SRW App. +Check out the external repositories, including regional_workflow, ufs-weather-model, ufs_utils, and upp.x for the SRW App. .. code-block:: console ./manage_externals/checkout_externals -This step will use the configuration ``Externals.cfg`` file in the ``ufs-srweather-app`` directory to -clone the specific tags (version of codes) of the external repositories as listed in +This step will use the configuration file ``Externals.cfg`` in the ``ufs-srweather-app`` directory to clone the correct tags (code versions) of the external repositories as listed in :numref:`Section %s `. .. _BuildExecutables: @@ -96,8 +94,7 @@ Before building the executables, the build environment must be set up for your s Instructions for loading the proper modules and/or setting the correct environment variables can be found in the ``env/`` directory in files named ``build__.env.`` For the most part, the commands in those files can be directly copied and pasted, but you may need to modify -certain variables such as the path to NCEP libraries for your specific platform. Here is a directory -listing example of these kinds of files: +certain variables such as the path to NCEP libraries for your specific platform. Here is a directory listing example of these kinds of files: .. code-block:: console @@ -111,17 +108,14 @@ The following steps will build the pre-processing utilities, forecast model, and .. code-block:: console - make dir + mkdir build cd build cmake .. -DCMAKE_INSTALL_PREFIX=.. make -j 4 >& build.out & where ``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, and ``share`` directories containing various components of the SRW App will be created, and its -recommended value ``..`` denotes one directory up from the build directory. In the next line for -the ``make`` call, ``-j 4`` indicates the build will run in parallel with 4 threads. If this step is successful, the -executables listed in :numref:`Table %s ` will be located in the -``ufs-srweather-app/bin`` directory. +recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. If this step is successful, the executables listed in :numref:`Table %s ` will be located in the ``ufs-srweather-app/bin`` directory. .. _ExecDescription: @@ -157,7 +151,8 @@ executables listed in :numref:`Table %s ` will be located in th +------------------------+---------------------------------------------------------------------------------+ | fvcom_to_FV3 | | +------------------------+---------------------------------------------------------------------------------+ - | make_hgrid | | + | make_hgrid | Computes geo-referencing parameters (e.g., latitude, longitude, grid cell area) | + | | for global uniform grids | | +------------------------+---------------------------------------------------------------------------------+ | emcsfc_ice_blend | | +------------------------+---------------------------------------------------------------------------------+ @@ -206,18 +201,17 @@ can be found in :numref:`Chapter %s `. Case-specific Configuration ============================= +When generating a new experiment (described in detail in :numref:`Section %s `), the SRW App first reads and assigns default values from the ``config_defaults.sh`` file. Then, it reads and (re)assigns variables from the user's custom ``config.sh`` file, located in the +``ufs-srweather-app/regional_workflow/ush`` directory. + .. _DefaultConfigSection: Default configuration: ``config_defaults.sh`` ------------------------------------------------ -When generating a new experiment (described in detail in :numref:`Section %s `), -the ``config_defaults.sh`` file is read first and assigns default values to the experiment -parameters. Important configuration variables in the ``config_defaults.sh`` file are shown in -:numref:`Table %s `, with more documentation found in the file itself, and -in :numref:`Chapter %s `. Some of these default values are intentionally invalid in order -to ensure that the user assigns valid values in the user-specified configuration ``config.sh`` file. -Therefore, any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` -settings. Note that there is usually no need for a user to modify the default configuration file. +Important configuration variables in the ``config_defaults.sh`` file appear in +:numref:`Table %s `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified configuration ``config.sh`` file. Any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` +settings. Note that there is usually no need for a user to modify the default configuration file. Additional information on the default settings can be found in the file itself and +in :numref:`Chapter %s `. .. _ConfigVarsDefault: @@ -330,15 +324,7 @@ settings. Note that there is usually no need for a user to modify the default co User-specific configuration: ``config.sh`` ------------------------------------------ -Before generating an experiment, the user must create a ``config.sh`` file in the -``ufs-srweather-app/regional_workflow/ush`` directory by copying either of the example -configuration files, ``config.community.sh`` for the community mode or ``config.nco.sh`` for -the NCO mode, or creating their own ``config.sh`` file. Note that the *community mode* is -recommended in most cases and will be fully supported for this release while the operational/NCO -mode will be more exclusively used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) -and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing. -:numref:`Table %s ` shows the configuration variables, along with their default -values in ``config_default.sh`` and the values defined in ``config.community.sh``. +The user must create a ``config.sh`` file in the ``ufs-srweather-app/regional_workflow/ush`` directory by copying either of the example configuration files (``config.community.sh`` for the community mode or ``config.nco.sh`` for the operational mode). Alternatively, the user can create a custom ``config.sh`` file from scratch. Note that the *community mode* is recommended in most cases and will be fully supported for this release while the operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing. :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. .. note:: @@ -348,7 +334,7 @@ values in ``config_default.sh`` and the values defined in ``config.community.sh` .. _ConfigCommunity: -.. table:: Configuration variables specified in the config.community.sh script. +.. table:: Configuration variables specified in the config.community.sh script +--------------------------------+-------------------+--------------------------------------------------------+ | **Parameter** | **Default Value** | **``config.community.sh`` Value** | @@ -397,11 +383,11 @@ values in ``config_default.sh`` and the values defined in ``config.community.sh` +--------------------------------+-------------------+--------------------------------------------------------+ | EXTRN_MDL_SOURCE_BASE_DIR_ICS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_FILES_ICS | "" | "gfs.pgrb2.0p25.f000" | + | EXTRN_MDL_FILES_ICS | "" | "gfs.pgrb2.0p25.f000" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_SOURCE_BASEDIR_LBCS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | + | EXTRN_MDL_SOURCE_BASEDIR_LBCS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_FILES_LBCS | "" | "gfs.pgrb2.0p25.f006" | + | EXTRN_MDL_FILES_LBCS | "" | "gfs.pgrb2.0p25.f006" | +--------------------------------+-------------------+--------------------------------------------------------+ From 93bfe9b619d510d742272703154d7b6abb023d81 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 11 Mar 2022 15:15:46 -0500 Subject: [PATCH 050/158] moved CodeReposAndDirs.rst info to the Introduction & deleted file --- docs/UsersGuide/source/CodeReposAndDirs.rst | 261 ----------------- docs/UsersGuide/source/Introduction.rst | 277 +++++++++++++++++- .../source/Quickstart_Container.rst | 52 +--- docs/UsersGuide/source/SRWAppOverview.rst | 23 +- docs/UsersGuide/source/index.rst | 1 - 5 files changed, 285 insertions(+), 329 deletions(-) delete mode 100644 docs/UsersGuide/source/CodeReposAndDirs.rst diff --git a/docs/UsersGuide/source/CodeReposAndDirs.rst b/docs/UsersGuide/source/CodeReposAndDirs.rst deleted file mode 100644 index 3031f84573..0000000000 --- a/docs/UsersGuide/source/CodeReposAndDirs.rst +++ /dev/null @@ -1,261 +0,0 @@ -.. _CodeReposAndDirs: - -========================================= -Code Repositories and Directory Structure -========================================= -This chapter describes the code repositories that comprise the UFS SRW Application, -without describing any of the components in detail. - -.. _HierarchicalRepoStr: - -Hierarchical Repository Structure -================================= -The umbrella repository for the UFS SRW Application is named ufs-srweather-app and is -available on GitHub at https://github.com/ufs-community/ufs-srweather-app. An umbrella -repository is defined as a repository that houses external code, called "externals," from -additional repositories. The UFS SRW Application includes the ``manage_externals`` tools -along with a configuration file called ``Externals.cfg``, which describes the external -repositories associated with this umbrella repo (see :numref:`Table %s `). - -.. _top_level_repos: - -.. table:: List of top-level repositories that comprise the UFS SRW Application. - - +---------------------------------+---------------------------------------------------------+ - | **Repository Description** | **Authoritative repository URL** | - +=================================+=========================================================+ - | Umbrella repository for the UFS | https://github.com/ufs-community/ufs-srweather-app | - | Short-Range Weather Application | | - +---------------------------------+---------------------------------------------------------+ - | Repository for | https://github.com/ufs-community/ufs-weather-model | - | the UFS Weather Model | | - +---------------------------------+---------------------------------------------------------+ - | Repository for the regional | https://github.com/ufs-community/regional_workflow | - | workflow | | - +---------------------------------+---------------------------------------------------------+ - | Repository for UFS utilities, | https://github.com/ufs-community/UFS_UTILS | - | including pre-processing, | | - | chgres_cube, and more | | - +---------------------------------+---------------------------------------------------------+ - | Repository for the Unified Post | https://github.com/NOAA-EMC/UPP | - | Processor (UPP) | | - +---------------------------------+---------------------------------------------------------+ - -The UFS Weather Model contains a number of sub-repositories used by the model as -documented `here `__. - -Note that the prerequisite libraries (including NCEP Libraries and external libraries) are not -included in the UFS SRW Application repository. The source code for these components resides in -the repositories `NCEPLIBS `_ and `NCEPLIBS-external -`_. - -These external components are already built on the preconfigured platforms listed `here -`__. -However, they must be cloned and built on other platforms according to the instructions provided -in the wiki pages of those repositories: https://github.com/NOAA-EMC/NCEPLIBS/wiki and -https://github.com/NOAA-EMC/NCEPLIBS-external/wiki. - -.. _TopLevelDirStructure: - -Directory Structure -=================== -The directory structure for the SRW Application is determined by the ``local_path`` settings in -the ``Externals.cfg`` file, which is in the directory where the umbrella repository has -been cloned. After ``manage_externals/checkout_externals`` is run, the specific GitHub repositories -that are described in :numref:`Table %s ` are cloned into the target -subdirectories shown below. The directories that will be created later by running the -scripts are presented in parentheses. Some directories have been removed for brevity. - -.. code-block:: console - - ufs-srweather-app - ├── (bin) - ├── (build) - ├── docs - │ └── UsersGuide - ├── (include) - ├── (lib) - ├── manage_externals - ├── regional_workflow - │ ├── docs - │ │ └── UsersGuide - │ ├── (fix) - │ ├── jobs - │ ├── modulefiles - │ ├── scripts - │ ├── tests - │ │ └── baseline_configs - │ └── ush - │ ├── Python - │ ├── rocoto - │ ├── templates - │ └── wrappers - ├── (share) - └── src - ├── UPP - │ ├── parm - │ └── sorc - │ └── ncep_post.fd - ├── UFS_UTILS - │ ├── sorc - │ │ ├── chgres_cube.fd - │ │ ├── fre-nctools.fd - | │ ├── grid_tools.fd - │ │ ├── orog_mask_tools.fd - │ │ └── sfc_climo_gen.fd - │ └── ush - └── ufs_weather_model - └── FV3 - ├── atmos_cubed_sphere - └── ccpp - -Regional Workflow Sub-Directories ---------------------------------- -Under the ``regional_workflow`` directory shown in :numref:`TopLevelDirStructure` there are -a number of sub-directories that are created when the regional workflow is cloned. The -contents of these sub-directories are described in :numref:`Table %s `. - -.. _Subdirectories: - -.. table:: Sub-directories of the regional workflow. - - +-------------------------+---------------------------------------------------------+ - | **Directory Name** | **Description** | - +=========================+=========================================================+ - | docs | Users' Guide Documentation | - +-------------------------+---------------------------------------------------------+ - | jobs | J-job scripts launched by Rocoto | - +-------------------------+---------------------------------------------------------+ - | modulefiles | Files used to load modules needed for building and | - | | running the workflow | - +-------------------------+---------------------------------------------------------+ - | scripts | Run scripts launched by the J-jobs | - +-------------------------+---------------------------------------------------------+ - | tests | Baseline experiment configuration | - +-------------------------+---------------------------------------------------------+ - | ush | Utility scripts used by the workflow | - +-------------------------+---------------------------------------------------------+ - -.. _ExperimentDirSection: - -Experiment Directory Structure -============================== -When the ``generate_FV3LAM_wflow.sh`` script is run, the user-defined experimental directory -``EXPTDIR=/path-to/ufs-srweather-app/../expt_dirs/${EXPT_SUBDIR}`` is created, where ``EXPT_SUBDIR`` -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: - -.. table:: Files and sub-directory initially created in the experimental directory. - :widths: 33 67 - - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | **File Name** | **Description** | - +===========================+=======================================================================================================+ - | config.sh | User-specified configuration file, see :numref:`Section %s ` | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | data_table | Cycle-independent input file (empty) | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | field_table | Tracers in the `forecast model | - | | `_ | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | input.nml | Namelist for the `UFS Weather model | - | | `_ | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | launch_FV3LAM_wflow.sh | Symlink to the shell script of | - | | ``ufs-srweather-app/regional_workflow/ush/launch_FV3LAM_wflow.sh`` | - | | that can be used to (re)launch the Rocoto workflow. | - | | Each time this script is called, it appends to a log | - | | file named ``log.launch_FV3LAM_wflow``. | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | log.generate_FV3LAM_wflow | Log of the output from the experiment generation script | - | | ``generate_FV3LAM_wflow.sh`` | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | nems.configure | See `NEMS configuration file | - | | `_ | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | suite_{CCPP}.xml | CCPP suite definition file used by the forecast model | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | var_defns.sh | Shell script defining the experiment parameters. It contains all | - | | of the primary parameters specified in the default and | - | | user-specified configuration files plus many secondary parameters | - | | that are derived from the primary ones by the experiment | - | | generation script. This file is sourced by various other scripts | - | | in order to make all the experiment variables available to these | - | | scripts. | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - | YYYYMMDDHH | Cycle directory (empty) | - +---------------------------+-------------------------------------------------------------------------------------------------------+ - -In addition, the *community* mode creates the ``fix_am`` and ``fix_lam`` directories in ``EXPTDIR``. -The ``fix_lam`` directory is initially empty but will contain some *fix* (time-independent) files -after the grid, orography, and/or surface climatology generation tasks are run. - -.. _FixDirectories: - -.. table:: Description of the fix directories - - +-------------------------+----------------------------------------------------------+ - | **Directory Name** | **Description** | - +=========================+==========================================================+ - | fix_am | Directory containing the global `fix` (time-independent) | - | | data files. The experiment generation script copies | - | | these files from a machine-dependent system directory. | - +-------------------------+----------------------------------------------------------+ - | fix_lam | Directory containing the regional fix (time-independent) | - | | data files that describe the regional grid, orography, | - | | and various surface climatology fields as well as | - | | symlinks to pre-generated files. | - +-------------------------+----------------------------------------------------------+ - -Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named -``log.launch_FV3LAM_wflow`` will be created (or appended to it if it already exists) in ``EXPTDIR``. -Once the ``make_grid``, ``make_orog``, and ``make_sfc_climo`` tasks and the ``get_extrn_ics`` -and ``get_extrn_lbc`` tasks for the YYYYMMDDHH cycle have completed successfully, new files and -sub-directories are created, as described in :numref:`Table %s `. - -.. _CreatedByWorkflow: - -.. table:: New directories and files created when the workflow is launched. - :widths: 30 70 - - +---------------------------+--------------------------------------------------------------------+ - | **Directory/file Name** | **Description** | - +===========================+====================================================================+ - | YYYYMMDDHH | This is updated when the first cycle-specific workflow tasks are | - | | run, which are ``get_extrn_ics`` and ``get_extrn_lbcs`` (they are | - | | launched simultaneously for each cycle in the experiment). We | - | | refer to this as a “cycle directory”. Cycle directories are | - | | created to contain cycle-specific files for each cycle that the | - | | experiment runs. If ``DATE_FIRST_CYCL`` and ``DATE_LAST_CYCL`` | - | | were different, and/or ``CYCL_HRS`` contained more than one | - | | element in the ``config.sh`` file, then more than one cycle | - | | directory would be created under the experiment directory. | - +---------------------------+--------------------------------------------------------------------+ - | grid | Directory generated by the ``make_grid`` task containing grid | - | | files for the experiment | - +---------------------------+--------------------------------------------------------------------+ - | log | Contains log files generated by the overall workflow and its | - | | various tasks. Look in these files to trace why a task may have | - | | failed. | - +---------------------------+--------------------------------------------------------------------+ - | orog | Directory generated by the ``make_orog`` task containing the | - | | orography files for the experiment | - +---------------------------+--------------------------------------------------------------------+ - | sfc_climo | Directory generated by the ``make_sfc_climo`` task containing the | - | | surface climatology files for the experiment | - +---------------------------+--------------------------------------------------------------------+ - | FV3LAM_wflow.db | Database files that are generated when Rocoto is called (by the | - | FV3LAM_wflow_lock.db | launch script) to launch the workflow. | - +---------------------------+--------------------------------------------------------------------+ - | log.launch_FV3LAM_wflow | This is the log file to which the launch script | - | | ``launch_FV3LAM_wflow.sh`` appends its output each time it is | - | | called. Take a look at the last 30–50 lines of this file to check | - | | the status of the workflow. | - +---------------------------+--------------------------------------------------------------------+ - -The output files for an experiment are described in :numref:`Section %s `. -The workflow tasks are described in :numref:`Section %s `). diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 0a4ba41d9a..b6e1eb4f61 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -1,8 +1,8 @@ .. _Introduction: -============= +============== Introduction -============= +============== The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. @@ -12,6 +12,10 @@ The SRW App v1.0.0 citation is as follows and should be used when presenting res UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994 +.. + COMMENT: Update version numbers/citation for release! + + How to Use This Document ======================== @@ -27,50 +31,293 @@ Variables presented as ``AaBbCc123`` in this document typically refer to variabl File paths or code that include angle brackets (e.g., ``env/build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``env/build_aws_gcc.env``). .. hint:: - To get started running the SRW, see the :ref:`Containerized Quick Start Guide `. + * To get started running the SRW, see the :ref:`Containerized Quick Start Guide ` or refer to the in-depth chapter on :ref:`Running the Short-Range Weather Application `. + * For background information on the SRW code repositories and directory structure, see :numref:`Section %s ` below. + * For an outline of SRW components, see section :numref:`Section %s ` below or refer to :numref:`Chapter %s: Components ` for a more in-depth treatment. + + +.. _SRWStructure: + +Code Repositories and Directory Structure +========================================= + +.. _HierarchicalRepoStr: + +Hierarchical Repository Structure +----------------------------------- +The umbrella repository for the UFS SRW Application is named *ufs-srweather-app* and is available on GitHub at https://github.com/ufs-community/ufs-srweather-app. An umbrella repository is a repository that houses external code, called "externals," from additional repositories. The UFS SRW Application includes the ``manage_externals`` tools along with a configuration file called ``Externals.cfg``, which describes the external repositories associated with this umbrella repo (see :numref:`Table %s `). + +.. _top_level_repos: +.. table:: List of top-level repositories that comprise the UFS SRW Application -Pre-processor Utilities and Initial Conditions -============================================== + +---------------------------------+---------------------------------------------------------+ + | **Repository Description** | **Authoritative repository URL** | + +=================================+=========================================================+ + | Umbrella repository for the UFS | https://github.com/ufs-community/ufs-srweather-app | + | Short-Range Weather Application | | + +---------------------------------+---------------------------------------------------------+ + | Repository for | https://github.com/ufs-community/ufs-weather-model | + | the UFS Weather Model | | + +---------------------------------+---------------------------------------------------------+ + | Repository for the regional | https://github.com/ufs-community/regional_workflow | + | workflow | | + +---------------------------------+---------------------------------------------------------+ + | Repository for UFS utilities, | https://github.com/ufs-community/UFS_UTILS | + | including pre-processing, | | + | chgres_cube, and more | | + +---------------------------------+---------------------------------------------------------+ + | Repository for the Unified Post | https://github.com/NOAA-EMC/UPP | + | Processor (UPP) | | + +---------------------------------+---------------------------------------------------------+ -The SRW Application includes a number of pre-processing utilities that initialize and prepare the -model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. +The UFS Weather Model contains a number of sub-repositories used by the model as +documented `here `__. + +Note that 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 the preconfigured (Level 1) platforms listed `here +`__. +However, it must be built on other systems. :numref:`Chapter %s ` contains details on installing the HPC-Stack. + + +.. _TopLevelDirStructure: + +Directory Structure +---------------------- +The ``ufs-srweather-app`` umbrella repository structure is determined by the ``local_path`` settings contained within the ``Externals.cfg`` file. After ``manage_externals/checkout_externals`` is run (:numref:`Step %s `), the specific GitHub repositories described in :numref:`Table %s ` are cloned into the target subdirectories shown below. Directories that will be created as part of the build process appear in parentheses and will not be visible until after the build is complete. Some directories have been removed for brevity. + +.. code-block:: console + + ufs-srweather-app + ├── (bin) + ├── (build) + ├── docs + │ └── UsersGuide + ├── (include) + ├── (lib) + ├── manage_externals + ├── regional_workflow + │ ├── docs + │ │ └── UsersGuide + │ ├── (fix) + │ ├── jobs + │ ├── modulefiles + │ ├── scripts + │ ├── tests + │ │ └── baseline_configs + │ └── ush + │ ├── Python + │ ├── rocoto + │ ├── templates + │ └── wrappers + ├── (share) + └── src + ├── UPP + │ ├── parm + │ └── sorc + │ └── ncep_post.fd + ├── UFS_UTILS + │ ├── sorc + │ │ ├── chgres_cube.fd + │ │ ├── fre-nctools.fd + | │ ├── grid_tools.fd + │ │ ├── orog_mask_tools.fd + │ │ └── sfc_climo_gen.fd + │ └── ush + └── ufs_weather_model + └── FV3 + ├── atmos_cubed_sphere + └── ccpp + +Regional Workflow Sub-Directories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Under the ``regional_workflow`` directory shown in :numref:`TopLevelDirStructure`, a number of sub-directories are created when the regional workflow is cloned. The contents of these sub-directories are described in :numref:`Table %s `. + +.. _Subdirectories: + +.. table:: Sub-directories of the regional workflow + + +-------------------------+---------------------------------------------------------+ + | **Directory Name** | **Description** | + +=========================+=========================================================+ + | docs | Users' Guide Documentation | + +-------------------------+---------------------------------------------------------+ + | jobs | J-job scripts launched by Rocoto | + +-------------------------+---------------------------------------------------------+ + | modulefiles | Files used to load modules needed for building and | + | | running the workflow | + +-------------------------+---------------------------------------------------------+ + | scripts | Run scripts launched by the J-jobs | + +-------------------------+---------------------------------------------------------+ + | tests | Baseline experiment configuration | + +-------------------------+---------------------------------------------------------+ + | ush | Utility scripts used by the workflow | + +-------------------------+---------------------------------------------------------+ + +.. _ExperimentDirSection: + +Experiment Directory Structure +-------------------------------- +When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Step %s `), a user-defined experimental directory is created based on information specified in the ``config.sh`` file. :numref:`Table %s ` shouws the contents of the experiment directory before the experiment workflow is run. + +.. _ExptDirStructure: + +.. table:: Files and sub-directory initially created in the experimental directory + :widths: 33 67 + + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | **File Name** | **Description** | + +===========================+=======================================================================================================+ + | config.sh | User-specified configuration file, see :numref:`Section %s ` | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | data_table | Cycle-independent input file (empty) | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | field_table | Tracers in the `forecast model | + | | `_ | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | input.nml | Namelist for the `UFS Weather model | + | | `_ | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | launch_FV3LAM_wflow.sh | Symlink to the shell script of | + | | ``ufs-srweather-app/regional_workflow/ush/launch_FV3LAM_wflow.sh`` | + | | that can be used to (re)launch the Rocoto workflow. | + | | Each time this script is called, it appends to a log | + | | file named ``log.launch_FV3LAM_wflow``. | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | log.generate_FV3LAM_wflow | Log of the output from the experiment generation script | + | | ``generate_FV3LAM_wflow.sh`` | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | nems.configure | See `NEMS configuration file | + | | `_ | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | suite_{CCPP}.xml | CCPP suite definition file used by the forecast model | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | var_defns.sh | Shell script defining the experiment parameters. It contains all | + | | of the primary parameters specified in the default and | + | | user-specified configuration files plus many secondary parameters | + | | that are derived from the primary ones by the experiment | + | | generation script. This file is sourced by various other scripts | + | | in order to make all the experiment variables available to these | + | | scripts. | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + | YYYYMMDDHH | Cycle directory (empty) | + +---------------------------+-------------------------------------------------------------------------------------------------------+ + +In addition, the *community* mode creates the ``fix_am`` and ``fix_lam`` directories in ``EXPTDIR``. +The ``fix_lam`` directory is initially empty but will contain some *fix* (time-independent) files +after the grid, orography, and/or surface climatology generation tasks are run. + +.. _FixDirectories: + +.. table:: Description of the fix directories + + +-------------------------+----------------------------------------------------------+ + | **Directory Name** | **Description** | + +=========================+==========================================================+ + | fix_am | Directory containing the global `fix` (time-independent) | + | | data files. The experiment generation script copies | + | | these files from a machine-dependent system directory. | + +-------------------------+----------------------------------------------------------+ + | fix_lam | Directory containing the regional fix (time-independent) | + | | data files that describe the regional grid, orography, | + | | and various surface climatology fields as well as | + | | symlinks to pre-generated files. | + +-------------------------+----------------------------------------------------------+ + +Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named +``log.launch_FV3LAM_wflow`` will be created (or appended to it if it already exists) in ``EXPTDIR``. +Once the ``make_grid``, ``make_orog``, and ``make_sfc_climo`` tasks and the ``get_extrn_ics`` +and ``get_extrn_lbc`` tasks for the YYYYMMDDHH cycle have completed successfully, new files and +sub-directories are created, as described in :numref:`Table %s `. + +.. _CreatedByWorkflow: + +.. table:: New directories and files created when the workflow is launched. + :widths: 30 70 + + +---------------------------+--------------------------------------------------------------------+ + | **Directory/file Name** | **Description** | + +===========================+====================================================================+ + | YYYYMMDDHH | This is updated when the first cycle-specific workflow tasks are | + | | run, which are ``get_extrn_ics`` and ``get_extrn_lbcs`` (they are | + | | launched simultaneously for each cycle in the experiment). We | + | | refer to this as a “cycle directory”. Cycle directories are | + | | created to contain cycle-specific files for each cycle that the | + | | experiment runs. If ``DATE_FIRST_CYCL`` and ``DATE_LAST_CYCL`` | + | | were different, and/or ``CYCL_HRS`` contained more than one | + | | element in the ``config.sh`` file, then more than one cycle | + | | directory would be created under the experiment directory. | + +---------------------------+--------------------------------------------------------------------+ + | grid | Directory generated by the ``make_grid`` task containing grid | + | | files for the experiment | + +---------------------------+--------------------------------------------------------------------+ + | log | Contains log files generated by the overall workflow and its | + | | various tasks. Look in these files to trace why a task may have | + | | failed. | + +---------------------------+--------------------------------------------------------------------+ + | orog | Directory generated by the ``make_orog`` task containing the | + | | orography files for the experiment | + +---------------------------+--------------------------------------------------------------------+ + | sfc_climo | Directory generated by the ``make_sfc_climo`` task containing the | + | | surface climatology files for the experiment | + +---------------------------+--------------------------------------------------------------------+ + | FV3LAM_wflow.db | Database files that are generated when Rocoto is called (by the | + | FV3LAM_wflow_lock.db | launch script) to launch the workflow. | + +---------------------------+--------------------------------------------------------------------+ + | log.launch_FV3LAM_wflow | This is the log file to which the launch script | + | | ``launch_FV3LAM_wflow.sh`` appends its output each time it is | + | | called. Take a look at the last 30–50 lines of this file to check | + | | the status of the workflow. | + +---------------------------+--------------------------------------------------------------------+ + +The output files for an experiment are described in :numref:`Section %s `. +The workflow tasks are described in :numref:`Section %s `). + + +.. _Utilities: + +SRW Component Summary: Pre-processor Utilities and Initial Conditions +========================================================================= + +The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. Forecast Model -============== +----------------- Atmospheric Model --------------------- +^^^^^^^^^^^^^^^^^^^^^^ The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere (:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability (:cite:t:`BlackEtAl2020`). The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. Common Community Physics Package ---------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and Noah Multi-parameterization (Noah MP) Land Surface Model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW release includes an experimental physics version and an updated operational version. Data Format --------------- +^^^^^^^^^^^^^^^^^^^^^^ The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube`. -Post-processor -============== +Unified Post-Processor (UPP) +-------------------------------- The `Unified Post Processor `__ (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF format on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from the UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). Visualization Example -===================== +------------------------- This SRW Application provides Python scripts to create basic visualizations of the model output. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. Build System and Workflow -========================= +---------------------------- The SRW Application has a portable CMake-based build system that packages together all the components required to build the SRW Application. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see `Rocoto documentation `__ for more on workflow management). Individual components can also be run in a stand-alone, command line fashion. diff --git a/docs/UsersGuide/source/Quickstart_Container.rst b/docs/UsersGuide/source/Quickstart_Container.rst index 413c72e283..82bcd0f960 100644 --- a/docs/UsersGuide/source/Quickstart_Container.rst +++ b/docs/UsersGuide/source/Quickstart_Container.rst @@ -10,7 +10,7 @@ The "out-of-the-box" SRW case described in this guide builds a weather forecast .. _DownloadCodeC: -Download the UFS SRW Application Code +Building the UFS SRW Application =========================================== The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. @@ -38,7 +38,7 @@ On NOAA Cloud systems, certain environment variables must be set *before* buildi * If the ``cache`` and ``tmp`` directories do not exist already, they must be created. -* ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, `tar the file `__ and move it to the ``/contrib`` directory, which is much slower but persistent. +* ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, `tar the files `__ and move it to the ``/contrib`` directory, which is much slower but persistent. .. _WorkOnHPC: @@ -46,16 +46,18 @@ Working on HPC Systems -------------------------- Those *not* working on HPC systems may skip to the `next step `. -On HPC systems (including NOAA's Cloud platforms), allocate a compute node on which to run the SRW. On some systems, it may be necessary to run the command ``module load singularity`` first. +On HPC systems (including NOAA's Cloud platforms), allocate a compute node on which to run the SRW. On NOAA's Cloud platforms, the following commands should work: .. code-block:: console salloc -N 1 - module load openmpi + module load gnu openmpi mpirun -n 1 hostname ssh -The compiler options are ``gnu`` or ``intel``. The third command will output a hostname. This hostname should replace ```` in the last command. After "ssh-ing" to the compute node in the last command, build and run the SRW from that node. +The third command will output a hostname. This hostname should replace ```` in the last command. After "ssh-ing" to the compute node in the last command, build and run the SRW from that node. + +The appropriate commands on other Level 1 platforms will vary, and users should consult the documentation for those platforms. .. _BuildC: @@ -83,27 +85,6 @@ The command above also binds the local directory to the container so that data c * When binding two directories, they must have the same name. It may be necessary to ``cd`` into the container and create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. * Be sure to bind the directory that contains the data the experiment will access. -Download the SRW Code ------------------------- - -Clone the develop branch of the UFS-SRW weather application repository: - -.. code-block:: console - - git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git - -.. - COMMENT: change repo for release - -Check out submodules for the SRW Application: - -.. code-block:: console - - cd ufs-srweather-app - ./manage_externals/checkout_externals - -If the ``manage_externals`` command brings up an error, it may be necessary to run ``ln -s /usr/bin/python3 /usr/bin/python`` first. - .. _SetUpBuildC: @@ -123,27 +104,14 @@ If the SRW Application has been built in a container provided by the Earth Predi Build the Executables -===================== +====================== Create a directory to hold the build's executables: .. code-block:: console - mkdir build - cd build - -From the build directory, run the ``cmake`` command below to set up the ``Makefile``, then run the ``make`` command to build the executables: - -.. code-block:: console - - cmake .. -DCMAKE_INSTALL_PREFIX=.. - make -j 4 >& build.out & - -The build will take a few minutes to complete. When it starts, a random number is printed to the console, and when it is done, a ``[1]+ Done`` message is printed to the console when you list the files in ``ufs-srweather-app/bin`` (``[1]+ Exit`` may indicate an error). Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, you should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. - -.. hint:: - - If you see the build.out file, but there is no ``ufs-srweather-app/bin`` directory, wait a few more minutes for the build to complete. + cd ubuntu20.04-epic-srwapp-1.0/opt/ufs-srweather-app/build + source build-srw.sh Download and Stage the Data ============================ diff --git a/docs/UsersGuide/source/SRWAppOverview.rst b/docs/UsersGuide/source/SRWAppOverview.rst index cc4c88d8f2..4d0f2f20a7 100644 --- a/docs/UsersGuide/source/SRWAppOverview.rst +++ b/docs/UsersGuide/source/SRWAppOverview.rst @@ -56,7 +56,7 @@ The cloned repository contains the configuration files and sub-directories shown +--------------------------------+--------------------------------------------------------+ | LICENSE.md | CC0 license information | +--------------------------------+--------------------------------------------------------+ - | README.md | Quick Start Guide | + | README.md | Getting Started Guide | +--------------------------------+--------------------------------------------------------+ | ufs_srweather_app_meta.h.in | Meta information for SRW App which can be used by | | | other packages | @@ -77,7 +77,7 @@ The cloned repository contains the configuration files and sub-directories shown External Components =================== -Check out the external repositories, including regional_workflow, ufs-weather-model, ufs_utils, and upp.x for the SRW App. +Retrieve required components from external repositories, including regional_workflow, ufs-weather-model, ufs_utils, and upp.x: .. code-block:: console @@ -152,21 +152,24 @@ recommended value ``..`` denotes one directory up from the build directory. In t | fvcom_to_FV3 | | +------------------------+---------------------------------------------------------------------------------+ | make_hgrid | Computes geo-referencing parameters (e.g., latitude, longitude, grid cell area) | - | | for global uniform grids | | + | | for global uniform grids | +------------------------+---------------------------------------------------------------------------------+ - | emcsfc_ice_blend | | + | emcsfc_ice_blend | Blends National Ice Center sea ice cover and EMC sea ice concentration data to | + | | create a global sea ice analysis used to update the GFS once per day | +------------------------+---------------------------------------------------------------------------------+ - | emcsfc_snow2mdl | | + | emcsfc_snow2mdl | Blends National Ice Center snow cover and Air Force snow depth data to create a | + | | global depth analysis used to update the GFS snow field once per day | +------------------------+---------------------------------------------------------------------------------+ - | global_cycle | | + | global_cycle | Updates the GFS surface conditions using external snow and sea ice analyses | +------------------------+---------------------------------------------------------------------------------+ - | inland | | + | inland | Create an inland land mask | +------------------------+---------------------------------------------------------------------------------+ - | orog_gsl | | + | orog_gsl | Ceates orographic statistics fields required for the orographic drag suite | + | | developed by NOAA's Global Systems Laboratory (GSL) | +------------------------+---------------------------------------------------------------------------------+ - | fregrid | | + | fregrid | Remaps data from the input mosaic grid to the output mosaic grid | +------------------------+---------------------------------------------------------------------------------+ - | lakefrac | | + | lakefrac | Set lake fraction and depth | +------------------------+---------------------------------------------------------------------------------+ .. _GridSpecificConfig: diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index 290b1ec482..4057dcee0d 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -14,7 +14,6 @@ UFS Short-Range Weather App Users Guide Introduction Quickstart_Container Quickstart_NonContainer - CodeReposAndDirs SRWAppOverview Components Include-HPCInstall From eb00397e23397f4245f3fcb03b37818e20e8cf49 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 11 Mar 2022 16:28:20 -0500 Subject: [PATCH 051/158] continued edits to SRWAppOverview --- docs/UsersGuide/source/Glossary.rst | 12 ++++ docs/UsersGuide/source/Introduction.rst | 13 ++-- .../source/Quickstart_Container.rst | 2 +- docs/UsersGuide/source/SRWAppOverview.rst | 71 ++++++------------- 4 files changed, 39 insertions(+), 59 deletions(-) diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index dbac0aca42..7099a6b1a2 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -9,6 +9,12 @@ Glossary CCPP The `Common Community Physics Package `_ is a forecast-model agnostic, vetted collection of codes containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model. + Component + A software element that has a clear function and interface. In Earth system models, components are often single portions of the Earth system (e.g. atmosphere, ocean, or land surface) that are assembled to form a whole. + + Component Repository + A :term:`repository` that contains, at a minimum, source code for a single component. + CONUS Continental United States @@ -81,6 +87,9 @@ Glossary RAP `Rapid Refresh `. The continental-scale NOAA hourly-updated assimilation/modeling system operational at NCEP. RAP covers North America and is comprised primarily of a numerical forecast model and an analysis/assimilation system to initialize that model. RAP is complemented by the higher-resolution 3km High-Resolution Rapid Refresh (HRRR) model. + Repository + A central location in which files (e.g., data, code, documentation) are stored and managed. + UFS The Unified Forecast System is a community-based, coupled comprehensive Earth modeling system consisting of several applications (apps). These apps span regional to global @@ -94,6 +103,9 @@ Glossary and boundary condition generation codes used by the UFS Short-Range Weather App are all part of this collection. + Umbrella repository + A repository that houses external code, or “externals,” from additional repositories. + UPP The `Unified Post Processor `__ is software developed at :term:`NCEP` and used operationally to post-process raw output from a variety of :term:`NCEP`'s NWP models, including the FV3. diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index b6e1eb4f61..c9b1ee6491 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -45,7 +45,7 @@ Code Repositories and Directory Structure Hierarchical Repository Structure ----------------------------------- -The umbrella repository for the UFS SRW Application is named *ufs-srweather-app* and is available on GitHub at https://github.com/ufs-community/ufs-srweather-app. An umbrella repository is a repository that houses external code, called "externals," from additional repositories. The UFS SRW Application includes the ``manage_externals`` tools along with a configuration file called ``Externals.cfg``, which describes the external repositories associated with this umbrella repo (see :numref:`Table %s `). +The umbrella repository for the UFS SRW Application is named *ufs-srweather-app* and is available on GitHub at https://github.com/ufs-community/ufs-srweather-app. An umbrella repository is a repository that houses external code, called "externals," from additional repositories. The UFS SRW Application includes the ``manage_externals`` tools along with a configuration file called ``Externals.cfg``, which describes the external repositories associated with this umbrella repository (see :numref:`Table %s `). .. _top_level_repos: @@ -74,17 +74,14 @@ The umbrella repository for the UFS SRW Application is named *ufs-srweather-app* The UFS Weather Model contains a number of sub-repositories used by the model as documented `here `__. -Note that 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 the preconfigured (Level 1) platforms listed `here -`__. -However, it must be built on other systems. :numref:`Chapter %s ` contains details on installing the HPC-Stack. +Note that 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 the preconfigured (Level 1) platforms listed `here `__. However, it must be built on other systems. :numref:`Chapter %s ` contains details on installing the HPC-Stack. .. _TopLevelDirStructure: Directory Structure ---------------------- -The ``ufs-srweather-app`` umbrella repository structure is determined by the ``local_path`` settings contained within the ``Externals.cfg`` file. After ``manage_externals/checkout_externals`` is run (:numref:`Step %s `), the specific GitHub repositories described in :numref:`Table %s ` are cloned into the target subdirectories shown below. Directories that will be created as part of the build process appear in parentheses and will not be visible until after the build is complete. Some directories have been removed for brevity. +The ``ufs-srweather-app`` :term:`umbrella repository` structure is determined by the ``local_path`` settings contained within the ``Externals.cfg`` file. After ``manage_externals/checkout_externals`` is run (:numref:`Step %s `), the specific GitHub repositories described in :numref:`Table %s ` are cloned into the target subdirectories shown below. Directories that will be created as part of the build process appear in parentheses and will not be visible until after the build is complete. Some directories have been removed for brevity. .. code-block:: console @@ -372,9 +369,7 @@ utilities, model code, and infrastructure. Users can post issues in the related Future Direction ================= -Users can expect to see incremental improvements and additional capabilities in upcoming -releases of the SRW Application to enhance research opportunities and support operational -forecast implementations. Planned enhancements include: +Users can expect to see incremental improvements and additional capabilities in upcoming releases of the SRW Application to enhance research opportunities and support operational forecast implementations. Planned enhancements include: * A more extensive set of supported developmental physics suites. * A larger number of pre-defined domains/resolutions and a fully supported capability to create a user-defined domain. diff --git a/docs/UsersGuide/source/Quickstart_Container.rst b/docs/UsersGuide/source/Quickstart_Container.rst index 82bcd0f960..c66a3abb5d 100644 --- a/docs/UsersGuide/source/Quickstart_Container.rst +++ b/docs/UsersGuide/source/Quickstart_Container.rst @@ -1,7 +1,7 @@ .. _QuickstartC: ================================================= -Containerized Workflow Quick Start (Recommended) +Containerized Quick Start Guide (Recommended) ================================================= This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a container. The container approach provides a uniform enviroment in which to build and run the SRW. Normally, the details of building and running the SRW vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions. Installation via an EPIC-provided container reduces this variability and allows for a smoother SRW build and run experience. diff --git a/docs/UsersGuide/source/SRWAppOverview.rst b/docs/UsersGuide/source/SRWAppOverview.rst index 4d0f2f20a7..0e320c7dd8 100644 --- a/docs/UsersGuide/source/SRWAppOverview.rst +++ b/docs/UsersGuide/source/SRWAppOverview.rst @@ -1,21 +1,21 @@ .. _SRWAppOverview: -======================================== -Short-Range Weather Application Overview -======================================== +=========================================================== +Building and Running the Short-Range Weather Application +=========================================================== -The UFS Short-Range Weather Application (SRW App) is an umbrella repository consisting of a number of different :ref:`components ` housed in external repositories. The SRW APP assembles the required components using the ``manage_externals/checkout_externals`` script. Once the +The UFS Short-Range Weather Application (SRW App) is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. The SRW App assembles the required components using the ``manage_externals/checkout_externals`` script. Once the build process is complete, all the files and executables necessary for a regional experiment are -located in the ``regional_workflow`` and ``bin`` directories, respectively, under the ``ufs-srweather-app`` directory. Users can utilize the pre-defined domains (grids) or build their own domain (details provided in :numref:`Chapter %s `). In either case, users must create/modify the case-specific (``config.sh``) and/or grid-specific configuration files (``set_predef_grid_params.sh``). The overall procedure is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. The steps are as follows: +located in the ``regional_workflow`` and ``bin`` directories, respectively, under the ``ufs-srweather-app`` directory. Users can utilize the pre-defined domains (grids) or build their own domain (see :numref:`Chapter %s ` for details). In either case, users must create/modify the case-specific (``config.sh``) and/or grid-specific configuration files (``set_predef_grid_params.sh``). The overall procedure is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. The steps are as follows: -#. Clone the UFS Short Range Weather Application from GitHub. -#. Check out the external repositories. -#. Set up the build environment and build the regional workflow system using ``cmake/make``. -#. Optional: Add new grid information to the ``set_predef_grid_param.sh`` configuration file and update ``valid_param_vals.sh``. -#. Modify the case-specific ``config.sh`` configuration file. -#. Load the python environment for the regional workflow -#. Generate a regional workflow experiment. -#. Run the regional workflow as needed. + * :ref:`Clone the SRW App from GitHub. ` + * :ref:`Check out the external repositories. ` + * :ref:`Set up the build environment and build the regional workflow system. ` + * :ref:`Optional: Configure a new grid. ` + * :ref:`Configure the experiment. ` + * :ref:`Load the python environment for the regional workflow. ` + * :ref:`Generate a regional workflow experiment. ` + * :ref:`Run the regional workflow. ` Each step will be described in detail in the following sections. @@ -27,8 +27,8 @@ Each step will be described in detail in the following sections. .. _DownloadSRWApp: -Download from GitHub -==================== +Download the SRW App +======================== Retrieve the UFS Short Range Weather Application (SRW App) repository from GitHub and checkout the ``ufs-v1.0.0`` tag: .. code-block:: console @@ -83,18 +83,13 @@ Retrieve required components from external repositories, including regional_work ./manage_externals/checkout_externals -This step will use the configuration file ``Externals.cfg`` in the ``ufs-srweather-app`` directory to clone the correct tags (code versions) of the external repositories as listed in -:numref:`Section %s `. +This step will use the configuration file ``Externals.cfg`` in the ``ufs-srweather-app`` directory to clone the correct tags (code versions) of the external repositories as listed in :numref:`Section %s `. .. _BuildExecutables: Building the Executables for the Application ============================================ -Before building the executables, the build environment must be set up for your specific platform. -Instructions for loading the proper modules and/or setting the correct environment variables -can be found in the ``env/`` directory in files named ``build__.env.`` For the -most part, the commands in those files can be directly copied and pasted, but you may need to modify -certain variables such as the path to NCEP libraries for your specific platform. Here is a directory listing example of these kinds of files: +Before building the executables, the build environment must be set up for your specific platform. Instructions for loading the proper modules and/or setting the correct environment variables can be found in the ``env/`` directory in files named ``build__.env.`` For the most part, the commands in those files can be directly copied and pasted, but you may need to modify certain variables such as the path to NCEP libraries for your specific platform. Here is a directory listing example of these kinds of files: .. code-block:: console @@ -113,9 +108,7 @@ The following steps will build the pre-processing utilities, forecast model, and cmake .. -DCMAKE_INSTALL_PREFIX=.. make -j 4 >& build.out & -where ``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, -and ``share`` directories containing various components of the SRW App will be created, and its -recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. If this step is successful, the executables listed in :numref:`Table %s ` will be located in the ``ufs-srweather-app/bin`` directory. +where ``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, and ``share`` directories containing various components of the SRW App will be created, and its recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. If this step is successful, the executables listed in :numref:`Table %s ` will be located in the ``ufs-srweather-app/bin`` directory. .. _ExecDescription: @@ -177,15 +170,8 @@ recommended value ``..`` denotes one directory up from the build directory. In t Grid-specific Configuration =========================== -Some SRW App parameters depend on the characteristics of the grid such as resolution and domain size. -These include ``ESG grid`` and ``Input configuration`` as well as the variables -related to the write component (quilting). The SRW App officially supports three different predefined -grids as shown in :numref:`Table %s `. Their names can be found under -``valid_vals_PREDEF_GRID_NAME`` in the ``valid_param_vals`` script, and their grid-specific configuration -variables are specified in the ``set_predef_grid_params`` script. If users want to create a new domain, -they should put its name in the ``valid_param_vals`` script and the corresponding grid-specific -parameters in the ``set_predef_grid_params`` script. More information on the predefined and user-generated options -can be found in :numref:`Chapter %s `. +Some SRW App parameters depend on the characteristics of the grid such as resolution and domain size. These include ``ESG grid`` and ``Input configuration`` as well as the variables related to the write component (quilting). The SRW App officially supports three different predefined grids as shown in :numref:`Table %s `. Their names can be found under ``valid_vals_PREDEF_GRID_NAME`` in the ``valid_param_vals`` script, and their grid-specific configuration variables are specified in the ``set_predef_grid_params`` script. If users want to create a new domain, they should put its name in the ``valid_param_vals`` script and the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. More information on the predefined and user-generated options +can be found in :numref:`Chapter %s `. .. _PredefinedGrids: @@ -439,11 +425,7 @@ that is executed when running the experiment with the Rocoto workflow manager. *Experiment generation description* -The ``setup.sh`` script reads three other configuration scripts: (1) ``config_default.sh`` -(:numref:`Section %s `), (2) ``config.sh`` (:numref:`Section %s `), -and (3) ``set_predef_grid_params.sh`` (:numref:`Section %s `). Note that these three -scripts are read in order: ``config_default.sh``, ``config.sh``, then ``set_predef_grid_params.sh``. -If a parameter is specified differently in these scripts, the file containing the last defined value will be used. +The ``setup.sh`` script reads three other configuration scripts: (1) ``config_default.sh`` (:numref:`Section %s `), (2) ``config.sh`` (:numref:`Section %s `), and (3) ``set_predef_grid_params.sh`` (:numref:`Section %s `). Note that these three scripts are read in order: ``config_default.sh``, ``config.sh``, then ``set_predef_grid_params.sh``. If a parameter is specified differently in these scripts, the file containing the last defined value will be used. .. _WorkflowTaskDescription: @@ -452,16 +434,7 @@ Description of Workflow Tasks The flowchart of the workflow tasks that are specified in the ``FV3LAM_wflow.xml`` file are illustrated in :numref:`Figure %s `, and each task is described in :numref:`Table %s `. The first three pre-processing tasks; ``MAKE_GRID``, -``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and -surface climatology fix files, these three tasks can be skipped by setting ``RUN_TASK_MAKE_GRID=”FALSE”``, -``RUN_TASK_MAKE_OROG=”FALSE”``, and ``RUN_TASK_MAKE_SFC_CLIMO=”FALSE”`` in the ``regional_workflow/ush/config.sh`` -file before running the ``generate_FV3LAM_wflow.sh`` script. As shown in the figure, the ``FV3LAM_wflow.xml`` -file runs the specific j-job scripts in the prescribed order (``regional_workflow/jobs/JREGIONAL_[task name]``) -when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own source script named -``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files -``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. -There is usually no need for users to modify these files. To relaunch the workflow from scratch, -delete these two ``*.db`` files and then call the launch script repeatedly for each task. +``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by setting ``RUN_TASK_MAKE_GRID=”FALSE”``, ``RUN_TASK_MAKE_OROG=”FALSE”``, and ``RUN_TASK_MAKE_SFC_CLIMO=”FALSE”`` in the ``regional_workflow/ush/config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script. As shown in the figure, the ``FV3LAM_wflow.xml`` file runs the specific j-job scripts in the prescribed order (``regional_workflow/jobs/JREGIONAL_[task name]``) when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own source script named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. .. _WorkflowTasksFig: From f4d2043ba6fe9a82c42331af02c53140112dfa58 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 15 Mar 2022 18:53:29 -0400 Subject: [PATCH 052/158] combine overview w/non-container docs --- docs/UsersGuide/source/Components.rst | 2 +- docs/UsersGuide/source/Introduction.rst | 6 +- .../source/Quickstart_Container.rst | 78 ++- .../source/Quickstart_NonContainer.rst | 459 +++++++++++++-- docs/UsersGuide/source/SRWAppOverview.rst | 547 +----------------- .../source/_static/theme_overrides.css | 1 + docs/UsersGuide/source/index.rst | 2 +- 7 files changed, 485 insertions(+), 610 deletions(-) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index 50513a303e..bd8b22c254 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -87,7 +87,7 @@ For the selected computational platforms that have been pre-configured (Level 1) required libraries for building the SRW Application are available in a central place. That means bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) have both been built. The SRW Application is expected to build and run out-of-the-box on these -pre-configured platforms. Users can download the SRW code and choose whether to run it :ref:`in a container ` or :ref:`locally `. +pre-configured platforms. Users can download the SRW code and choose whether to run it :ref:`in a container ` or :ref:`locally `. A few additional computational platforms are considered configurable for the SRW Application release. Configurable platforms (Level 2) are platforms where all of the required libraries for building the SRW Application are expected to install successfully but are not available in a central location. Applications and models are expected to build and run once the required bundled libraries (e.g., NCEPLIBS) and third-party libraries (e.g., NCEPLIBS-external) are built. diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index c9b1ee6491..f67f240f25 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -6,7 +6,7 @@ Introduction The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. -The UFS can be configured for multiple applications (see the `complete list here `__). The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides two Quick Start Guides for running the application :ref:`in a conainer ` or :ref:`locally `, in addition to an overview of the :ref:`release components `, a description of the supported capabilities, and details on where to find more information and obtain support. +The UFS can be configured for multiple applications (see the `complete list here `__). The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a Quick Start Guide for running the application :ref:`in a container ` and a detailed guide for running the SRW :ref:`locally `, in addition to an overview of the :ref:`release components `, a description of the supported capabilities, and details on where to find more information and obtain support. The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research conducted with the App: @@ -155,7 +155,7 @@ Under the ``regional_workflow`` directory shown in :numref:`TopLevelDirStructure Experiment Directory Structure -------------------------------- -When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Step %s `), a user-defined experimental directory is created based on information specified in the ``config.sh`` file. :numref:`Table %s ` shouws the contents of the experiment directory before the experiment workflow is run. +When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Step %s `), a user-defined experimental directory is created based on information specified in the ``config.sh`` file. :numref:`Table %s ` shouws the contents of the experiment directory before the experiment workflow is run. .. _ExptDirStructure: @@ -320,7 +320,7 @@ The SRW Application has a portable CMake-based build system that packages togeth The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. -This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW code ` without first installing prerequisites. On other platforms, the SRW must be :ref:`run within a container ` that contains the HPC-Stack, or the required libraries (i.e., HPC-Stack) will need to be installed as part of the :ref:`non-container `) SRW installation process. Once these prerequisite libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW code ` without first installing prerequisites. On other platforms, the SRW must be :ref:`run within a container ` that contains the HPC-Stack, or the required libraries (i.e., HPC-Stack) will need to be installed as part of the :ref:`non-container `) SRW installation process. Once these prerequisite libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. User Support, Documentation, and Contributions to Development =============================================================== diff --git a/docs/UsersGuide/source/Quickstart_Container.rst b/docs/UsersGuide/source/Quickstart_Container.rst index c66a3abb5d..554ba9b743 100644 --- a/docs/UsersGuide/source/Quickstart_Container.rst +++ b/docs/UsersGuide/source/Quickstart_Container.rst @@ -4,7 +4,7 @@ Containerized Quick Start Guide (Recommended) ================================================= -This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a container. The container approach provides a uniform enviroment in which to build and run the SRW. Normally, the details of building and running the SRW vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions. Installation via an EPIC-provided container reduces this variability and allows for a smoother SRW build and run experience. +This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a container. The container approach provides a uniform enviroment in which to build and run the SRW. Normally, the details of building and running the SRW vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via an EPIC-provided container reduces this variability and allows for a smoother SRW build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW App. The "out-of-the-box" SRW case described in this guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. @@ -45,7 +45,7 @@ On NOAA Cloud systems, certain environment variables must be set *before* buildi Working on HPC Systems -------------------------- -Those *not* working on HPC systems may skip to the `next step `. +Those *not* working on HPC systems may skip to the :ref:`next step `. On HPC systems (including NOAA's Cloud platforms), allocate a compute node on which to run the SRW. On NOAA's Cloud platforms, the following commands should work: .. code-block:: console @@ -83,7 +83,7 @@ The command above also binds the local directory to the container so that data c .. attention:: * When binding two directories, they must have the same name. It may be necessary to ``cd`` into the container and create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. - * Be sure to bind the directory that contains the data the experiment will access. + * Be sure to bind the directory that contains the experiment data. .. _SetUpBuildC: @@ -95,6 +95,7 @@ If the SRW Application has been built in a container provided by the Earth Predi .. code-block:: console + cd ubuntu20.04-epic-srwapp-1.0/opt/ufs-srweather-app/ ln -s /usr/bin/python3 /usr/bin/python source /usr/share/lmod/6.6/init/profile module use /opt/hpc-modules/modulefiles/stack @@ -106,17 +107,17 @@ If the SRW Application has been built in a container provided by the Earth Predi Build the Executables ====================== -Create a directory to hold the build's executables: +From the ``ufs-srweather-app`` directory, ``cd`` into the build directory and run the script that builds the SRW App: .. code-block:: console - cd ubuntu20.04-epic-srwapp-1.0/opt/ufs-srweather-app/build + cd build source build-srw.sh Download and Stage the Data ============================ -The SRW requires input files to run. These include static datasets, initial and boundary conditions +The SRW requires input files to run. These include static datasets, initial and boundary condition files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. .. _GenerateForecastC: @@ -133,15 +134,15 @@ The first two steps depend on the platform being used and are described here for .. _SetUpConfigFileC: -Set Experiment Parameters -------------------------- +Set the Experiment Parameters +------------------------------- Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in the ``config.sh`` file. Two example ``config.sh`` templates are provided: ``config.community.sh`` and ``config.nco.sh``. They can be found in the ``ufs-srweather-app/regional_workflow/ush`` directory. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. Make a copy of ``config.community.sh`` to get started (under ``/regional_workflow/ush``). From the ``ufs-srweather-app`` directory, run: .. code-block:: console - cd ../regional_workflow/ush + cd regional_workflow/ush cp config.community.sh config.sh The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. @@ -183,8 +184,8 @@ On NOAA Cloud platforms, users may continue to the :ref:`next step `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in the experiment directory. +The generated workflow will be in the experiment directory specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in the experiment directory. + +.. _RunUsingStandaloneScripts: Run the Workflow Using Stand-Alone Scripts ============================================= @@ -234,6 +237,8 @@ Run the Workflow Using Stand-Alone Scripts .. note:: The Rocoto workflow manager cannot be used inside a container. +The regional workflow can be run using standalone shell scripts if the Rocoto software is not available on a given platform. If Rocoto *is* available, see `Section %s ` to run the workflow using Rocoto. + #. ``cd`` into the experiment directory #. Set the environment variable ``EXPTDIR`` for either bash or csh, respectively: @@ -243,7 +248,7 @@ Run the Workflow Using Stand-Alone Scripts export EXPTDIR=`pwd` setenv EXPTDIR `pwd` -#. COPY the wrapper scripts from the regional_workflow directory into your experiment directory: +#. Copy the wrapper scripts from the regional_workflow directory into your experiment directory. Each workflow task has a wrapper script that sets environment variables and run the job script. .. code-block:: console @@ -256,7 +261,7 @@ Run the Workflow Using Stand-Alone Scripts export OMP_NUM_THREADS=1 sed -i 's/bin\/sh/bin\/bash/g' *sh -#. RUN each of the listed scripts in order. Scripts with the same stage number (listed in :numref:`Table %s `) may be run simultaneously. +#. Run each of the listed scripts in order. Scripts with the same stage number (listed in :numref:`Table %s `) may be run simultaneously. .. code-block:: console @@ -270,6 +275,51 @@ Run the Workflow Using Stand-Alone Scripts ./run_fcst.sh ./run_post.sh +Check the batch script output file in your experiment directory for a “SUCCESS” message near the end of the file. + +.. hint:: + If any of the scripts return an error that "Primary job terminated normally, but one process returned a non-zero exit code," there may not be enough space on one node to run the process. On an HPC system, the user will need to allocate a(nother) compute node. The process for doing so is system-dependent, and users should check the documentation available for their HPC system. Instructions for allocating a compute node on NOAA Cloud systems can be viewed in the :numref:`Step %s ` as an example. + +.. note:: + #. On most HPC systems, users will need to submit a batch job to run multi-processor jobs. On some HPC systems, users may be able to run the first two jobs (serial) on a login node/command-line. Example scripts for Slurm (Hera) and PBS (Cheyenne) resource managers are provided. These will need to be adapted to each user's system. This submit batch script is hard-coded per task, so it will need to be modified or copied to run each task. + + +.. _RegionalWflowTasks: + +.. table:: List of tasks in the regional workflow in the order that they are executed. + Scripts with the same stage number may be run simultaneously. The number of + processors and wall clock time is a good starting point for Cheyenne or Hera + when running a 48-h forecast on the 25-km CONUS domain. + + +------------+------------------------+----------------+----------------------------+ + | **Stage/** | **Task Run Script** | **Number of** | **Wall clock time (H:MM)** | + | **step** | | **Processors** | | + +============+========================+================+============================+ + | 1 | run_get_ics.sh | 1 | 0:20 (depends on HPSS vs | + | | | | FTP vs staged-on-disk) | + +------------+------------------------+----------------+----------------------------+ + | 1 | run_get_lbcs.sh | 1 | 0:20 (depends on HPSS vs | + | | | | FTP vs staged-on-disk) | + +------------+------------------------+----------------+----------------------------+ + | 1 | run_make_grid.sh | 24 | 0:20 | + +------------+------------------------+----------------+----------------------------+ + | 2 | run_make_orog.sh | 24 | 0:20 | + +------------+------------------------+----------------+----------------------------+ + | 3 | run_make_sfc_climo.sh | 48 | 0:20 | + +------------+------------------------+----------------+----------------------------+ + | 4 | run_make_ics.sh | 48 | 0:30 | + +------------+------------------------+----------------+----------------------------+ + | 4 | run_make_lbcs.sh | 48 | 0:30 | + +------------+------------------------+----------------+----------------------------+ + | 5 | run_fcst.sh | 48 | 0:30 | + +------------+------------------------+----------------+----------------------------+ + | 6 | run_post.sh | 48 | 0:25 (2 min per output | + | | | | forecast hour) | + +------------+------------------------+----------------+----------------------------+ + +Example batch-submit scripts for Hera (Slurm) and Cheyenne (PBS) are included (``sq_job.sh`` +and ``qsub_job.sh``, respectively). These examples set the build and run environment for Hera or Cheyenne so that run-time libraries match the compiled libraries (i.e. netCDF, MPI). Users may either modify the submit batch script as each task is submitted, or duplicate this batch wrapper +for their system settings for each task. Alternatively, some batch systems allow users to specify most of the settings on the command line (with the ``sbatch`` or ``qsub`` command, for example). This piece will be unique to your platform. The tasks run by the regional workflow are shown in :numref:`Table %s `. Tasks with the same stage level may be run concurrently (no dependency). Plot the Output =============== diff --git a/docs/UsersGuide/source/Quickstart_NonContainer.rst b/docs/UsersGuide/source/Quickstart_NonContainer.rst index 4339c5ab79..7b0bd6195f 100644 --- a/docs/UsersGuide/source/Quickstart_NonContainer.rst +++ b/docs/UsersGuide/source/Quickstart_NonContainer.rst @@ -1,17 +1,39 @@ -.. _QuickstartNC: +.. _BuildRunSRW: -====================================== -Workflow Quick Start (Non-Container) -====================================== +============================================== +Building and Running the SRW (Non-Container) +============================================== -This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application. The "out-of-the-box" case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. +The UFS Short-Range Weather Application (SRW App) is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. Once the SRW App is configured and built, users can generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. + +This chapter walks users through how to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application. However, the steps are relevant to any SRW experiment and can be modified to suit user goals. The "out-of-the-box" SRW case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: - The UFS defines `four platform levels `_. The steps described in this chapter are most applicable to preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems as well but may require additional troubleshooting by the user. + The UFS defines `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems, too, but the user need to perform additional troubleshooting. .. note:: - The :ref:`container approach ` is recommended when possible for a smoother build and run experience. Building without a container allows for use of the Rocoto workflow manager and may allow for more cutomization; however, this comes at the expense of more in-depth troubleshooting, especially on Level 3 and 4 systems. + The :ref:`container approach ` is recommended for a smoother build and run experience. Building without a container allows for the use of the Rocoto workflow manager and may allow for more cutomization. However, the non-container approach requires more in-depth troubleshooting skills, especially on Level 3 and 4 systems, and is less appropriate for beginners. + +The overall procedure for generating an experiment is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. The steps are as follows: + + * :ref:`Install prerequisites ` + * :ref:`Clone the SRW App from GitHub ` + * :ref:`Check out the external repositories ` + * :ref:`Set up the build environment ` + * :ref:`Build the executables ` + * :ref:`Download and stage data ` + * :ref:`Optional: Configure a new grid ` + * :ref:`Configure the experiment ` + * :ref:`Load the python environment for the regional workflow ` + * :ref:`Generate a regional workflow experiment ` + * :ref:`Run the regional workflow ` + +.. _AppOverallProc: + +.. figure:: _static/FV3LAM_wflow_overall.png + + *Overall layout of the SRW App* .. _HPCstackInfo: @@ -20,28 +42,26 @@ Install the HPC-Stack ======================== .. Attention:: - Skip the HPC-stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion). + Skip the HPC-Stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion, NOAA Cloud). -**Definition:** :term:`HPC-stack` is a repository that provides a unified, shell script-based build system that builds the software stack required for the `Unified Forecast System (UFS) `_ and applications. +**Definition:** :term:`HPC-Stack` is a repository that provides a unified, shell script-based build system and builds the software stack required for the `Unified Forecast System (UFS) `_ and applications. Background ---------------- -The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF etc) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `__ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW. +The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF, etc.) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `__ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW. Instructions ------------------------- -`Level 1 `_ platforms (e.g. Cheyenne, Hera) already have the HPC-Stack installed. Users on those platforms do *not* need to install the HPC-Stack before building applications or models that require the HPC-Stack. Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to run applications or models that depend on it. - -Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. +Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to run applications (such as the SRW) or models that depend on it. Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. After completing installation, continue to the next section. -.. _DownloadCodeNC: +.. _DownloadSRWApp: Download the UFS SRW Application Code ===================================== -The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. +The SRW Application source code is publicly available on GitHub. It relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. Clone the release branch of the repository: @@ -52,31 +72,84 @@ Clone the release branch of the repository: .. COMMENT: This will need to be changed to the updated release branch of the SRW repo once it exists. -Then, run the executable that pulls in the submodules for the SRW Application: +The cloned repository contains the configuration files and sub-directories shown in +:numref:`Table %s `. + +.. _FilesAndSubDirs: + +.. table:: Files and sub-directories of the ufs-srweather-app repository + + +--------------------------------+--------------------------------------------------------+ + | **File/directory Name** | **Description** | + +================================+========================================================+ + | CMakeLists.txt | Main cmake file for SRW App | + +--------------------------------+--------------------------------------------------------+ + | Externals.cfg | Tags of the GitHub repositories/branches for the | + | | external repositories | + +--------------------------------+--------------------------------------------------------+ + | LICENSE.md | CC0 license information | + +--------------------------------+--------------------------------------------------------+ + | README.md | Getting Started Guide | + +--------------------------------+--------------------------------------------------------+ + | ufs_srweather_app_meta.h.in | Meta information for SRW App which can be used by | + | | other packages | + +--------------------------------+--------------------------------------------------------+ + | ufs_srweather_app.settings.in | SRW App configuration summary | + +--------------------------------+--------------------------------------------------------+ + | env | Contains build and workflow environment files | + +--------------------------------+--------------------------------------------------------+ + | docs | Contains release notes, documentation, and Users' Guide| + +--------------------------------+--------------------------------------------------------+ + | manage_externals | Utility for checking out external repositories | + +--------------------------------+--------------------------------------------------------+ + | src | Contains CMakeLists.txt; external repositories | + | | will be cloned in this directory. | + +--------------------------------+--------------------------------------------------------+ + + +.. _CheckoutExternals: + +Check Out External Components +================================ + +Next, run the executable that pulls in SRW components from external repositories, including the regional_workflow, ufs-weather-model, ufs_utils, and upp repositories: .. code-block:: console cd ufs-srweather-app ./manage_externals/checkout_externals +This step will use the configuration file ``Externals.cfg`` in the ``ufs-srweather-app`` directory to clone the correct tags (code versions) of the external repositories listed in :numref:`Section %s `. -.. _SetUpBuildNC: +.. _SetUpBuild: Set up the Build Environment ============================ -For Level 1 and 2 systems, scripts for loading the proper modules and/or setting the -correct environment variables can be found in the ``env/`` directory of the SRW App in files named -``build__.env``. The commands in these files can be directly copy-pasted -to the command line, or the file can be sourced from the ufs-srweather-app ``env/`` directory. -For example, on Hera, run ``source env/build_hera_intel.env`` from the main ufs-srweather-app -directory to source the appropriate file. +Before building the SRW App, the build environment must be set up for the user's specific platform. For Level 1 systems, scripts for loading the proper modules and/or setting the correct environment variables can be found in the ``env`` directory of the SRW App in files named ``build__.env``. Here is a sample directory listing of these build files: + +.. code-block:: console + + $ ls -l env/ + -rw-rw-r-- 1 user ral 1228 Oct 9 10:09 build_cheyenne_intel.env + -rw-rw-r-- 1 user ral 1134 Oct 9 10:09 build_hera_intel.env + -rw-rw-r-- 1 user ral 1228 Oct 9 10:09 build_jet_intel.env + ... + +On Level 1 systems, the commands in the ``build__.env`` files can be directly copy-pasted into the command line, or the file can be sourced from the ufs-srweather-app ``env`` directory. For example, on Hera, run: + +.. code-block:: -On Level 3-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. On systems without Lmod, this process will typically involve commands in the form ``export =``. You may need to use ``setenv`` rather than ``export`` depending on your environment. + source env/build_hera_intel.env +from the main ufs-srweather-app directory to source the appropriate file. + +On Level 2-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. To check if Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, this process will typically involve commands in the form ``export =``. You may need to use ``setenv`` rather than ``export`` depending on your shell environment. + +.. _BuildExecutables: Build the Executables -===================== +======================= Create a directory to hold the build's executables: @@ -85,26 +158,109 @@ Create a directory to hold the build's executables: mkdir build cd build -From the build directory, run the ``cmake`` command below to set up the ``Makefile``, then run the ``make`` command to build the executables: +From the build directory, run the following commands to build the pre-processing utilities, forecast model, and post-processor: .. code-block:: console cmake .. -DCMAKE_INSTALL_PREFIX=.. make -j 4 >& build.out & -The build will take a few minutes to complete. When it starts, a random number is printed to the console, and when it is done, a ``[1]+ Done`` message is printed to the console when you list the files in ``ufs-srweather-app/bin`` (``[1]+ Exit`` may indicate an error). Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, you should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. +``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, and ``share`` directories will be created. These directories will contain various components of the SRW App. Its recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. + +The build will take a few minutes to complete. When it starts, a random number is printed to the console, and when it is done, a ``[1]+ Done`` message is printed to the console. ``[1]+ Exit`` indicates an error. Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, users should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. .. hint:: If you see the build.out file, but there is no ``ufs-srweather-app/bin`` directory, wait a few more minutes for the build to complete. +.. _ExecDescription: + +.. table:: Names and descriptions of the executables produced by the build step and used by the SRW App + + +------------------------+---------------------------------------------------------------------------------+ + | **Executable Name** | **Description** | + +========================+=================================================================================+ + | chgres_cube | Reads in raw external model (global or regional) and surface climatology data | + | | to create initial and lateral boundary conditions | + +------------------------+---------------------------------------------------------------------------------+ + | filter_topo | Filters topography based on resolution | + +------------------------+---------------------------------------------------------------------------------+ + | global_equiv_resol | Calculates a global, uniform, cubed-sphere equivalent resolution for the | + | | regional Extended Schmidt Gnomonic (ESG) grid | + +------------------------+---------------------------------------------------------------------------------+ + | make_solo_mosaic | Creates mosaic files with halos | + +------------------------+---------------------------------------------------------------------------------+ + | upp.x | Post-processor for the model output | + +------------------------+---------------------------------------------------------------------------------+ + | ufs_model | UFS Weather Model executable | + +------------------------+---------------------------------------------------------------------------------+ + | orog | Generates orography, land mask, and gravity wave drag files from fixed files | + +------------------------+---------------------------------------------------------------------------------+ + | regional_esg_grid | Generates an ESG regional grid based on a user-defined namelist | + +------------------------+---------------------------------------------------------------------------------+ + | sfc_climo_gen | Creates surface climatology fields from fixed files for use in ``chgres_cube`` | + +------------------------+---------------------------------------------------------------------------------+ + | shave | Shaves the excess halo rows down to what is required for the LBCs in the | + | | orography and grid files | + +------------------------+---------------------------------------------------------------------------------+ + | vcoord_gen | Generates hybrid coordinate interface profiles | + +------------------------+---------------------------------------------------------------------------------+ + | fvcom_to_FV3 | Determine lake surface conditions for the Great Lakes | + +------------------------+---------------------------------------------------------------------------------+ + | make_hgrid | Computes geo-referencing parameters (e.g., latitude, longitude, grid cell area) | + | | for global uniform grids | + +------------------------+---------------------------------------------------------------------------------+ + | emcsfc_ice_blend | Blends National Ice Center sea ice cover and EMC sea ice concentration data to | + | | create a global sea ice analysis used to update the GFS once per day | + +------------------------+---------------------------------------------------------------------------------+ + | emcsfc_snow2mdl | Blends National Ice Center snow cover and Air Force snow depth data to create a | + | | global depth analysis used to update the GFS snow field once per day | + +------------------------+---------------------------------------------------------------------------------+ + | global_cycle | Updates the GFS surface conditions using external snow and sea ice analyses | + +------------------------+---------------------------------------------------------------------------------+ + | inland | Creates an inland land mask by determining in-land (i.e. non-coastal) points | + | | and assigning a value of 1. Default value is 0. | + +------------------------+---------------------------------------------------------------------------------+ + | orog_gsl | Ceates orographic statistics fields required for the orographic drag suite | + | | developed by NOAA's Global Systems Laboratory (GSL) | + +------------------------+---------------------------------------------------------------------------------+ + | fregrid | Remaps data from the input mosaic grid to the output mosaic grid | + +------------------------+---------------------------------------------------------------------------------+ + | lakefrac | Calculates the ratio of the lake area to the grid cell area at each atmospheric | + | | grid point. | + +------------------------+---------------------------------------------------------------------------------+ + +.. _Data: + Download and Stage the Data ============================ The SRW requires input files to run. These include static datasets, initial and boundary conditions files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. -.. _GenerateForecastNC: +.. _GridSpecificConfig: + +Grid Configuration +======================= + +The SRW App officially supports three different predefined grids as shown in :numref:`Table %s `. The "out-of-the-box" SRW case uses the ``RRFS_CONUS_25km`` predefined grid option. More information on the predefined and user-generated grid options can be found in :numref:`Chapter %s ` for those who are curious. Users who plan to utilize one of the three pre-defined domain (grid) options may continue to :numref:`Step %s `. Users who plan to create a new domain should refer to :numref:`Chapter %s ` for details on how to do so. At a minimum, they will need to add the new grid name to the ``valid_param_vals`` script and add the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. + +.. _PredefinedGrids: + +.. table:: Predefined grids in the SRW App + + +----------------------+-------------------+--------------------------------+ + | **Grid Name** | **Grid Type** | **Quilting (write component)** | + +======================+===================+================================+ + | RRFS_CONUS_25km | ESG grid | lambert_conformal | + +----------------------+-------------------+--------------------------------+ + | RRFS_CONUS_13km | ESG grid | lambert_conformal | + +----------------------+-------------------+--------------------------------+ + | RRFS_CONUS_3km | ESG grid | lambert_conformal | + +----------------------+-------------------+--------------------------------+ + + +.. _GenerateForecast: Generate the Forecast Experiment ================================= @@ -116,36 +272,219 @@ Generating the forecast experiment requires three steps: The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. -.. _SetUpConfigFileNC: +.. _ExptConfig: Set Experiment Parameters -------------------------- -Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in the ``config.sh`` file. Two example ``config.sh`` templates are provided: ``config.community.sh`` and ``config.nco.sh``. They can be found in the ``ufs-srweather-app/regional_workflow/ush`` directory. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. +---------------------------- + +Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in ``config_defaults.sh`` and in the user-specific ``config.sh`` file. When generating a new experiment, the SRW App first reads and assigns default values from the ``config_defaults.sh`` file. Then, it reads and (re)assigns variables from the user's custom ``config.sh`` file. For background info on ``config_defaults.sh``, read :numref:`Section %s ` or jump to :numref:`Section %s ` to continue configuring the experiment. + +.. _DefaultConfigSection: -Make a copy of ``config.community.sh`` to get started (under ``/regional_workflow/ush``). From the ``ufs-srweather-app`` directory, run: +Default configuration: ``config_defaults.sh`` +------------------------------------------------ + +.. note:: + Users may skip to :numref:`Step %s `. This section provides background information on how the SRW App uses the ``config_defaults.sh`` file, but this information is not necessary for running the SRW. + +Important configuration variables in the ``config_defaults.sh`` file appear in +:numref:`Table %s `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified configuration ``config.sh`` file. Any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` +settings. There is usually no need for a user to modify the default configuration file. Additional information on the default settings can be found in the file itself and in :numref:`Chapter %s `. + +.. _ConfigVarsDefault: + +.. table:: Configuration variables specified in the config_defaults.sh script. + + +----------------------+------------------------------------------------------------+ + | **Group Name** | **Configuration variables** | + +======================+============================================================+ + | Experiment mode | RUN_ENVIR | + +----------------------+------------------------------------------------------------+ + | Machine and queue | MACHINE, ACCOUNT, SCHED, PARTITION_DEFAULT, QUEUE_DEFAULT, | + | | PARTITION_HPSS, QUEUE_HPSS, PARTITION_FCST, QUEUE_FCST | + +----------------------+------------------------------------------------------------+ + | Cron | USE_CRON_TO_RELAUNCH, CRON_RELAUNCH_INTVL_MNTS | + +----------------------+------------------------------------------------------------+ + | Experiment Dir. | EXPT_BASEDIR, EXPT_SUBDIR | + +----------------------+------------------------------------------------------------+ + | NCO mode | COMINgfs, STMP, NET, envir, RUN, PTMP | + +----------------------+------------------------------------------------------------+ + | Separator | DOT_OR_USCORE | + +----------------------+------------------------------------------------------------+ + | File name | EXPT_CONFIG_FN, RGNL_GRID_NML_FN, DATA_TABLE_FN, | + | | DIAG_TABLE_FN, FIELD_TABLE_FN, FV3_NML_BASE_SUITE_FN, | + | | FV3_NML_YALM_CONFIG_FN, FV3_NML_BASE_ENS_FN, | + | | MODEL_CONFIG_FN, NEMS_CONFIG_FN, FV3_EXEC_FN, | + | | WFLOW_XML_FN, GLOBAL_VAR_DEFNS_FN, | + | | EXTRN_MDL_ICS_VAR_DEFNS_FN, EXTRN_MDL_LBCS_VAR_DEFNS_FN, | + | | WFLOW_LAUNCH_SCRIPT_FN, WFLOW_LAUNCH_LOG_FN | + +----------------------+------------------------------------------------------------+ + | Forecast | DATE_FIRST_CYCL, DATE_LAST_CYCL, CYCL_HRS, FCST_LEN_HRS | + +----------------------+------------------------------------------------------------+ + | IC/LBC | EXTRN_MDL_NAME_ICS, EXTRN_MDL_NAME_LBCS, | + | | LBC_SPEC_INTVL_HRS, FV3GFS_FILE_FMT_ICS, | + | | FV3GFS_FILE_FMT_LBCS | + +----------------------+------------------------------------------------------------+ + | NOMADS | NOMADS, NOMADS_file_type | + +----------------------+------------------------------------------------------------+ + | External model | USE_USER_STAGED_EXTRN_FILES, EXTRN_MDL_SOURCE_BASEDRI_ICS, | + | | EXTRN_MDL_FILES_ICS, EXTRN_MDL_SOURCE_BASEDIR_LBCS, | + | | EXTRN_MDL_FILES_LBCS | + +----------------------+------------------------------------------------------------+ + | CCPP | CCPP_PHYS_SUITE | + +----------------------+------------------------------------------------------------+ + | GRID | GRID_GEN_METHOD | + +----------------------+------------------------------------------------------------+ + | ESG grid | ESGgrid_LON_CTR, ESGgrid_LAT_CTR, ESGgrid_DELX, | + | | ESGgrid_DELY, ESGgrid_NX, ESGgrid_NY, | + | | ESGgrid_WIDE_HALO_WIDTH | + +----------------------+------------------------------------------------------------+ + | Input configuration | DT_ATMOS, LAYOUT_X, LAYOUT_Y, BLOCKSIZE, QUILTING, | + | | PRINT_ESMF, WRTCMP_write_groups, | + | | WRTCMP_write_tasks_per_group, WRTCMP_output_grid, | + | | WRTCMP_cen_lon, WRTCMP_cen_lat, WRTCMP_lon_lwr_left, | + | | WRTCMP_lat_lwr_left, WRTCMP_lon_upr_rght, | + | | WRTCMP_lat_upr_rght, WRTCMP_dlon, WRTCMP_dlat, | + | | WRTCMP_stdlat1, WRTCMP_stdlat2, WRTCMP_nx, WRTCMP_ny, | + | | WRTCMP_dx, WRTCMP_dy | + +----------------------+------------------------------------------------------------+ + | Pre-existing grid | PREDEF_GRID_NAME, PREEXISTING_DIR_METHOD, VERBOSE | + +----------------------+------------------------------------------------------------+ + | Cycle-independent | RUN_TASK_MAKE_GRID, GRID_DIR, RUN_TASK_MAKE_OROG, | + | | OROG_DIR, RUN_TASK_MAKE_SFC_CLIMO, SFC_CLIMO_DIR | + +----------------------+------------------------------------------------------------+ + | Surface climatology | SFC_CLIMO_FIELDS, FIXgsm, TOPO_DIR, SFC_CLIMO_INPUT_DIR, | + | | FNGLAC, FNMXIC, FNTSFC, FNSNOC, FNZORC, FNAISC, FNSMCC, | + | | FNMSKH, FIXgsm_FILES_TO_COPY_TO_FIXam, | + | | FV3_NML_VARNAME_TO_FIXam_FILES_MAPPING, | + | | FV3_NML_VARNAME_TO_SFC_CLIMO_FIELD_MAPPING, | + | | CYCLEDIR_LINKS_TO_FIXam_FILES_MAPPING | + +----------------------+------------------------------------------------------------+ + | Workflow task | MAKE_GRID_TN, MAKE_OROG_TN, MAKE_SFC_CLIMO_TN, | + | | GET_EXTRN_ICS_TN, GET_EXTRN_LBCS_TN, MAKE_ICS_TN, | + | | MAKE_LBCS_TN, RUN_FCST_TN, RUN_POST_TN | + +----------------------+------------------------------------------------------------+ + | NODE | NNODES_MAKE_GRID, NNODES_MAKE_OROG, NNODES_MAKE_SFC_CLIMO, | + | | NNODES_GET_EXTRN_ICS, NNODES_GET_EXTRN_LBCS, | + | | NNODES_MAKE_ICS, NNODES_MAKE_LBCS, NNODES_RUN_FCST, | + | | NNODES_RUN_POST | + +----------------------+------------------------------------------------------------+ + | MPI processes | PPN_MAKE_GRID, PPN_MAKE_OROG, PPN_MAKE_SFC_CLIMO, | + | | PPN_GET_EXTRN_ICS, PPN_GET_EXTRN_LBCS, PPN_MAKE_ICS, | + | | PPN_MAKE_LBCS, PPN_RUN_FCST, PPN_RUN_POST | + +----------------------+------------------------------------------------------------+ + | Walltime | WTIME_MAKE_GRID, WTIME_MAKE_OROG, WTIME_MAKE_SFC_CLIMO, | + | | WTIME_GET_EXTRN_ICS, WTIME_GET_EXTRN_LBCS, WTIME_MAKE_ICS, | + | | WTIME_MAKE_LBCS, WTIME_RUN_FCST, WTIME_RUN_POST | + +----------------------+------------------------------------------------------------+ + | Maximum attempt | MAXTRIES_MAKE_GRID, MAXTRIES_MAKE_OROG, | + | | MAXTRIES_MAKE_SFC_CLIMO, MAXTRIES_GET_EXTRN_ICS, | + | | MAXTRIES_GET_EXTRN_LBCS, MAXTRIES_MAKE_ICS, | + | | MAXTRIES_MAKE_LBCS, MAXTRIES_RUN_FCST, MAXTRIES_RUN_POST | + +----------------------+------------------------------------------------------------+ + | Post configuration | USE_CUSTOM_POST_CONFIG_FILE, CUSTOM_POST_CONFIG_FP | + +----------------------+------------------------------------------------------------+ + | Running ensembles | DO_ENSEMBLE, NUM_ENS_MEMBERS | + +----------------------+------------------------------------------------------------+ + | Stochastic physics | DO_SHUM, DO_SPPT, DO_SKEB, SHUM_MAG, SHUM_LSCALE, | + | | SHUM_TSCALE, SHUM_INT, SPPT_MAG, SPPT_LSCALE, SPPT_TSCALE, | + | | SPPT_INT, SKEB_MAG, SKEB_LSCALE, SKEP_TSCALE, SKEB_INT, | + | | SKEB_VDOF, USE_ZMTNBLCK | + +----------------------+------------------------------------------------------------+ + | Boundary blending | HALO_BLEND | + +----------------------+------------------------------------------------------------+ + | FVCOM | USE_FVCOM, FVCOM_DIR, FVCOM_FILE | + +----------------------+------------------------------------------------------------+ + | Compiler | COMPILER | + +----------------------+------------------------------------------------------------+ + + +.. _UserSpecificConfig: + +User-specific configuration: ``config.sh`` +-------------------------------------------- + +The user must specify certain basic information about the experiment in a ``config.sh`` file located in the ``ufs-srweather-app/regional_workflow/ush`` directory. Two example templates are provided in the ``ufs-srweather-app/regional_workflow/ush`` directory: ``config.community.sh`` and ``config.nco.sh``. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. The operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing. :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. + +.. _ConfigCommunity: + +.. table:: Configuration variables specified in the config.community.sh script + + +--------------------------------+-------------------+--------------------------------------------------------+ + | **Parameter** | **Default Value** | **config.community.sh Value** | + +================================+===================+========================================================+ + | MACHINE | "BIG_COMPUTER" | "hera" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | ACCOUNT | "project_name" | "an_account" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXPT_SUBDIR | "" | "test_CONUS_25km_GFSv15p2" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | VERBOSE | "TRUE" | "TRUE" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | RUN_ENVIR | "nco" | "community" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | PREEXISTING_DIR_METHOD | "delete" | "rename" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | PREDEF_GRID_NAME | "" | "RRFS_CONUS_25km" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | GRID_GEN_METHOD | "ESGgrid" | "ESGgrid" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | QUILTING | "TRUE" | "TRUE" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | CCPP_PHYS_SUITE | "FV3_GSD_V0" | "FV3_GFS_v15p2" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | FCST_LEN_HRS | "24" | "48" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | LBC_SPEC_INTVL_HRS | "6" | "6" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | DATE_FIRST_CYCL | "YYYYMMDD" | "20190615" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | DATE_LAST_CYCL | "YYYYMMDD" | "20190615" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | CYCL_HRS | ("HH1" "HH2") | "00" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_NAME_ICS | "FV3GFS" | "FV3GFS" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_NAME_LBCS | "FV3GFS" | "FV3GFS" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | FV3GFS_FILE_FMT_ICS | "nemsio" | "grib2" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | FV3GFS_FILE_FMT_LBCS | "nemsio" | "grib2" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | WTIME_RUN_FCST | "04:30:00" | "01:00:00" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | USE_USER_STAGED_EXTRN_FILES | "FALSE" | "TRUE" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_SOURCE_BASE_DIR_ICS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_FILES_ICS | "" | "gfs.pgrb2.0p25.f000" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_SOURCE_BASEDIR_LBCS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_FILES_LBCS | "" | "gfs.pgrb2.0p25.f006" | + +--------------------------------+-------------------+--------------------------------------------------------+ + + +To get started, make a copy of ``config.community.sh`` (under ``/regional_workflow/ush``). From the ``ufs-srweather-app`` directory, run: .. code-block:: console - cd ../regional_workflow/ush + cd regional_workflow/ush cp config.community.sh config.sh The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. -Next, edit the new ``config.sh`` file to customize it for your machine. At a minimum, change the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If you have pre-staged the initialization data for the experiment, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and set the paths to the data for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. For example: +Next, edit the new ``config.sh`` file to customize it for your machine. At a minimum, change the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If you have pre-staged the initialization data for the experiment, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and set the paths to the data for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. -.. code-block:: console +Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. - MACHINE="SINGULARITY" - ACCOUNT="none" - EXPT_SUBDIR="GST" - EXPT_BASEDIR="home/$USER/expt_dirs" - COMPILER="gnu" +.. important:: -Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. + If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. -.. Important:: +.. hint:: - If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. + To determine an appropriate ACCOUNT field for Level 1 systems, run ``groups``, and it will return a list of projects you have permissions for. Not all of the listed projects/groups have an HPC allocation, but those that do are potentially valid account names. Minimum parameter settings for Level 1 machines: @@ -191,11 +530,18 @@ For **WCOSS**, edit ``config.sh`` with these WCOSS-specific parameters, and use EXPT_BASEDIR="lustre/$USER/expt_dirs" COMPILER="gnu" USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/GST/model_data/FV3GFS" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/EPIC/model_data/FV3GFS" EXTRN_MDL_FILES_ICS=( "gfs.pgrb2.0p25.f000" ) - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/GST/model_data/FV3GFS" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/EPIC/model_data/FV3GFS" EXTRN_MDL_FILES_LBCS=( "gfs.pgrb2.0p25.f006" "gfs.pgrb2.0p25.f012" ) +.. note:: + + The values of the configuration variables should be consistent with those in the + ``valid_param_vals script``. In addition, various example configuration files can be + found in the ``regional_workflow/tests/baseline_configs`` directory. + + .. _SetUpPythonEnv: @@ -221,15 +567,26 @@ This command will activate the ``regional_workflow``. The user should see ``(reg Generate the Regional Workflow ------------------------------------------- -Run the following command to generate the workflow: +Run the following command from the ``ufs-srweather-app/regional_workflow/ush`` directory to generate the workflow: .. code-block:: console ./generate_FV3LAM_wflow.sh -The last line of output from this script, starting with ``*/1 * * * *``, can be saved and :ref:`used later ` to automatically run portions of the workflow. +The last line of output from this script, starting with ``*/1 * * * *`` or ``*/3 * * * *``, can be saved and :ref:`used later ` to automatically run portions of the workflow. + +This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The flowchart in :numref:`Figure %s ` describes the experiment generation process. First, ``generate_FV3LAM_wflow.sh`` runs the ``setup.sh`` script to set the configuration parameters. Second, it copies the time-independent (fix) files and other necessary data input files from their location in the ufs-weather-model directory to the experiment directory (``$EXPTDIR``). Third, it copies the weather model executable (``ufs_model``) from the ``bin`` directory to ``$EXPTDIR`` and creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` file in the regional_workflow/ush/templates directory. Lastly, it creates the workflow XML file ``FV3LAM_wflow.xml`` that is executed when running the experiment with the Rocoto workflow manager. + +The ``setup.sh`` script reads three other configuration scripts in order: (1) ``config_default.sh`` (:numref:`Section %s `), (2) ``config.sh`` (:numref:`Section %s `), and (3) ``set_predef_grid_params.sh`` (:numref:`Section %s `). If a parameter is specified differently in these scripts, the file containing the last defined value will be used. + +The generated workflow will appear in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in ``$EXPTDIR``. + +.. _WorkflowGeneration: + +.. figure:: _static/FV3regional_workflow_gen.png + + *Experiment generation description* -This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The generated workflow will be in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in $EXPTDIR. An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: @@ -239,9 +596,11 @@ An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is csh/tcsh, replace ``export`` with ``setenv`` in the command above. +.. _RocotoRun: + Run the Workflow Using Rocoto ============================= -The information in this section assumes that Rocoto is available on the desired platform. Rocoto cannot be used when running the workflow within a container. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: using the ``./launch_FV3LAM_wflow.sh`` or by hand. +The information in this section assumes that Rocoto is available on the desired platform. (Note that Rocoto cannot be used when running the workflow within a container.) If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: using the ``./launch_FV3LAM_wflow.sh`` or by hand. Launch the Rocoto Workflow Using a Script ----------------------------------------------- @@ -361,7 +720,7 @@ If the experiment fails, the ``rocotostat`` command will indicate which task fai Additional Options ---------------------- -For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry by entering the ``crontab -e`` command, which opens a crontab file. As mentioned in `Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *``), can be pasted into the crontab file. It can also be found in the``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: +For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry by entering the ``crontab -e`` command, which opens a crontab file. As mentioned in :ref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *``), can be pasted into the crontab file. It can also be found in the``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: .. code-block:: console diff --git a/docs/UsersGuide/source/SRWAppOverview.rst b/docs/UsersGuide/source/SRWAppOverview.rst index 0e320c7dd8..2d846bb5da 100644 --- a/docs/UsersGuide/source/SRWAppOverview.rst +++ b/docs/UsersGuide/source/SRWAppOverview.rst @@ -1,440 +1,15 @@ .. _SRWAppOverview: =========================================================== -Building and Running the Short-Range Weather Application +Overview of the Short-Range Weather Application Workflow =========================================================== -The UFS Short-Range Weather Application (SRW App) is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. The SRW App assembles the required components using the ``manage_externals/checkout_externals`` script. Once the -build process is complete, all the files and executables necessary for a regional experiment are -located in the ``regional_workflow`` and ``bin`` directories, respectively, under the ``ufs-srweather-app`` directory. Users can utilize the pre-defined domains (grids) or build their own domain (see :numref:`Chapter %s ` for details). In either case, users must create/modify the case-specific (``config.sh``) and/or grid-specific configuration files (``set_predef_grid_params.sh``). The overall procedure is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. The steps are as follows: - - * :ref:`Clone the SRW App from GitHub. ` - * :ref:`Check out the external repositories. ` - * :ref:`Set up the build environment and build the regional workflow system. ` - * :ref:`Optional: Configure a new grid. ` - * :ref:`Configure the experiment. ` - * :ref:`Load the python environment for the regional workflow. ` - * :ref:`Generate a regional workflow experiment. ` - * :ref:`Run the regional workflow. ` - -Each step will be described in detail in the following sections. - -.. _AppOverallProc: - -.. figure:: _static/FV3LAM_wflow_overall.png - - *Overall layout of the SRW App* - -.. _DownloadSRWApp: - -Download the SRW App -======================== -Retrieve the UFS Short Range Weather Application (SRW App) repository from GitHub and checkout the ``ufs-v1.0.0`` tag: - -.. code-block:: console - - git clone -b ufs-v1.0.0 https://github.com/ufs-community/ufs-srweather-app.git - cd ufs-srweather-app - -.. - COMMENT: Change version number in 2 places above! - -The cloned repository contains the configuration files and sub-directories shown in -:numref:`Table %s `. - -.. _FilesAndSubDirs: - -.. table:: Files and sub-directories of the ufs-srweather-app repository - - +--------------------------------+--------------------------------------------------------+ - | **File/directory Name** | **Description** | - +================================+========================================================+ - | CMakeLists.txt | Main cmake file for SRW App | - +--------------------------------+--------------------------------------------------------+ - | Externals.cfg | Tags of the GitHub repositories/branches for the | - | | external repositories | - +--------------------------------+--------------------------------------------------------+ - | LICENSE.md | CC0 license information | - +--------------------------------+--------------------------------------------------------+ - | README.md | Getting Started Guide | - +--------------------------------+--------------------------------------------------------+ - | ufs_srweather_app_meta.h.in | Meta information for SRW App which can be used by | - | | other packages | - +--------------------------------+--------------------------------------------------------+ - | ufs_srweather_app.settings.in | SRW App configuration summary | - +--------------------------------+--------------------------------------------------------+ - | env | Contains build and workflow environment files | - +--------------------------------+--------------------------------------------------------+ - | docs | Contains release notes, documentation, and Users' Guide| - +--------------------------------+--------------------------------------------------------+ - | manage_externals | Utility for checking out external repositories | - +--------------------------------+--------------------------------------------------------+ - | src | Contains CMakeLists.txt; external repositories | - | | will be cloned in this directory. | - +--------------------------------+--------------------------------------------------------+ - -.. _CheckoutExternals: - -External Components -=================== -Retrieve required components from external repositories, including regional_workflow, ufs-weather-model, ufs_utils, and upp.x: - -.. code-block:: console - - ./manage_externals/checkout_externals - -This step will use the configuration file ``Externals.cfg`` in the ``ufs-srweather-app`` directory to clone the correct tags (code versions) of the external repositories as listed in :numref:`Section %s `. - -.. _BuildExecutables: - -Building the Executables for the Application -============================================ -Before building the executables, the build environment must be set up for your specific platform. Instructions for loading the proper modules and/or setting the correct environment variables can be found in the ``env/`` directory in files named ``build__.env.`` For the most part, the commands in those files can be directly copied and pasted, but you may need to modify certain variables such as the path to NCEP libraries for your specific platform. Here is a directory listing example of these kinds of files: - -.. code-block:: console - - $ ls -l env/ - -rw-rw-r-- 1 user ral 1228 Oct 9 10:09 build_cheyenne_intel.env - -rw-rw-r-- 1 user ral 1134 Oct 9 10:09 build_hera_intel.env - -rw-rw-r-- 1 user ral 1228 Oct 9 10:09 build_jet_intel.env - ... - -The following steps will build the pre-processing utilities, forecast model, and post-processor: - -.. code-block:: console - - mkdir build - cd build - cmake .. -DCMAKE_INSTALL_PREFIX=.. - make -j 4 >& build.out & - -where ``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, and ``share`` directories containing various components of the SRW App will be created, and its recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. If this step is successful, the executables listed in :numref:`Table %s ` will be located in the ``ufs-srweather-app/bin`` directory. - -.. _ExecDescription: - -.. table:: Names and descriptions of the executables produced by the build step and used by the SRW App. - - +------------------------+---------------------------------------------------------------------------------+ - | **Executable Name** | **Description** | - +========================+=================================================================================+ - | chgres_cube | Reads in raw external model (global or regional) and surface climatology data | - | | to create initial and lateral boundary conditions | - +------------------------+---------------------------------------------------------------------------------+ - | filter_topo | Filters topography based on resolution | - +------------------------+---------------------------------------------------------------------------------+ - | global_equiv_resol | Calculates a global, uniform, cubed-sphere equivalent resolution for the | - | | regional Extended Schmidt Gnomonic (ESG) grid | - +------------------------+---------------------------------------------------------------------------------+ - | make_solo_mosaic | Creates mosaic files with halos | - +------------------------+---------------------------------------------------------------------------------+ - | upp.x | Post-processor for the model output | - +------------------------+---------------------------------------------------------------------------------+ - | ufs_model | UFS Weather Model executable | - +------------------------+---------------------------------------------------------------------------------+ - | orog | Generates orography, land mask, and gravity wave drag files from fixed files | - +------------------------+---------------------------------------------------------------------------------+ - | regional_esg_grid | Generates an ESG regional grid based on a user-defined namelist | - +------------------------+---------------------------------------------------------------------------------+ - | sfc_climo_gen | Creates surface climatology fields from fixed files for use in ``chgres_cube`` | - +------------------------+---------------------------------------------------------------------------------+ - | shave | Shaves the excess halo rows down to what is required for the LBCs in the | - | | orography and grid files | - +------------------------+---------------------------------------------------------------------------------+ - | vcoord_gen | Generates hybrid coordinate interface profiles | - +------------------------+---------------------------------------------------------------------------------+ - | fvcom_to_FV3 | | - +------------------------+---------------------------------------------------------------------------------+ - | make_hgrid | Computes geo-referencing parameters (e.g., latitude, longitude, grid cell area) | - | | for global uniform grids | - +------------------------+---------------------------------------------------------------------------------+ - | emcsfc_ice_blend | Blends National Ice Center sea ice cover and EMC sea ice concentration data to | - | | create a global sea ice analysis used to update the GFS once per day | - +------------------------+---------------------------------------------------------------------------------+ - | emcsfc_snow2mdl | Blends National Ice Center snow cover and Air Force snow depth data to create a | - | | global depth analysis used to update the GFS snow field once per day | - +------------------------+---------------------------------------------------------------------------------+ - | global_cycle | Updates the GFS surface conditions using external snow and sea ice analyses | - +------------------------+---------------------------------------------------------------------------------+ - | inland | Create an inland land mask | - +------------------------+---------------------------------------------------------------------------------+ - | orog_gsl | Ceates orographic statistics fields required for the orographic drag suite | - | | developed by NOAA's Global Systems Laboratory (GSL) | - +------------------------+---------------------------------------------------------------------------------+ - | fregrid | Remaps data from the input mosaic grid to the output mosaic grid | - +------------------------+---------------------------------------------------------------------------------+ - | lakefrac | Set lake fraction and depth | - +------------------------+---------------------------------------------------------------------------------+ - -.. _GridSpecificConfig: - -Grid-specific Configuration -=========================== - -Some SRW App parameters depend on the characteristics of the grid such as resolution and domain size. These include ``ESG grid`` and ``Input configuration`` as well as the variables related to the write component (quilting). The SRW App officially supports three different predefined grids as shown in :numref:`Table %s `. Their names can be found under ``valid_vals_PREDEF_GRID_NAME`` in the ``valid_param_vals`` script, and their grid-specific configuration variables are specified in the ``set_predef_grid_params`` script. If users want to create a new domain, they should put its name in the ``valid_param_vals`` script and the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. More information on the predefined and user-generated options -can be found in :numref:`Chapter %s `. - -.. _PredefinedGrids: - -.. table:: Predefined grids in the SRW App. - - +----------------------+-------------------+--------------------------------+ - | **Grid Name** | **Grid Type** | **Quilting (write component)** | - +======================+===================+================================+ - | RRFS_CONUS_25km | ESG grid | lambert_conformal | - +----------------------+-------------------+--------------------------------+ - | RRFS_CONUS_13km | ESG grid | lambert_conformal | - +----------------------+-------------------+--------------------------------+ - | RRFS_CONUS_3km | ESG grid | lambert_conformal | - +----------------------+-------------------+--------------------------------+ - -Case-specific Configuration -============================= - -When generating a new experiment (described in detail in :numref:`Section %s `), the SRW App first reads and assigns default values from the ``config_defaults.sh`` file. Then, it reads and (re)assigns variables from the user's custom ``config.sh`` file, located in the -``ufs-srweather-app/regional_workflow/ush`` directory. - -.. _DefaultConfigSection: - -Default configuration: ``config_defaults.sh`` ------------------------------------------------- -Important configuration variables in the ``config_defaults.sh`` file appear in -:numref:`Table %s `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified configuration ``config.sh`` file. Any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` -settings. Note that there is usually no need for a user to modify the default configuration file. Additional information on the default settings can be found in the file itself and -in :numref:`Chapter %s `. - -.. _ConfigVarsDefault: - -.. table:: Configuration variables specified in the config_defaults.sh script. - - +----------------------+------------------------------------------------------------+ - | **Group Name** | **Configuration variables** | - +======================+============================================================+ - | Experiment mode | RUN_ENVIR | - +----------------------+------------------------------------------------------------+ - | Machine and queue | MACHINE, ACCOUNT, SCHED, PARTITION_DEFAULT, QUEUE_DEFAULT, | - | | PARTITION_HPSS, QUEUE_HPSS, PARTITION_FCST, QUEUE_FCST | - +----------------------+------------------------------------------------------------+ - | Cron | USE_CRON_TO_RELAUNCH, CRON_RELAUNCH_INTVL_MNTS | - +----------------------+------------------------------------------------------------+ - | Experiment Dir. | EXPT_BASEDIR, EXPT_SUBDIR | - +----------------------+------------------------------------------------------------+ - | NCO mode | COMINgfs, STMP, NET, envir, RUN, PTMP | - +----------------------+------------------------------------------------------------+ - | Separator | DOT_OR_USCORE | - +----------------------+------------------------------------------------------------+ - | File name | EXPT_CONFIG_FN, RGNL_GRID_NML_FN, DATA_TABLE_FN, | - | | DIAG_TABLE_FN, FIELD_TABLE_FN, FV3_NML_BASE_SUITE_FN, | - | | FV3_NML_YALM_CONFIG_FN, FV3_NML_BASE_ENS_FN, | - | | MODEL_CONFIG_FN, NEMS_CONFIG_FN, FV3_EXEC_FN, | - | | WFLOW_XML_FN, GLOBAL_VAR_DEFNS_FN, | - | | EXTRN_MDL_ICS_VAR_DEFNS_FN, EXTRN_MDL_LBCS_VAR_DEFNS_FN, | - | | WFLOW_LAUNCH_SCRIPT_FN, WFLOW_LAUNCH_LOG_FN | - +----------------------+------------------------------------------------------------+ - | Forecast | DATE_FIRST_CYCL, DATE_LAST_CYCL, CYCL_HRS, FCST_LEN_HRS | - +----------------------+------------------------------------------------------------+ - | IC/LBC | EXTRN_MDL_NAME_ICS, EXTRN_MDL_NAME_LBCS, | - | | LBC_SPEC_INTVL_HRS, FV3GFS_FILE_FMT_ICS, | - | | FV3GFS_FILE_FMT_LBCS | - +----------------------+------------------------------------------------------------+ - | NOMADS | NOMADS, NOMADS_file_type | - +----------------------+------------------------------------------------------------+ - | External model | USE_USER_STAGED_EXTRN_FILES, EXTRN_MDL_SOURCE_BASEDRI_ICS, | - | | EXTRN_MDL_FILES_ICS, EXTRN_MDL_SOURCE_BASEDIR_LBCS, | - | | EXTRN_MDL_FILES_LBCS | - +----------------------+------------------------------------------------------------+ - | CCPP | CCPP_PHYS_SUITE | - +----------------------+------------------------------------------------------------+ - | GRID | GRID_GEN_METHOD | - +----------------------+------------------------------------------------------------+ - | ESG grid | ESGgrid_LON_CTR, ESGgrid_LAT_CTR, ESGgrid_DELX, | - | | ESGgrid_DELY, ESGgrid_NX, ESGgrid_NY, | - | | ESGgrid_WIDE_HALO_WIDTH | - +----------------------+------------------------------------------------------------+ - | Input configuration | DT_ATMOS, LAYOUT_X, LAYOUT_Y, BLOCKSIZE, QUILTING, | - | | PRINT_ESMF, WRTCMP_write_groups, | - | | WRTCMP_write_tasks_per_group, WRTCMP_output_grid, | - | | WRTCMP_cen_lon, WRTCMP_cen_lat, WRTCMP_lon_lwr_left, | - | | WRTCMP_lat_lwr_left, WRTCMP_lon_upr_rght, | - | | WRTCMP_lat_upr_rght, WRTCMP_dlon, WRTCMP_dlat, | - | | WRTCMP_stdlat1, WRTCMP_stdlat2, WRTCMP_nx, WRTCMP_ny, | - | | WRTCMP_dx, WRTCMP_dy | - +----------------------+------------------------------------------------------------+ - | Pre-existing grid | PREDEF_GRID_NAME, PREEXISTING_DIR_METHOD, VERBOSE | - +----------------------+------------------------------------------------------------+ - | Cycle-independent | RUN_TASK_MAKE_GRID, GRID_DIR, RUN_TASK_MAKE_OROG, | - | | OROG_DIR, RUN_TASK_MAKE_SFC_CLIMO, SFC_CLIMO_DIR | - +----------------------+------------------------------------------------------------+ - | Surface climatology | SFC_CLIMO_FIELDS, FIXgsm, TOPO_DIR, SFC_CLIMO_INPUT_DIR, | - | | FNGLAC, FNMXIC, FNTSFC, FNSNOC, FNZORC, FNAISC, FNSMCC, | - | | FNMSKH, FIXgsm_FILES_TO_COPY_TO_FIXam, | - | | FV3_NML_VARNAME_TO_FIXam_FILES_MAPPING, | - | | FV3_NML_VARNAME_TO_SFC_CLIMO_FIELD_MAPPING, | - | | CYCLEDIR_LINKS_TO_FIXam_FILES_MAPPING | - +----------------------+------------------------------------------------------------+ - | Workflow task | MAKE_GRID_TN, MAKE_OROG_TN, MAKE_SFC_CLIMO_TN, | - | | GET_EXTRN_ICS_TN, GET_EXTRN_LBCS_TN, MAKE_ICS_TN, | - | | MAKE_LBCS_TN, RUN_FCST_TN, RUN_POST_TN | - +----------------------+------------------------------------------------------------+ - | NODE | NNODES_MAKE_GRID, NNODES_MAKE_OROG, NNODES_MAKE_SFC_CLIMO, | - | | NNODES_GET_EXTRN_ICS, NNODES_GET_EXTRN_LBCS, | - | | NNODES_MAKE_ICS, NNODES_MAKE_LBCS, NNODES_RUN_FCST, | - | | NNODES_RUN_POST | - +----------------------+------------------------------------------------------------+ - | MPI processes | PPN_MAKE_GRID, PPN_MAKE_OROG, PPN_MAKE_SFC_CLIMO, | - | | PPN_GET_EXTRN_ICS, PPN_GET_EXTRN_LBCS, PPN_MAKE_ICS, | - | | PPN_MAKE_LBCS, PPN_RUN_FCST, PPN_RUN_POST | - +----------------------+------------------------------------------------------------+ - | Walltime | WTIME_MAKE_GRID, WTIME_MAKE_OROG, WTIME_MAKE_SFC_CLIMO, | - | | WTIME_GET_EXTRN_ICS, WTIME_GET_EXTRN_LBCS, WTIME_MAKE_ICS, | - | | WTIME_MAKE_LBCS, WTIME_RUN_FCST, WTIME_RUN_POST | - +----------------------+------------------------------------------------------------+ - | Maximum attempt | MAXTRIES_MAKE_GRID, MAXTRIES_MAKE_OROG, | - | | MAXTRIES_MAKE_SFC_CLIMO, MAXTRIES_GET_EXTRN_ICS, | - | | MAXTRIES_GET_EXTRN_LBCS, MAXTRIES_MAKE_ICS, | - | | MAXTRIES_MAKE_LBCS, MAXTRIES_RUN_FCST, MAXTRIES_RUN_POST | - +----------------------+------------------------------------------------------------+ - | Post configuration | USE_CUSTOM_POST_CONFIG_FILE, CUSTOM_POST_CONFIG_FP | - +----------------------+------------------------------------------------------------+ - | Running ensembles | DO_ENSEMBLE, NUM_ENS_MEMBERS | - +----------------------+------------------------------------------------------------+ - | Stochastic physics | DO_SHUM, DO_SPPT, DO_SKEB, SHUM_MAG, SHUM_LSCALE, | - | | SHUM_TSCALE, SHUM_INT, SPPT_MAG, SPPT_LSCALE, SPPT_TSCALE, | - | | SPPT_INT, SKEB_MAG, SKEB_LSCALE, SKEP_TSCALE, SKEB_INT, | - | | SKEB_VDOF, USE_ZMTNBLCK | - +----------------------+------------------------------------------------------------+ - | Boundary blending | HALO_BLEND | - +----------------------+------------------------------------------------------------+ - | FVCOM | USE_FVCOM, FVCOM_DIR, FVCOM_FILE | - +----------------------+------------------------------------------------------------+ - | Compiler | COMPILER | - +----------------------+------------------------------------------------------------+ - -.. _UserSpecificConfig: - -User-specific configuration: ``config.sh`` ------------------------------------------- -The user must create a ``config.sh`` file in the ``ufs-srweather-app/regional_workflow/ush`` directory by copying either of the example configuration files (``config.community.sh`` for the community mode or ``config.nco.sh`` for the operational mode). Alternatively, the user can create a custom ``config.sh`` file from scratch. Note that the *community mode* is recommended in most cases and will be fully supported for this release while the operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing. :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. - -.. note:: - - The values of the configuration variables should be consistent with those in the - ``valid_param_vals script``. In addition, various example configuration files can be - found in the ``regional_workflow/tests/baseline_configs`` directory. - -.. _ConfigCommunity: - -.. table:: Configuration variables specified in the config.community.sh script - - +--------------------------------+-------------------+--------------------------------------------------------+ - | **Parameter** | **Default Value** | **``config.community.sh`` Value** | - +================================+===================+========================================================+ - | MACHINE | "BIG_COMPUTER" | "hera" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | ACCOUNT | "project_name" | "an_account" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | EXPT_SUBDIR | "" | "test_CONUS_25km_GFSv15p2" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | VERBOSE | "TRUE" | "TRUE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | RUN_ENVIR | "nco" | "community" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | PREEXISTING_DIR_METHOD | "delete" | "rename" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | PREDEF_GRID_NAME | "" | "RRFS_CONUS_25km" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | GRID_GEN_METHOD | "ESGgrid" | "ESGgrid" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | QUILTING | "TRUE" | "TRUE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | CCPP_PHYS_SUITE | "FV3_GSD_V0" | "FV3_GFS_v15p2" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | FCST_LEN_HRS | "24" | "48" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | LBC_SPEC_INTVL_HRS | "6" | "6" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | DATE_FIRST_CYCL | "YYYYMMDD" | "20190615" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | DATE_LAST_CYCL | "YYYYMMDD" | "20190615" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | CYCL_HRS | ("HH1" "HH2") | "00" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_NAME_ICS | "FV3GFS" | "FV3GFS" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_NAME_LBCS | "FV3GFS" | "FV3GFS" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | FV3GFS_FILE_FMT_ICS | "nemsio" | "grib2" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | FV3GFS_FILE_FMT_LBCS | "nemsio" | "grib2" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | WTIME_RUN_FCST | "04:30:00" | "01:00:00" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | USE_USER_STAGED_EXTRN_FILES | "FALSE" | "TRUE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_SOURCE_BASE_DIR_ICS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_FILES_ICS | "" | "gfs.pgrb2.0p25.f000" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_SOURCE_BASEDIR_LBCS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_FILES_LBCS | "" | "gfs.pgrb2.0p25.f006" | - +--------------------------------+-------------------+--------------------------------------------------------+ - - -.. _LoadPythonEnv: - -Python Environment for Workflow -=============================== -It is necessary to load the appropriate Python environment for the workflow. -The workflow requires Python 3, with the packages 'PyYAML', 'Jinja2', and 'f90nml' available. -This Python environment has already been set up on Level 1 platforms, and can be activated in -the following way: - -.. code-block:: console - - source ../../env/wflow_.env - -when in the ``ufs-srweather-app/regional_workflow/ush`` directory. - -.. _GeneratingWflowExpt: - -Generating a Regional Workflow Experiment -========================================= - -Steps to a Generate a New Experiment ----------------------------------------- -Generating an experiment requires running - -.. code-block:: console - - generate_FV3LAM_wflow.sh - -in the ``ufs-srweather-app/regional_workflow/ush`` directory. This is the all-in-one script for users -to set up their experiment with ease. :numref:`Figure %s ` shows the flowchart -for generating an experiment. First, it sets up the configuration parameters by running -the ``setup.sh`` script. Second, it copies the time-independent (fix) files and other necessary -input files such as ``data_table``, ``field_table``, ``nems.configure``, ``model_configure``, -and the CCPP suite file from its location in the ufs-weather-model directory to the experiment directory (``EXPTDIR``). -Third, it copies the weather model executable (``NEMS.exe``) from the ``bin`` directory to ``EXPTDIR``, -and creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` -file in the regional_workflow/ush/templates directory. Lastly, it creates the workflow XML file ``FV3LAM_wflow.xml`` -that is executed when running the experiment with the Rocoto workflow manager. - -.. _WorkflowGeneration: - -.. figure:: _static/FV3regional_workflow_gen.png - - *Experiment generation description* - -The ``setup.sh`` script reads three other configuration scripts: (1) ``config_default.sh`` (:numref:`Section %s `), (2) ``config.sh`` (:numref:`Section %s `), and (3) ``set_predef_grid_params.sh`` (:numref:`Section %s `). Note that these three scripts are read in order: ``config_default.sh``, ``config.sh``, then ``set_predef_grid_params.sh``. If a parameter is specified differently in these scripts, the file containing the last defined value will be used. .. _WorkflowTaskDescription: Description of Workflow Tasks ----------------------------- -The flowchart of the workflow tasks that are specified in the ``FV3LAM_wflow.xml`` file are -illustrated in :numref:`Figure %s `, and each task is described in -:numref:`Table %s `. The first three pre-processing tasks; ``MAKE_GRID``, -``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by setting ``RUN_TASK_MAKE_GRID=”FALSE”``, ``RUN_TASK_MAKE_OROG=”FALSE”``, and ``RUN_TASK_MAKE_SFC_CLIMO=”FALSE”`` in the ``regional_workflow/ush/config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script. As shown in the figure, the ``FV3LAM_wflow.xml`` file runs the specific j-job scripts in the prescribed order (``regional_workflow/jobs/JREGIONAL_[task name]``) when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own source script named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. +Workflow tasks are specified in the ``FV3LAM_wflow.xml`` file and illustrated in :numref:`Figure %s `. Each task is described in :numref:`Table %s `. The first three pre-processing tasks; ``MAKE_GRID``, ``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by setting ``RUN_TASK_MAKE_GRID=”FALSE”``, ``RUN_TASK_MAKE_OROG=”FALSE”``, and ``RUN_TASK_MAKE_SFC_CLIMO=”FALSE”`` in the ``regional_workflow/ush/config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script. As shown in the figure, the ``FV3LAM_wflow.xml`` file runs the specific j-job scripts in the prescribed order (``regional_workflow/jobs/JREGIONAL_[task name]``) when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own source script named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. .. _WorkflowTasksFig: @@ -537,8 +112,7 @@ This command will print out the status of the workflow tasks as follows: 0 out of 1 cycles completed. Workflow status: IN PROGRESS -Error messages for each task can be found in the task log files located in the ``EXPTDIR/log`` directory. In order to launch -more tasks in the workflow, you just need to call the launch script again as follows: +Error messages for each task can be found in the task log files located in the ``EXPTDIR/log`` directory. In order to launch more tasks in the workflow, you just need to call the launch script again: .. code-block:: console @@ -575,16 +149,17 @@ To launch the workflow manually, the ``rocoto`` module should be loaded: .. code-block:: console + module use rocoto module load rocoto -Then, launch the workflow as follows: +Then, launch the workflow: .. code-block:: console cd ${EXPTDIR} rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -To check the status of the workflow, issue a ``rocotostat`` command as follows: +To check the status of the workflow, issue a ``rocotostat`` command: .. code-block:: console @@ -598,114 +173,4 @@ Wait a few seconds and issue a second set of ``rocotorun`` and ``rocotostat`` co rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -.. _RunUsingStandaloneScripts: - -Run the Workflow Using the Stand-alone Scripts ----------------------------------------------- -The regional workflow has the capability to be run using standalone shell scripts if the Rocoto software is not available on a given platform. These scripts are located in the ``ufs-srweather-app/regional_workflow/ush/wrappers`` directory. Each workflow task has a wrapper script to set environment variables and run the job script. - -Example batch-submit scripts for Hera (Slurm) and Cheyenne (PBS) are included: ``sq_job.sh`` -and ``qsub_job.sh``, respectively. These examples set the build and run environment for Hera or Cheyenne so that run-time libraries match the compiled libraries (i.e. netCDF, MPI). Users may either modify the submit batch script as each task is submitted, or duplicate this batch wrapper -for their system settings for each task. Alternatively, some batch systems allow users to specify most of the settings on the command line (with the ``sbatch`` or ``qsub`` command, for example). This piece will be unique to your platform. The tasks run by the regional workflow are shown in :numref:`Table %s `. Tasks with the same stage level may be run concurrently (no dependency). - -.. _RegionalWflowTasks: - -.. table:: List of tasks in the regional workflow in the order that they are executed. - Scripts with the same stage number may be run simultaneously. The number of - processors and wall clock time is a good starting point for Cheyenne or Hera - when running a 48-h forecast on the 25-km CONUS domain. - - +------------+------------------------+----------------+----------------------------+ - | **Stage/** | **Task Run Script** | **Number of** | **Wall clock time (H:MM)** | - | **step** | | **Processors** | | - +============+========================+================+============================+ - | 1 | run_get_ics.sh | 1 | 0:20 (depends on HPSS vs | - | | | | FTP vs staged-on-disk) | - +------------+------------------------+----------------+----------------------------+ - | 1 | run_get_lbcs.sh | 1 | 0:20 (depends on HPSS vs | - | | | | FTP vs staged-on-disk) | - +------------+------------------------+----------------+----------------------------+ - | 1 | run_make_grid.sh | 24 | 0:20 | - +------------+------------------------+----------------+----------------------------+ - | 2 | run_make_orog.sh | 24 | 0:20 | - +------------+------------------------+----------------+----------------------------+ - | 3 | run_make_sfc_climo.sh | 48 | 0:20 | - +------------+------------------------+----------------+----------------------------+ - | 4 | run_make_ics.sh | 48 | 0:30 | - +------------+------------------------+----------------+----------------------------+ - | 4 | run_make_lbcs.sh | 48 | 0:30 | - +------------+------------------------+----------------+----------------------------+ - | 5 | run_fcst.sh | 48 | 0:30 | - +------------+------------------------+----------------+----------------------------+ - | 6 | run_post.sh | 48 | 0:25 (2 min per output | - | | | | forecast hour) | - +------------+------------------------+----------------+----------------------------+ - -The steps to run the standalone scripts are as follows: - -#. Clone and build the ufs-srweather-app following the steps - `here `_, or in - :numref:`Sections %s ` to :numref:`Section %s ` above. - -#. Generate an experiment configuration following the steps - `here `_, or in - :numref:`Section %s ` above. - -#. ``cd`` into the experiment directory - -#. Set the environment variable ``EXPTDIR`` for either csh and bash, respectively: - - .. code-block:: console - - setenv EXPTDIR `pwd` - export EXPTDIR=`pwd` - -#. COPY the wrapper scripts from the regional_workflow directory into your experiment directory: - - .. code-block:: console - - cp ufs-srweather-app/regional_workflow/ush/wrappers/* . - -#. Set the OMP_NUM_THREADS variable and fix dash/bash shell issue (this ensures the system does not use an alias of ``sh`` to dash). - - .. code-block:: console - - export OMP_NUM_THREADS=1 - sed -i 's/bin\/sh/bin\/bash/g' *sh - -#. RUN each of the listed scripts in order. Scripts with the same stage number (listed in :numref:`Table %s `) may be run simultaneously. - - .. code-block:: console - - ./run_make_grid.sh - ./run_get_ics.sh - ./run_get_lbcs.sh - ./run_make_orog.sh - ./run_make_sfc_climo.sh - ./run_make_ics.sh - ./run_make_lbcs.sh - ./run_fcst.sh - ./run_post.sh - - .. note:: - If any of the scripts return an error that "Primary job terminated normally, but one process returned a non-zero exit code," there may not be enough space on one node to run the process. To allocate a second node: - - .. code-block:: console - - salloc -N 1 - module load gnu openmpi - mpirun -n 1 hostname - - This last command will output a hostname. Then, run ``ssh ``, replacing ```` with the actual hostname output in the prior command. - - - #. On most HPC systems, you will need to submit a batch job to run multi-processor jobs. - - #. On some HPC systems, you may be able to run the first two jobs (serial) on a login node/command-line - - #. Example scripts for Slurm (Hera) and PBS (Cheyenne) are provided. These will need to be adapted to your system. - - #. This submit batch script is hard-coded per task, so will need to be modified or copied to run each task. - -Check the batch script output file in your experiment directory for a “SUCCESS” message near the end of the file. diff --git a/docs/UsersGuide/source/_static/theme_overrides.css b/docs/UsersGuide/source/_static/theme_overrides.css index f2b48b594c..9143850a43 100644 --- a/docs/UsersGuide/source/_static/theme_overrides.css +++ b/docs/UsersGuide/source/_static/theme_overrides.css @@ -10,5 +10,6 @@ .wy-table-responsive { overflow: visible !important; } + } diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index 4057dcee0d..ad0d16b25e 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -12,9 +12,9 @@ UFS Short-Range Weather App Users Guide Introduction + SRWAppOverview Quickstart_Container Quickstart_NonContainer - SRWAppOverview Components Include-HPCInstall InputOutputFiles From d1addf82b700b343779fdd737a2509061218461c Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 16 Mar 2022 14:50:38 -0400 Subject: [PATCH 053/158] finish merging non-container guide & SRWOverview, rename/remove files, update FAQ --- ...start_NonContainer.rst => BuildRunSRW.rst} | 163 +++++++++++++--- docs/UsersGuide/source/FAQ.rst | 46 +++-- docs/UsersGuide/source/Introduction.rst | 25 ++- ...uickstart_Container.rst => Quickstart.rst} | 6 +- docs/UsersGuide/source/SRWAppOverview.rst | 176 ------------------ docs/UsersGuide/source/index.rst | 5 +- 6 files changed, 186 insertions(+), 235 deletions(-) rename docs/UsersGuide/source/{Quickstart_NonContainer.rst => BuildRunSRW.rst} (82%) rename docs/UsersGuide/source/{Quickstart_Container.rst => Quickstart.rst} (99%) delete mode 100644 docs/UsersGuide/source/SRWAppOverview.rst diff --git a/docs/UsersGuide/source/Quickstart_NonContainer.rst b/docs/UsersGuide/source/BuildRunSRW.rst similarity index 82% rename from docs/UsersGuide/source/Quickstart_NonContainer.rst rename to docs/UsersGuide/source/BuildRunSRW.rst index 7b0bd6195f..1bfa8c1e2d 100644 --- a/docs/UsersGuide/source/Quickstart_NonContainer.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -1,8 +1,8 @@ .. _BuildRunSRW: -============================================== -Building and Running the SRW (Non-Container) -============================================== +===================================== +Building and Running the SRW +===================================== The UFS Short-Range Weather Application (SRW App) is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. Once the SRW App is configured and built, users can generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. @@ -24,10 +24,11 @@ The overall procedure for generating an experiment is shown in :numref:`Figure % * :ref:`Build the executables ` * :ref:`Download and stage data ` * :ref:`Optional: Configure a new grid ` - * :ref:`Configure the experiment ` - * :ref:`Load the python environment for the regional workflow ` * :ref:`Generate a regional workflow experiment ` + * :ref:`Configure the experiment parameters ` + * :ref:`Load the python environment for the regional workflow ` * :ref:`Run the regional workflow ` + * :ref:`Optional: Plot the output ` .. _AppOverallProc: @@ -266,9 +267,9 @@ Generate the Forecast Experiment ================================= Generating the forecast experiment requires three steps: -* Set experiment parameters -* Set Python and other environment parameters -* Run a script to generate the experiment workflow +* :ref:`Set experiment parameters ` +* :ref:`Set Python and other environment parameters ` +* :ref:`Run a script to generate the experiment workflow ` The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. @@ -562,7 +563,7 @@ This command will activate the ``regional_workflow``. The user should see ``(reg conda activate regional_workflow -.. _GenerateWorkflowNC: +.. _GenerateWorkflow: Generate the Regional Workflow ------------------------------------------- @@ -573,7 +574,7 @@ Run the following command from the ``ufs-srweather-app/regional_workflow/ush`` d ./generate_FV3LAM_wflow.sh -The last line of output from this script, starting with ``*/1 * * * *`` or ``*/3 * * * *``, can be saved and :ref:`used later ` to automatically run portions of the workflow. +The last line of output from this script, starting with ``*/1 * * * *`` or ``*/3 * * * *``, can be saved and :ref:`used later ` to automatically run portions of the workflow. This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The flowchart in :numref:`Figure %s ` describes the experiment generation process. First, ``generate_FV3LAM_wflow.sh`` runs the ``setup.sh`` script to set the configuration parameters. Second, it copies the time-independent (fix) files and other necessary data input files from their location in the ufs-weather-model directory to the experiment directory (``$EXPTDIR``). Third, it copies the weather model executable (``ufs_model``) from the ``bin`` directory to ``$EXPTDIR`` and creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` file in the regional_workflow/ush/templates directory. Lastly, it creates the workflow XML file ``FV3LAM_wflow.xml`` that is executed when running the experiment with the Rocoto workflow manager. @@ -587,45 +588,149 @@ The generated workflow will appear in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASED *Experiment generation description* +.. _WorkflowTaskDescription: -An environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: +Description of Workflow Tasks +-------------------------------- -.. code-block:: console +.. note:: + This section gives an overview of workflow tasks. To begin running the workflow, skip to :numref:`Step %s ` + +Workflow tasks are specified in the ``FV3LAM_wflow.xml`` file and illustrated in :numref:`Figure %s `. Each task is described in :numref:`Table %s `. The first three pre-processing tasks; ``MAKE_GRID``, ``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by setting ``RUN_TASK_MAKE_GRID=”FALSE”``, ``RUN_TASK_MAKE_OROG=”FALSE”``, and ``RUN_TASK_MAKE_SFC_CLIMO=”FALSE”`` in the ``regional_workflow/ush/config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script. As shown in the figure, the ``FV3LAM_wflow.xml`` file runs the specific j-job scripts in the prescribed order (``regional_workflow/jobs/JREGIONAL_[task name]``) when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own source script named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. + +.. _WorkflowTasksFig: + +.. figure:: _static/FV3LAM_wflow_flowchart.png + + *Flowchart of the workflow tasks* + +.. _WorkflowTasksTable: + +.. table:: Workflow tasks in SRW App + + +----------------------+------------------------------------------------------------+ + | **Workflow Task** | **Task Description** | + +======================+============================================================+ + | make_grid | Pre-processing task to generate regional grid files. Can | + | | be run, at most, once per experiment. | + +----------------------+------------------------------------------------------------+ + | make_orog | Pre-processing task to generate orography files. Can be | + | | run, at most, once per experiment. | + +----------------------+------------------------------------------------------------+ + | make_sfc_climo | Pre-processing task to generate surface climatology files. | + | | Can be run, at most, once per experiment. | + +----------------------+------------------------------------------------------------+ + | get_extrn_ics | Cycle-specific task to obtain external data for the | + | | initial conditions | + +----------------------+------------------------------------------------------------+ + | get_extrn_lbcs | Cycle-specific task to obtain external data for the | + | | lateral boundary (LB) conditions | + +----------------------+------------------------------------------------------------+ + | make_ics | Generate initial conditions from the external data | + +----------------------+------------------------------------------------------------+ + | make_lbcs | Generate lateral boundary conditions from the external data| + +----------------------+------------------------------------------------------------+ + | run_fcst | Run the forecast model (UFS weather model) | + +----------------------+------------------------------------------------------------+ + | run_post | Run the post-processing tool (UPP) | + +----------------------+------------------------------------------------------------+ - export EXPTDIR=// -If the login shell is csh/tcsh, replace ``export`` with ``setenv`` in the command above. .. _RocotoRun: Run the Workflow Using Rocoto ============================= -The information in this section assumes that Rocoto is available on the desired platform. (Note that Rocoto cannot be used when running the workflow within a container.) If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: using the ``./launch_FV3LAM_wflow.sh`` or by hand. +The information in this section assumes that Rocoto is available on the desired platform. (Note that Rocoto cannot be used when running the workflow within a container.) If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: (1) with the ``launch_FV3LAM_wflow.sh`` script, and (2) by manually calling the ``rocotorun`` command. Users can also automate the workflow using a crontab. + +Optionally, an environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: + +.. code-block:: console + + export EXPTDIR=// + +If the login shell is csh/tcsh, it can be set using: + +.. code-block:: console + + setenv EXPTDIR /path-to-experiment/directory + Launch the Rocoto Workflow Using a Script ----------------------------------------------- -To run Rocoto using the script provided: +To run Rocoto using the ``launch_FV3LAM_wflow.sh`` script provided, simply call it without any arguments: .. code-block:: console cd $EXPTDIR ./launch_FV3LAM_wflow.sh -Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named ``log.launch_FV3LAM_wflow`` will be created (or appended) in the ``EXPTDIR``. Check the end of the log file periodically to see how the experiment is progressing: +This script creates a log file named ``log.launch_FV3LAM_wflow`` in the EXPTDIR directory or appends information to it if the file already exists. Check the end of the log file periodically to see how the experiment is progressing: .. code-block:: console - cd $EXPTDIR - vi ``log.launch_FV3LAM_wflow`` + tail -n 30 log.launch_FV3LAM_wflow + +In order to launch additional tasks in the workflow, call the launch script again; this action will need to be repeated until all tasks in the workflow have been launched. To (re)launch the workflow and check its progress on a single line, run: + +.. code-block:: console + + ./launch_FV3LAM_wflow.sh; tail -n 80 log.launch_FV3LAM_wflow -Alternatively, to (re)launch the workflow and check its progress on a single line: +This will output the last 80 lines of the log file, which includes the status of the workflow tasks (e.g., SUCCEEDED, DEAD, RUNNING, SUBMITTING, QUEUED). The number 80 can be changed according to the user's preferences. The output will look like this: .. code-block:: console - ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + ====================================================================================================== + 202006170000 make_grid druby://hfe01:33728 SUBMITTING - 0 0.0 + 202006170000 make_orog - - - - - + 202006170000 make_sfc_climo - - - - - + 202006170000 get_extrn_ics druby://hfe01:33728 SUBMITTING - 0 0.0 + 202006170000 get_extrn_lbcs druby://hfe01:33728 SUBMITTING - 0 0.0 + 202006170000 make_ics - - - - - + 202006170000 make_lbcs - - - - - + 202006170000 run_fcst - - - - - + 202006170000 run_post_00 - - - - - + 202006170000 run_post_01 - - - - - + 202006170000 run_post_02 - - - - - + 202006170000 run_post_03 - - - - - + 202006170000 run_post_04 - - - - - + 202006170000 run_post_05 - - - - - + 202006170000 run_post_06 - - - - - + + Summary of workflow status: + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 0 out of 1 cycles completed. + Workflow status: IN PROGRESS + +Error messages for each specific task can be found in the task log files located in the ``$EXPTDIR/log`` directory. + +If everything goes smoothly, you will eventually get the following workflow status table as follows: -This will output the last 40 lines of the log file. The number 40 can be changed according to the user's preferences. +.. code-block:: console + + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + ====================================================================================================== + 202006170000 make_grid 8854765 SUCCEEDED 0 1 6.0 + 202006170000 make_orog 8854809 SUCCEEDED 0 1 27.0 + 202006170000 make_sfc_climo 8854849 SUCCEEDED 0 1 36.0 + 202006170000 get_extrn_ics 8854763 SUCCEEDED 0 1 54.0 + 202006170000 get_extrn_lbcs 8854764 SUCCEEDED 0 1 61.0 + 202006170000 make_ics 8854914 SUCCEEDED 0 1 119.0 + 202006170000 make_lbcs 8854913 SUCCEEDED 0 1 98.0 + 202006170000 run_fcst 8854992 SUCCEEDED 0 1 655.0 + 202006170000 run_post_00 8855459 SUCCEEDED 0 1 6.0 + 202006170000 run_post_01 8855460 SUCCEEDED 0 1 6.0 + 202006170000 run_post_02 8855461 SUCCEEDED 0 1 6.0 + 202006170000 run_post_03 8855462 SUCCEEDED 0 1 6.0 + 202006170000 run_post_04 8855463 SUCCEEDED 0 1 6.0 + 202006170000 run_post_05 8855464 SUCCEEDED 0 1 6.0 + 202006170000 run_post_06 8855465 SUCCEEDED 0 1 6.0 + +If all the tasks complete successfully, the workflow status in the log file will include the word “SUCCESS." Otherwise, the workflow status will include the word “FAILURE." Launch the Rocoto Workflow Manually @@ -634,7 +739,7 @@ Launch the Rocoto Workflow Manually Load Rocoto ^^^^^^^^^^^^^^^^ -Instead of running the ``./launch_FV3LAM_wflow.sh`` script, users can manually load Rocoto and any other required modules. This gives the user more control over the process and allows them to view experiment progress more easily. +Instead of running the ``./launch_FV3LAM_wflow.sh`` script, users can load Rocoto and any other required modules. This gives the user more control over the process and allows them to view experiment progress more easily. For most systems, a variant on the following commands will be necessary to load the Rocoto module: @@ -705,7 +810,7 @@ After loading Rocoto, call ``rocotorun`` from the experiment directory to launch The ``rocotorun`` and ``rocotostat`` commands will need to be resubmitted regularly and repeatedly until the experiment is finished. In part, this is to avoid having the system time out. This also ensures that when one task ends, tasks dependent on it will run as soon as possible, and ``rocotostat`` will capture the new progress. -If the experiment fails, the ``rocotostat`` command will indicate which task failed. Users can look at the log file in the ``log`` subdirectory for the failed task to determine what caused the failure. For example, if the ``make_grid`` task failed: +If the experiment fails, the ``rocotostat`` command will indicate which task failed. Users can look at the log file in the ``log`` subdirectory for the failed task to determine what caused the failure. For example, if the ``make_grid`` task failed, users can open the ``make_grid.log`` file to see what caused the problem: .. code-block:: console @@ -716,11 +821,11 @@ If the experiment fails, the ``rocotostat`` command will indicate which task fai If users have the `Slurm workload manager `_ on their system, they can run the ``squeue`` command in lieu of ``rocotostat`` to check what jobs are currently running. -.. _AdditionalOptions: +.. _Automate: -Additional Options +Automated Option ---------------------- -For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry by entering the ``crontab -e`` command, which opens a crontab file. As mentioned in :ref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *``), can be pasted into the crontab file. It can also be found in the``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: +For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry by entering the ``crontab -e`` command, which opens a crontab file. As mentioned in :ref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *``), can be pasted into the crontab file. It can also be found in the``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: .. code-block:: console @@ -728,7 +833,7 @@ For automatic resubmission of the workflow at regular intervals (e.g., every min where ```` is changed to correspond to the user's machine, and ``/apps/rocoto/1.3.3/bin/rocotorun`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can also be changed and simply means that the workflow will be resubmitted every minute. -Then, check the experiment progress with: +To check the experiment progress: .. code-block:: console @@ -760,6 +865,8 @@ The workflow run is completed when all tasks have “SUCCEEDED”, and the rocot ... 201906150000 run_post_f048 4953381 SUCCEEDED 0 1 7.0 +.. _PlotOutput: + Plot the Output =============== Two python scripts are provided to generate plots from the FV3-LAM post-processed GRIB2 output. Information on how to generate the graphics can be found in :numref:`Chapter %s `. diff --git a/docs/UsersGuide/source/FAQ.rst b/docs/UsersGuide/source/FAQ.rst index ee744db726..636e27ad21 100644 --- a/docs/UsersGuide/source/FAQ.rst +++ b/docs/UsersGuide/source/FAQ.rst @@ -1,17 +1,26 @@ .. _FAQ: -*** +**** FAQ -*** +**** + +* :ref:`How do I turn on/off the cycle-independent workflow tasks? ` +* :ref:`How do I define an experiment name? ` +* :ref:`How do I change the Physics Suite Definition File (SDF)? ` +* :ref:`How do I restart a DEAD task? ` +* :ref:`How do I change the grid? ` + +.. _CycleInd: + +=========================================================== +How do I turn on/off the cycle-independent workflow tasks? +=========================================================== -========================================================= -How do I turn On/Off the Cycle-Independent Workflow Tasks -========================================================= The first three pre-processing tasks ``make_grid``, ``make_orog``, and ``make_sfc_climo`` are cycle-independent, meaning that they only need to be run once per experiment. If the grid, orography, and surface climatology files that these tasks generate are already available (e.g. from a previous experiment that used the same grid as the current), then -these tasks can be skipped by having the workflow use those pre-generated files. This +these tasks can be skipped, and the workflow can use those pre-generated files. This can be done by adding the following lines to the ``config.sh`` script before running the ``generate_FV3LAM_wflow.sh`` script: @@ -28,26 +37,36 @@ The ``RUN_TASK_MAKE_GRID``, ``RUN_TASK_MAKE_OROG``, and ``RUN_TASK_MAKE_SFC_CLIM disable their respective tasks, and ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` specify the directories in which the workflow can find the pre-generated grid, orography, and surface climatology files, respectively (these directories may be the same, i.e. all -three sets of files may be placed in the same location). By default, the ``RUN_TASK_MAKE_...`` +three sets of files may be placed in the same location). By default, the ``RUN_TASK_MAKE_...`` flags are set to ``TRUE`` in ``config_defaults.sh``, i.e. the workflow will by default run the ``make_grid``, ``make_orog``, and ``make_sfc_climo`` tasks. +.. _DefineExptName: + =================================== How do I define an experiment name? =================================== + The name of the experiment is set in the ``config.sh`` file using the variable ``EXPT_SUBDIR``. -See :numref:`Section %s ` for more details. +See :numref:`Section %s ` for more details. + + +.. _ChangePhysics: + +========================================================= +How do I change the Physics Suite Definition File (SDF)? +========================================================= -================================================ -How do I change the Suite Definition File (SDF)? -================================================ The SDF is set in the ``config.sh`` file using the variable ``CCPP_PHYS_SUITE``. When the ``generate_FV3LAM_wflow.sh`` script is run, the SDF file is copied from its location in the forecast model directory to the experiment directory ``EXPTDIR``. +.. _RestartTask: + ============================= How do I restart a DEAD task? ============================= + On platforms that utilize Rocoto workflow software (such as NCAR’s Cheyenne machine), sometimes if something goes wrong with the workflow a task may end up in the DEAD state: @@ -70,12 +89,15 @@ command: rocotorewind -w FV3SAR_wflow.xml -d FV3SAR_wflow.db -v 10 -c 201905200000 -t get_extrn_ics where ``-c`` specifies the cycle date (first column of rocotostat output) and ``-t`` represents the task name -(second column of rocotostat output). After using ``rocotorewind``, the next time ``rocotorun`` is used to +(second column of rocotostat output). After using ``rocotorewind``, the next time ``rocotorun`` is used to advance the workflow, the job will be resubmitted. +.. _ChangeGrid: + =========================== How do I change the grid? =========================== + To change the predefined grid, you need to modify the ``PREDEF_GRID_NAME`` variable in the ``config.sh`` script which the user has created to generate an experiment configuration and workflow. Users can choose from one of three predefined grids for the SRW Application: diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index f67f240f25..cd8f699da7 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -6,7 +6,7 @@ Introduction The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. -The UFS can be configured for multiple applications (see the `complete list here `__). The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a Quick Start Guide for running the application :ref:`in a container ` and a detailed guide for running the SRW :ref:`locally `, in addition to an overview of the :ref:`release components `, a description of the supported capabilities, and details on where to find more information and obtain support. +The UFS can be configured for `multiple applications `__. The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a :ref:`Quick Start Guide ` for running the application in a container and a :ref:`detailed guide ` for running the SRW on supported platforms. It also provides an overview of the :ref:`release components ` and details on how to customize or modify different portions of the workflow. The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research conducted with the App: @@ -19,21 +19,21 @@ UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range How to Use This Document ======================== -This guide instructs both novice and experienced users on downloading, building, and running the SRW Application. Please post questions in the `UFS forum `__. +This guide instructs both novice and experienced users on downloading, building, and running the SRW Application. Please post questions in the `UFS Forum `__. .. code-block:: console Throughout the guide, this presentation style indicates shell commands and options, code examples, etc. -Variables presented as ``AaBbCc123`` in this document typically refer to variables in scripts, names of files, and directories. +Variables presented as ``AaBbCc123`` in this User's Guide typically refer to variables in scripts, names of files, and directories. -File paths or code that include angle brackets (e.g., ``env/build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``env/build_aws_gcc.env``). +File paths or code that include angle brackets (e.g., ``build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``build_orion_intel.env``). .. hint:: - * To get started running the SRW, see the :ref:`Containerized Quick Start Guide ` or refer to the in-depth chapter on :ref:`Running the Short-Range Weather Application `. + * To get started running the SRW, see the :ref:`Quick Start Guide ` for beginners or refer to the in-depth chapter on :ref:`Running the Short-Range Weather Application `. * For background information on the SRW code repositories and directory structure, see :numref:`Section %s ` below. - * For an outline of SRW components, see section :numref:`Section %s ` below or refer to :numref:`Chapter %s: Components ` for a more in-depth treatment. + * For an outline of SRW components, see section :numref:`Section %s ` below or refer to :numref:`Chapter %s ` for a more in-depth treatment. .. _SRWStructure: @@ -45,7 +45,7 @@ Code Repositories and Directory Structure Hierarchical Repository Structure ----------------------------------- -The umbrella repository for the UFS SRW Application is named *ufs-srweather-app* and is available on GitHub at https://github.com/ufs-community/ufs-srweather-app. An umbrella repository is a repository that houses external code, called "externals," from additional repositories. The UFS SRW Application includes the ``manage_externals`` tools along with a configuration file called ``Externals.cfg``, which describes the external repositories associated with this umbrella repository (see :numref:`Table %s `). +The :term:`umbrella repository` for the SRW Application is named ``ufs-srweather-app`` and is available on GitHub at https://github.com/ufs-community/ufs-srweather-app. An umbrella repository is a repository that houses external code, called "externals," from additional repositories. The SRW Application includes the ``manage_externals`` tool and a configuration file called ``Externals.cfg``, which describes the external repositories associated with the SRW umbrella repository (see :numref:`Table %s `). .. _top_level_repos: @@ -71,10 +71,9 @@ The umbrella repository for the UFS SRW Application is named *ufs-srweather-app* | Processor (UPP) | | +---------------------------------+---------------------------------------------------------+ -The UFS Weather Model contains a number of sub-repositories used by the model as -documented `here `__. +The UFS Weather Model contains a number of sub-repositories, which are documented `here `__. -Note that 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 the preconfigured (Level 1) platforms listed `here `__. However, it must be built on other systems. :numref:`Chapter %s ` contains details on installing the HPC-Stack. +Note that 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. .. _TopLevelDirStructure: @@ -128,7 +127,7 @@ The ``ufs-srweather-app`` :term:`umbrella repository` structure is determined by Regional Workflow Sub-Directories ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Under the ``regional_workflow`` directory shown in :numref:`TopLevelDirStructure`, a number of sub-directories are created when the regional workflow is cloned. The contents of these sub-directories are described in :numref:`Table %s `. +A number of sub-directories are created under the ``regional_workflow`` directory when the regional workflow is cloned (see directory diagram :ref:`above `). The contents of these sub-directories are described in :numref:`Table %s `. .. _Subdirectories: @@ -137,7 +136,7 @@ Under the ``regional_workflow`` directory shown in :numref:`TopLevelDirStructure +-------------------------+---------------------------------------------------------+ | **Directory Name** | **Description** | +=========================+=========================================================+ - | docs | Users' Guide Documentation | + | docs | User's Guide Documentation | +-------------------------+---------------------------------------------------------+ | jobs | J-job scripts launched by Rocoto | +-------------------------+---------------------------------------------------------+ @@ -155,7 +154,7 @@ Under the ``regional_workflow`` directory shown in :numref:`TopLevelDirStructure Experiment Directory Structure -------------------------------- -When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Step %s `), a user-defined experimental directory is created based on information specified in the ``config.sh`` file. :numref:`Table %s ` shouws the contents of the experiment directory before the experiment workflow is run. +When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Step %s `), a user-defined experimental directory is created based on information specified in the ``config.sh`` file. :numref:`Table %s ` shows the contents of the experiment directory before the experiment workflow is run. .. _ExptDirStructure: diff --git a/docs/UsersGuide/source/Quickstart_Container.rst b/docs/UsersGuide/source/Quickstart.rst similarity index 99% rename from docs/UsersGuide/source/Quickstart_Container.rst rename to docs/UsersGuide/source/Quickstart.rst index 554ba9b743..8e7f1f4aaf 100644 --- a/docs/UsersGuide/source/Quickstart_Container.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -1,8 +1,8 @@ .. _QuickstartC: -================================================= -Containerized Quick Start Guide (Recommended) -================================================= +==================================== +Quick Start Guide +==================================== This Workflow Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a container. The container approach provides a uniform enviroment in which to build and run the SRW. Normally, the details of building and running the SRW vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via an EPIC-provided container reduces this variability and allows for a smoother SRW build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW App. diff --git a/docs/UsersGuide/source/SRWAppOverview.rst b/docs/UsersGuide/source/SRWAppOverview.rst deleted file mode 100644 index 2d846bb5da..0000000000 --- a/docs/UsersGuide/source/SRWAppOverview.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. _SRWAppOverview: - -=========================================================== -Overview of the Short-Range Weather Application Workflow -=========================================================== - - -.. _WorkflowTaskDescription: - -Description of Workflow Tasks ------------------------------ -Workflow tasks are specified in the ``FV3LAM_wflow.xml`` file and illustrated in :numref:`Figure %s `. Each task is described in :numref:`Table %s `. The first three pre-processing tasks; ``MAKE_GRID``, ``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by setting ``RUN_TASK_MAKE_GRID=”FALSE”``, ``RUN_TASK_MAKE_OROG=”FALSE”``, and ``RUN_TASK_MAKE_SFC_CLIMO=”FALSE”`` in the ``regional_workflow/ush/config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script. As shown in the figure, the ``FV3LAM_wflow.xml`` file runs the specific j-job scripts in the prescribed order (``regional_workflow/jobs/JREGIONAL_[task name]``) when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own source script named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. - -.. _WorkflowTasksFig: - -.. figure:: _static/FV3LAM_wflow_flowchart.png - - *Flowchart of the workflow tasks* - -.. _WorkflowTasksTable: - -.. table:: Workflow tasks in SRW App - - +----------------------+------------------------------------------------------------+ - | **Workflow Task** | **Task Description** | - +======================+============================================================+ - | make_grid | Pre-processing task to generate regional grid files. Can | - | | be run, at most, once per experiment. | - +----------------------+------------------------------------------------------------+ - | make_orog | Pre-processing task to generate orography files. Can be | - | | run, at most, once per experiment. | - +----------------------+------------------------------------------------------------+ - | make_sfc_climo | Pre-processing task to generate surface climatology files. | - | | Can be run, at most, once per experiment. | - +----------------------+------------------------------------------------------------+ - | get_extrn_ics | Cycle-specific task to obtain external data for the | - | | initial conditions | - +----------------------+------------------------------------------------------------+ - | get_extrn_lbcs | Cycle-specific task to obtain external data for the | - | | lateral boundary (LB) conditions | - +----------------------+------------------------------------------------------------+ - | make_ics | Generate initial conditions from the external data | - +----------------------+------------------------------------------------------------+ - | make_lbcs | Generate lateral boundary conditions from the external data| - +----------------------+------------------------------------------------------------+ - | run_fcst | Run the forecast model (UFS weather model) | - +----------------------+------------------------------------------------------------+ - | run_post | Run the post-processing tool (UPP) | - +----------------------+------------------------------------------------------------+ - -Launch of Workflow -================== -There are two ways to launch the workflow using Rocoto: (1) with the ``launch_FV3LAM_wflow.sh`` -script, and (2) manually calling the ``rocotorun`` command. Moreover, you can run the workflow -separately using stand-alone scripts. - -An environment variable may be set to navigate to the ``$EXPTDIR`` more easily. If the login -shell is bash, it can be set as follows: - -.. code-block:: console - - export EXPTDIR=/path-to-experiment/directory - -Or if the login shell is csh/tcsh, it can be set using: - -.. code-block:: console - - setenv EXPTDIR /path-to-experiment/directory - -Launch with the ``launch_FV3LAM_wflow.sh`` script -------------------------------------------------- -To launch the ``launch_FV3LAM_wflow.sh`` script, simply call it without any arguments as follows: - -.. code-block:: console - - cd ${EXPTDIR} - ./launch_FV3LAM_wflow.sh - -This script creates a log file named ``log.launch_FV3LAM_wflow`` in the EXPTDIR directory -(described in :numref:`Section %s `) or appends to it if it already exists. -You can check the contents of the end of the log file (e.g. last 30 lines) using the command: - -.. code-block:: console - - tail -n 30 log.launch_FV3LAM_wflow - -This command will print out the status of the workflow tasks as follows: - -.. code-block:: console - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ====================================================================================================== - 202006170000 make_grid druby://hfe01:33728 SUBMITTING - 0 0.0 - 202006170000 make_orog - - - - - - 202006170000 make_sfc_climo - - - - - - 202006170000 get_extrn_ics druby://hfe01:33728 SUBMITTING - 0 0.0 - 202006170000 get_extrn_lbcs druby://hfe01:33728 SUBMITTING - 0 0.0 - 202006170000 make_ics - - - - - - 202006170000 make_lbcs - - - - - - 202006170000 run_fcst - - - - - - 202006170000 run_post_00 - - - - - - 202006170000 run_post_01 - - - - - - 202006170000 run_post_02 - - - - - - 202006170000 run_post_03 - - - - - - 202006170000 run_post_04 - - - - - - 202006170000 run_post_05 - - - - - - 202006170000 run_post_06 - - - - - - - Summary of workflow status: - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - - 0 out of 1 cycles completed. - Workflow status: IN PROGRESS - -Error messages for each task can be found in the task log files located in the ``EXPTDIR/log`` directory. In order to launch more tasks in the workflow, you just need to call the launch script again: - -.. code-block:: console - - ./launch_FV3LAM_wflow - -If everything goes smoothly, you will eventually get the following workflow status table as follows: - -.. code-block:: console - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ====================================================================================================== - 202006170000 make_grid 8854765 SUCCEEDED 0 1 6.0 - 202006170000 make_orog 8854809 SUCCEEDED 0 1 27.0 - 202006170000 make_sfc_climo 8854849 SUCCEEDED 0 1 36.0 - 202006170000 get_extrn_ics 8854763 SUCCEEDED 0 1 54.0 - 202006170000 get_extrn_lbcs 8854764 SUCCEEDED 0 1 61.0 - 202006170000 make_ics 8854914 SUCCEEDED 0 1 119.0 - 202006170000 make_lbcs 8854913 SUCCEEDED 0 1 98.0 - 202006170000 run_fcst 8854992 SUCCEEDED 0 1 655.0 - 202006170000 run_post_00 8855459 SUCCEEDED 0 1 6.0 - 202006170000 run_post_01 8855460 SUCCEEDED 0 1 6.0 - 202006170000 run_post_02 8855461 SUCCEEDED 0 1 6.0 - 202006170000 run_post_03 8855462 SUCCEEDED 0 1 6.0 - 202006170000 run_post_04 8855463 SUCCEEDED 0 1 6.0 - 202006170000 run_post_05 8855464 SUCCEEDED 0 1 6.0 - 202006170000 run_post_06 8855465 SUCCEEDED 0 1 6.0 - -If all the tasks complete successfully, the workflow status in the log file will include the word “SUCCESS." -Otherwise, the workflow status will include the word “FAILURE." - -Manually launch by calling the ``rocotorun`` command ----------------------------------------------------- -To launch the workflow manually, the ``rocoto`` module should be loaded: - -.. code-block:: console - - module use rocoto - module load rocoto - -Then, launch the workflow: - -.. code-block:: console - - cd ${EXPTDIR} - rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - -To check the status of the workflow, issue a ``rocotostat`` command: - -.. code-block:: console - - rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - -Wait a few seconds and issue a second set of ``rocotorun`` and ``rocotostat`` commands: - -.. code-block:: console - - rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - - - diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index ad0d16b25e..e66471d1e6 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -12,9 +12,8 @@ UFS Short-Range Weather App Users Guide Introduction - SRWAppOverview - Quickstart_Container - Quickstart_NonContainer + Quickstart + BuildRunSRW Components Include-HPCInstall InputOutputFiles From fc1a1d4cc40316355773996b74813dbf781d03c5 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 17 Mar 2022 09:58:11 -0400 Subject: [PATCH 054/158] minor edits for Intro & QS --- docs/UsersGuide/source/Components.rst | 1 + docs/UsersGuide/source/FAQ.rst | 2 +- docs/UsersGuide/source/Glossary.rst | 8 +- docs/UsersGuide/source/Introduction.rst | 158 ++++++++++++------------ docs/UsersGuide/source/Quickstart.rst | 72 +++++------ 5 files changed, 124 insertions(+), 117 deletions(-) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index bd8b22c254..ed3eff1f2a 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -13,6 +13,7 @@ The SRW Application v2.0 release assembles a variety of components, including: These components are documented within this User's Guide and supported through a `community forum `_. +.. _Utils: Pre-processor Utilities and Initial Conditions ============================================== diff --git a/docs/UsersGuide/source/FAQ.rst b/docs/UsersGuide/source/FAQ.rst index 636e27ad21..50d3141006 100644 --- a/docs/UsersGuide/source/FAQ.rst +++ b/docs/UsersGuide/source/FAQ.rst @@ -86,7 +86,7 @@ command: .. code-block:: console - rocotorewind -w FV3SAR_wflow.xml -d FV3SAR_wflow.db -v 10 -c 201905200000 -t get_extrn_ics + rocotorewind -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201905200000 -t get_extrn_ics where ``-c`` specifies the cycle date (first column of rocotostat output) and ``-t`` represents the task name (second column of rocotostat output). After using ``rocotorewind``, the next time ``rocotorun`` is used to diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 7099a6b1a2..ebded5df4a 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -15,6 +15,9 @@ Glossary Component Repository A :term:`repository` that contains, at a minimum, source code for a single component. + Container + `Docker `__ describes a container as "a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another." + CONUS Continental United States @@ -25,6 +28,9 @@ Glossary dynamical core Global atmospheric model based on fluid dynamics principles, including Euler's equations of motion. + EPIC + EPIC stands for the `Earth Prediction Innovation Center `__. EPIC seeks to accelerate scientific research and modeling contributions through continuous and sustained community engagement to produce the most accurate and reliable operational modeling system in the world. + FV3 The Finite-Volume Cubed-Sphere dynamical core (dycore). Developed at NOAA's Geophysical Fluid Dynamics Laboratory (GFDL), it is a scalable and flexible dycore capable of both @@ -78,7 +84,7 @@ Glossary NEMSIO A binary format for atmospheric model output from :term:`NCEP`'s Global Forecast System (GFS). - NWP (Numerical Weather Prediction) + NWP Numerical Weather Prediction (NWP) takes current observations of weather and processes them with computer models to forecast the future state of the weather. Orography diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index cd8f699da7..0cd418f402 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -33,7 +33,61 @@ File paths or code that include angle brackets (e.g., ``build__` for beginners or refer to the in-depth chapter on :ref:`Running the Short-Range Weather Application `. * For background information on the SRW code repositories and directory structure, see :numref:`Section %s ` below. - * For an outline of SRW components, see section :numref:`Section %s ` below or refer to :numref:`Chapter %s ` for a more in-depth treatment. + * For an outline of SRW components, see section :numref:`Section %s ` below or refer to :numref:`Chapter %s ` for a more in-depth treatment. + + +.. _ComponentsOverview: + +SRW Components Overview +============================ + +Pre-processor Utilities and Initial Conditions +------------------------------------------------ + +The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, these files are used as input to the atmospheric model (FV3-LAM). Additional information about the pre-processor utilities can be found in :numref:`Chapter %s ` and in the `UFS_UTILS User’s Guide `_. + + +Forecast Model +----------------- + +Atmospheric Model +^^^^^^^^^^^^^^^^^^^^^^ + +The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere +(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability (:cite:t:`BlackEtAl2020`). +The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. + +Common Community Physics Package +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and Noah Multi-parameterization (Noah MP) Land Surface Model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW release includes an experimental physics version and an updated operational version. + +Data Format +^^^^^^^^^^^^^^^^^^^^^^ + +The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube`. + + +Unified Post-Processor (UPP) +-------------------------------- + +The `Unified Post Processor `__ (:term:`UPP`) processes raw output from a variety of numerical weather prediction (:term:`NWP`) models. In the SRW, it converts data output formats from netCDF format on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from the UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). + + +Visualization Example +------------------------- + +This SRW Application release provides Python scripts to create basic visualizations of the model output. :numref:`Chapter %s ` contains usage information and instructions; instructions also appear at the top of the scripts. + +Build System and Workflow +---------------------------- + +The SRW Application has a portable CMake-based build system that packages together all the components required to build the SRW Application. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see `Rocoto documentation `__ for more on workflow management). Individual components can also be run in a stand-alone, command line fashion. + +The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. + +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application. Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW code ` without first installing prerequisites. On other platforms, the SRW can be :ref:`run within a container ` that includes the HPC-Stack, or the required libraries will need to be installed as part of the :ref:`SRW build ` process. Once these prerequisite libraries are installed, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. + .. _SRWStructure: @@ -127,7 +181,7 @@ The ``ufs-srweather-app`` :term:`umbrella repository` structure is determined by Regional Workflow Sub-Directories ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A number of sub-directories are created under the ``regional_workflow`` directory when the regional workflow is cloned (see directory diagram :ref:`above `). The contents of these sub-directories are described in :numref:`Table %s `. +A number of sub-directories are created under the ``regional_workflow`` directory when the regional workflow is cloned (see directory diagram :ref:`above `). :numref:`Table %s ` describes the contents of these sub-directories. .. _Subdirectories: @@ -154,7 +208,7 @@ A number of sub-directories are created under the ``regional_workflow`` director Experiment Directory Structure -------------------------------- -When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Step %s `), a user-defined experimental directory is created based on information specified in the ``config.sh`` file. :numref:`Table %s ` shows the contents of the experiment directory before the experiment workflow is run. +When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` script (:numref:`Step %s `), a user-defined experimental directory (``EXPTDIR``) is created based on information specified in the ``config.sh`` file. :numref:`Table %s ` shows the contents of the experiment directory before running the experiment workflow. .. _ExptDirStructure: @@ -201,9 +255,7 @@ When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` scr | YYYYMMDDHH | Cycle directory (empty) | +---------------------------+-------------------------------------------------------------------------------------------------------+ -In addition, the *community* mode creates the ``fix_am`` and ``fix_lam`` directories in ``EXPTDIR``. -The ``fix_lam`` directory is initially empty but will contain some *fix* (time-independent) files -after the grid, orography, and/or surface climatology generation tasks are run. +In addition, running the SRW in *community* mode creates the ``fix_am`` and ``fix_lam`` directories in ``EXPTDIR``. The ``fix_lam`` directory is initially empty but will contain some *fix* (time-independent) files after the grid, orography, and/or surface climatology generation tasks are run. .. _FixDirectories: @@ -212,7 +264,7 @@ after the grid, orography, and/or surface climatology generation tasks are run. +-------------------------+----------------------------------------------------------+ | **Directory Name** | **Description** | +=========================+==========================================================+ - | fix_am | Directory containing the global `fix` (time-independent) | + | fix_am | Directory containing the global fix (time-independent) | | | data files. The experiment generation script copies | | | these files from a machine-dependent system directory. | +-------------------------+----------------------------------------------------------+ @@ -223,33 +275,31 @@ after the grid, orography, and/or surface climatology generation tasks are run. +-------------------------+----------------------------------------------------------+ Once the workflow is launched with the ``launch_FV3LAM_wflow.sh`` script, a log file named -``log.launch_FV3LAM_wflow`` will be created (or appended to it if it already exists) in ``EXPTDIR``. -Once the ``make_grid``, ``make_orog``, and ``make_sfc_climo`` tasks and the ``get_extrn_ics`` -and ``get_extrn_lbc`` tasks for the YYYYMMDDHH cycle have completed successfully, new files and -sub-directories are created, as described in :numref:`Table %s `. +``log.launch_FV3LAM_wflow`` will be created (unless it already exists) in ``EXPTDIR``. The first several workflow tasks (i.e., ``make_grid``, ``make_orog``, ``make_sfc_climo``, ``get_extrn_ics``, and ``get_extrn_lbc``) are preprocessing tasks, which result in the creation of new files and +sub-directories, described in :numref:`Table %s `. .. _CreatedByWorkflow: -.. table:: New directories and files created when the workflow is launched. +.. table:: New directories and files created when the workflow is launched :widths: 30 70 +---------------------------+--------------------------------------------------------------------+ - | **Directory/file Name** | **Description** | + | **Directory/File Name** | **Description** | +===========================+====================================================================+ - | YYYYMMDDHH | This is updated when the first cycle-specific workflow tasks are | - | | run, which are ``get_extrn_ics`` and ``get_extrn_lbcs`` (they are | - | | launched simultaneously for each cycle in the experiment). We | - | | refer to this as a “cycle directory”. Cycle directories are | - | | created to contain cycle-specific files for each cycle that the | - | | experiment runs. If ``DATE_FIRST_CYCL`` and ``DATE_LAST_CYCL`` | - | | were different, and/or ``CYCL_HRS`` contained more than one | - | | element in the ``config.sh`` file, then more than one cycle | - | | directory would be created under the experiment directory. | + | YYYYMMDDHH | This is a “cycle directory” that is updated when the first | + | | cycle-specific workflow tasks (``get_extrn_ics`` and | + | | ``get_extrn_lbcs``) are run. These tasks are launched | + | | simultaneously for each cycle in the experiment. Cycle directories | + | | are created to contain cycle-specific files for each cycle that | + | | the experiment runs. If ``DATE_FIRST_CYCL`` and ``DATE_LAST_CYCL`` | + | | are different, and/or if ``CYCL_HRS`` contains more than one | + | | element in the ``config.sh`` file, more than one cycle directory | + | | will be created under the experiment directory. | +---------------------------+--------------------------------------------------------------------+ - | grid | Directory generated by the ``make_grid`` task containing grid | - | | files for the experiment | + | grid | Directory generated by the ``make_grid`` task to store grid files | + | | for the experiment | +---------------------------+--------------------------------------------------------------------+ - | log | Contains log files generated by the overall workflow and its | + | log | Contains log files generated by the overall workflow and by its | | | various tasks. Look in these files to trace why a task may have | | | failed. | +---------------------------+--------------------------------------------------------------------+ @@ -262,65 +312,15 @@ sub-directories are created, as described in :numref:`Table %s `. The workflow tasks are described in :numref:`Section %s `). -.. _Utilities: - -SRW Component Summary: Pre-processor Utilities and Initial Conditions -========================================================================= - -The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, this is used as input to the atmospheric model (FV3-LAM). Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. - - -Forecast Model ------------------ - -Atmospheric Model -^^^^^^^^^^^^^^^^^^^^^^ - -The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability (:cite:t:`BlackEtAl2020`). -The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. - -Common Community Physics Package -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and Noah Multi-parameterization (Noah MP) Land Surface Model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW release includes an experimental physics version and an updated operational version. - -Data Format -^^^^^^^^^^^^^^^^^^^^^^ - -The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube`. - - -Unified Post-Processor (UPP) --------------------------------- - -The `Unified Post Processor `__ (:term:`UPP`) is included in the SRW Application workflow. The UPP is designed to generate useful products from raw model output. In the SRW, it converts data output formats from netCDF format on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from the UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). - - -Visualization Example -------------------------- - -This SRW Application provides Python scripts to create basic visualizations of the model output. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. - -Build System and Workflow ----------------------------- - -The SRW Application has a portable CMake-based build system that packages together all the components required to build the SRW Application. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see `Rocoto documentation `__ for more on workflow management). Individual components can also be run in a stand-alone, command line fashion. - -The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. - -This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build-only platforms (Level 4). Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW code ` without first installing prerequisites. On other platforms, the SRW must be :ref:`run within a container ` that contains the HPC-Stack, or the required libraries (i.e., HPC-Stack) will need to be installed as part of the :ref:`non-container `) SRW installation process. Once these prerequisite libraries are built, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. - User Support, Documentation, and Contributions to Development =============================================================== @@ -330,7 +330,7 @@ A list of available documentation is shown in :numref:`Table %s ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW App. +This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via an :term:`EPIC`-provided container reduces this variability and allows for a smoother SRW build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW. -The "out-of-the-box" SRW case described in this guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. +The "out-of-the-box" SRW case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. + +.. attention:: + + The UFS defines `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. However, this guide can serve as a starting point for running the SRW App on other systems, too. .. _DownloadCodeC: Building the UFS SRW Application -=========================================== -The SRW Application source code is publicly available on GitHub and can be run in a container or locally, depending on user preference. The SRW Application relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. +=========================================== Prerequisites: Install Singularity ------------------------------------ @@ -26,7 +29,7 @@ To build and run the SRW App using a Singularity container, first install the Si Working in the Cloud ----------------------- -For those working on non-cloud-based systems, skip to :numref:`Step %s `. Users building the SRW using NOAA's Cloud resources must complete a few additional steps to ensure the SRW builds and runs correctly. +For those working on non-cloud-based systems, skip to :numref:`Step %s `. Users building the SRW using NOAA's Cloud resources must complete a few additional steps to ensure that the SRW builds and runs correctly. On NOAA Cloud systems, certain environment variables must be set *before* building the container: @@ -36,9 +39,10 @@ On NOAA Cloud systems, certain environment variables must be set *before* buildi export SINGULARITY_CACHEDIR=/lustre/cache export SINGULARITY_TEMPDIR=/lustre/tmp -* If the ``cache`` and ``tmp`` directories do not exist already, they must be created. +If the ``cache`` and ``tmp`` directories do not exist already, they must be created with a ``mkdir`` command. -* ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, `tar the files `__ and move it to the ``/contrib`` directory, which is much slower but persistent. +.. note:: + ``/lustre`` is a fast but non-persistent file system used on NOAA cloud systems. To retain work completed in this directory, `tar the files `__ and move them to the ``/contrib`` directory, which is much slower but persistent. .. _WorkOnHPC: @@ -46,7 +50,7 @@ Working on HPC Systems -------------------------- Those *not* working on HPC systems may skip to the :ref:`next step `. -On HPC systems (including NOAA's Cloud platforms), allocate a compute node on which to run the SRW. On NOAA's Cloud platforms, the following commands should work: +On HPC systems (including NOAA's Cloud platforms), allocate a compute node on which to run the SRW. On NOAA's Cloud platforms, the following commands will allocate a compute node: .. code-block:: console @@ -55,7 +59,7 @@ On HPC systems (including NOAA's Cloud platforms), allocate a compute node on wh mpirun -n 1 hostname ssh -The third command will output a hostname. This hostname should replace ```` in the last command. After "ssh-ing" to the compute node in the last command, build and run the SRW from that node. +The third command will output a hostname. Replace ```` in the last command with the output from the third command. After "ssh-ing" to the compute node in the last command, build and run the SRW from that node. The appropriate commands on other Level 1 platforms will vary, and users should consult the documentation for those platforms. @@ -79,7 +83,7 @@ Start the container and run an interactive shell within it: singularity shell -e --writable --bind /:/ ubuntu20.04-epic-srwapp-1.0 -The command above also binds the local directory to the container so that data can be shared between them. On NOAA systems, the local directory is usually the topmost directory (e.g., /lustre, /contrib, /work, or /home). Additional directories can be bound by adding another ``--bind /:/`` argument before the name of the container. +The command above also binds the local directory to the container so that data can be shared between them. On Level 1 systems, ```` is usually the topmost directory (e.g., /lustre, /contrib, /work, or /home). Additional directories can be bound by adding another ``--bind /:/`` argument before the name of the container. .. attention:: * When binding two directories, they must have the same name. It may be necessary to ``cd`` into the container and create an appropriately named directory in the container using the ``mkdir`` command if one is not already there. @@ -91,7 +95,7 @@ The command above also binds the local directory to the container so that data c Set up the Build Environment ============================ -If the SRW Application has been built in a container provided by the Earth Prediction Innovation Center (EPIC), set build environments and modules within the ``ufs-srweather-app`` directory as follows: +Set the build environments and modules within the ``ufs-srweather-app`` directory as follows: .. code-block:: console @@ -118,17 +122,17 @@ Download and Stage the Data ============================ The SRW requires input files to run. These include static datasets, initial and boundary condition -files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. +files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. .. _GenerateForecastC: Generate the Forecast Experiment ================================= -Generating the forecast experiment requires three steps: +To generate the forecast experiment, users must: -* :ref:`Set experiment parameters ` -* :ref:`Set Python and other environment parameters ` -* :ref:`Run a script to generate the experiment workflow ` +#. :ref:`Set experiment parameters ` +#. :ref:`Set Python and other environment parameters ` +#. :ref:`Run a script to generate the experiment workflow ` The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. @@ -138,7 +142,7 @@ Set the Experiment Parameters ------------------------------- Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in the ``config.sh`` file. Two example ``config.sh`` templates are provided: ``config.community.sh`` and ``config.nco.sh``. They can be found in the ``ufs-srweather-app/regional_workflow/ush`` directory. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. -Make a copy of ``config.community.sh`` to get started (under ``/regional_workflow/ush``). From the ``ufs-srweather-app`` directory, run: +Make a copy of ``config.community.sh`` to get started. From the ``ufs-srweather-app`` directory, run the following commands: .. code-block:: console @@ -157,7 +161,7 @@ Next, edit the new ``config.sh`` file to customize it for your experiment. At a EXPT_BASEDIR="/home/$USER/expt_dirs" COMPILER="gnu" -Additionally, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and add the correct paths to the data. The following is a sample for a 48-hour forecast: +Additionally, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and add the correct paths to the data. The following is a sample for a 24-hour forecast: .. code-block:: @@ -165,7 +169,7 @@ Additionally, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and add the correct pa EXTRN_MDL_SOURCE_BASEDIR_ICS="/path/to/model_data/FV3GFS" EXTRN_MDL_FILES_ICS=( "gfs.pgrb2.0p25.f000" ) EXTRN_MDL_SOURCE_BASEDIR_LBCS="/path/to/model_data/FV3GFS" - EXTRN_MDL_FILES_LBCS=( "gfs.pgrb2.0p25.f006" "gfs.pgrb2.0p25.f012" "gfs.pgrb2.0p25.f018" "gfs.pgrb2.0p25.f024" \ "gfs.pgrb2.0p25.f030" "gfs.pgrb2.0p25.f036" "gfs.pgrb2.0p25.f042" "gfs.pgrb2.0p25.f048" ) + EXTRN_MDL_FILES_LBCS=( "gfs.pgrb2.0p25.f006" "gfs.pgrb2.0p25.f012" "gfs.pgrb2.0p25.f018" "gfs.pgrb2.0p25.f024" ) On Level 1 systems, ``/path/to/model_data/FV3GFS`` should correspond to the location of the machine's global data. Alternatively, the user can add the path to their local data if they downloaded it as described in :numref:`Step %s `. @@ -185,7 +189,7 @@ On NOAA Cloud platforms, users may continue to the :ref:`next step ` on Level 1 systems. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. +On Level 1 systems, it should be possible to continue to the :ref:`next step ` after changing the settings above. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. For users interested in experimenting with a different grid, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. .. _SetUpPythonEnvC: Activate the Regional Workflow ---------------------------------------------- -Next, activate the regional workflow. +Next, activate the regional workflow: .. code-block:: console @@ -227,7 +231,7 @@ Run the following command to generate the workflow: This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The last line of output from this script should start with ``*/1 * * * *`` or ``*/3 * * * *``. -The generated workflow will be in the experiment directory specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in the experiment directory. +The generated workflow will be in the experiment directory specified in the ``config.sh`` file in :numref:`Step %s `. .. _RunUsingStandaloneScripts: @@ -237,7 +241,7 @@ Run the Workflow Using Stand-Alone Scripts .. note:: The Rocoto workflow manager cannot be used inside a container. -The regional workflow can be run using standalone shell scripts if the Rocoto software is not available on a given platform. If Rocoto *is* available, see `Section %s ` to run the workflow using Rocoto. +The regional workflow can be run using standalone shell scripts in cases where the Rocoto software is not available on a given platform. If Rocoto *is* available, see :numref:`Section %s ` to run the workflow using Rocoto. #. ``cd`` into the experiment directory @@ -248,13 +252,13 @@ The regional workflow can be run using standalone shell scripts if the Rocoto so export EXPTDIR=`pwd` setenv EXPTDIR `pwd` -#. Copy the wrapper scripts from the regional_workflow directory into your experiment directory. Each workflow task has a wrapper script that sets environment variables and run the job script. +#. Copy the wrapper scripts from the regional_workflow directory into the experiment directory. Each workflow task has a wrapper script that sets environment variables and runs the job script. .. code-block:: console cp ufs-srweather-app/regional_workflow/ush/wrappers/* . -#. Set the OMP_NUM_THREADS variable and fix dash/bash shell issue (this ensures the system does not use an alias of ``sh`` to dash). +#. Set the ``OMP_NUM_THREADS`` variable and fix dash/bash shell issue (this ensures the system does not use an alias of ``sh`` to dash). .. code-block:: console @@ -277,13 +281,6 @@ The regional workflow can be run using standalone shell scripts if the Rocoto so Check the batch script output file in your experiment directory for a “SUCCESS” message near the end of the file. -.. hint:: - If any of the scripts return an error that "Primary job terminated normally, but one process returned a non-zero exit code," there may not be enough space on one node to run the process. On an HPC system, the user will need to allocate a(nother) compute node. The process for doing so is system-dependent, and users should check the documentation available for their HPC system. Instructions for allocating a compute node on NOAA Cloud systems can be viewed in the :numref:`Step %s ` as an example. - -.. note:: - #. On most HPC systems, users will need to submit a batch job to run multi-processor jobs. On some HPC systems, users may be able to run the first two jobs (serial) on a login node/command-line. Example scripts for Slurm (Hera) and PBS (Cheyenne) resource managers are provided. These will need to be adapted to each user's system. This submit batch script is hard-coded per task, so it will need to be modified or copied to run each task. - - .. _RegionalWflowTasks: .. table:: List of tasks in the regional workflow in the order that they are executed. @@ -317,9 +314,12 @@ Check the batch script output file in your experiment directory for a “SUCCESS | | | | forecast hour) | +------------+------------------------+----------------+----------------------------+ -Example batch-submit scripts for Hera (Slurm) and Cheyenne (PBS) are included (``sq_job.sh`` -and ``qsub_job.sh``, respectively). These examples set the build and run environment for Hera or Cheyenne so that run-time libraries match the compiled libraries (i.e. netCDF, MPI). Users may either modify the submit batch script as each task is submitted, or duplicate this batch wrapper -for their system settings for each task. Alternatively, some batch systems allow users to specify most of the settings on the command line (with the ``sbatch`` or ``qsub`` command, for example). This piece will be unique to your platform. The tasks run by the regional workflow are shown in :numref:`Table %s `. Tasks with the same stage level may be run concurrently (no dependency). + +.. hint:: + If any of the scripts return an error that "Primary job terminated normally, but one process returned a non-zero exit code," there may not be enough space on one node to run the process. On an HPC system, the user will need to allocate a(nother) compute node. The process for doing so is system-dependent, and users should check the documentation available for their HPC system. Instructions for allocating a compute node on NOAA Cloud systems can be viewed in the :numref:`Step %s ` as an example. + +.. note:: + On most HPC systems, users will need to submit a batch job to run multi-processor jobs. On some HPC systems, users may be able to run the first two jobs (serial) on a login node/command-line. Example scripts for Slurm (Hera) and PBS (Cheyenne) resource managers are provided (``sq_job.sh`` and ``qsub_job.sh``, respectively). These examples will need to be adapted to each user's system. Alternatively, some batch systems allow users to specify most of the settings on the command line (with the ``sbatch`` or ``qsub`` command, for example). Plot the Output =============== From acb77c836ac88673c34695a3ecbfdd6274e84c64 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 17 Mar 2022 11:35:37 -0400 Subject: [PATCH 055/158] updates to BuildRun doc through 3.8.1 --- docs/UsersGuide/source/BuildRunSRW.rst | 54 +++++++++++++------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 1bfa8c1e2d..aaf59faca1 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -4,13 +4,13 @@ Building and Running the SRW ===================================== -The UFS Short-Range Weather Application (SRW App) is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. Once the SRW App is configured and built, users can generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. +The Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. Once the SRW App is configured and built, users can generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. -This chapter walks users through how to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application. However, the steps are relevant to any SRW experiment and can be modified to suit user goals. The "out-of-the-box" SRW case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. +This chapter walks users through how to build and run the "out-of-the-box" case for the SRW App. However, the steps are relevant to any SRW experiment and can be modified to suit user goals. The "out-of-the-box" SRW case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: - The UFS defines `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems, too, but the user need to perform additional troubleshooting. + The UFS defines `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems, too, but the user may need to perform additional troubleshooting. .. note:: The :ref:`container approach ` is recommended for a smoother build and run experience. Building without a container allows for the use of the Rocoto workflow manager and may allow for more cutomization. However, the non-container approach requires more in-depth troubleshooting skills, especially on Level 3 and 4 systems, and is less appropriate for beginners. @@ -27,14 +27,14 @@ The overall procedure for generating an experiment is shown in :numref:`Figure % * :ref:`Generate a regional workflow experiment ` * :ref:`Configure the experiment parameters ` * :ref:`Load the python environment for the regional workflow ` - * :ref:`Run the regional workflow ` + * :ref:`Run the regional workflow ` * :ref:`Optional: Plot the output ` .. _AppOverallProc: .. figure:: _static/FV3LAM_wflow_overall.png - *Overall layout of the SRW App* + *Overall layout of the SRW App Workflow* .. _HPCstackInfo: @@ -45,7 +45,7 @@ Install the HPC-Stack .. Attention:: Skip the HPC-Stack installation if working on a `Level 1 system `_ (e.g., Cheyenne, Hera, Orion, NOAA Cloud). -**Definition:** :term:`HPC-Stack` is a repository that provides a unified, shell script-based build system and builds the software stack required for the `Unified Forecast System (UFS) `_ and applications. +**Definition:** :term:`HPC-Stack` is a repository that provides a unified, shell script-based build system and builds the software stack required for `UFS `_ applications such as the SRW App. Background ---------------- @@ -54,7 +54,7 @@ The UFS Weather Model draws on over 50 code libraries to run its applications. T Instructions ------------------------- -Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to run applications (such as the SRW) or models that depend on it. Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. +Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to run applications (such as the SRW) or models that depend on it. Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. After completing installation, continue to the next section. @@ -62,9 +62,7 @@ After completing installation, continue to the next section. Download the UFS SRW Application Code ===================================== -The SRW Application source code is publicly available on GitHub. It relies on a variety of components detailed in the :ref:`Components Chapter ` of this User's Guide. Users must (1) clone the UFS SRW Application umbrella repository and then (2) run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App and will clone the correct version of the regional workflow, pre-processing utilities, UFS Weather Model, and UPP source code into the appropriate directories under the ``regional_workflow`` and ``src`` directories. - -Clone the release branch of the repository: +The SRW Application source code is publicly available on GitHub. To download the SRW App, clone the release branch of the repository: .. code-block:: console @@ -81,12 +79,12 @@ The cloned repository contains the configuration files and sub-directories shown .. table:: Files and sub-directories of the ufs-srweather-app repository +--------------------------------+--------------------------------------------------------+ - | **File/directory Name** | **Description** | + | **File/Directory Name** | **Description** | +================================+========================================================+ | CMakeLists.txt | Main cmake file for SRW App | +--------------------------------+--------------------------------------------------------+ - | Externals.cfg | Tags of the GitHub repositories/branches for the | - | | external repositories | + | Externals.cfg | Includes tags pointing to the correct version of the | + | | external GitHub repositories/branches used in the SRW. | +--------------------------------+--------------------------------------------------------+ | LICENSE.md | CC0 license information | +--------------------------------+--------------------------------------------------------+ @@ -113,14 +111,16 @@ The cloned repository contains the configuration files and sub-directories shown Check Out External Components ================================ -Next, run the executable that pulls in SRW components from external repositories, including the regional_workflow, ufs-weather-model, ufs_utils, and upp repositories: +The SRW App relies on a variety of components (e.g., regional_workflow, UFS_UTILS, ufs-weather-model, and UPP) detailed in :numref:`Chapter %s ` of this User's Guide. Users must run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App to clone the correct tags (code versions) of the external repositories listed in :numref:`Section %s ` into the appropriate directories under the ``regional_workflow`` and ``src`` directories. + +Run the executable that pulls in SRW components from external repositories: .. code-block:: console cd ufs-srweather-app ./manage_externals/checkout_externals -This step will use the configuration file ``Externals.cfg`` in the ``ufs-srweather-app`` directory to clone the correct tags (code versions) of the external repositories listed in :numref:`Section %s `. + .. _SetUpBuild: @@ -137,15 +137,15 @@ Before building the SRW App, the build environment must be set up for the user's -rw-rw-r-- 1 user ral 1228 Oct 9 10:09 build_jet_intel.env ... -On Level 1 systems, the commands in the ``build__.env`` files can be directly copy-pasted into the command line, or the file can be sourced from the ufs-srweather-app ``env`` directory. For example, on Hera, run: +On Level 1 systems, the commands in the ``build__.env`` files can be directly copy-pasted into the command line, or the file can be sourced from the ``ufs-srweather-app/env`` directory. For example, on Hera, run: .. code-block:: source env/build_hera_intel.env -from the main ufs-srweather-app directory to source the appropriate file. +from the main ``ufs-srweather-app`` directory to source the appropriate file. -On Level 2-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. To check if Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, this process will typically involve commands in the form ``export =``. You may need to use ``setenv`` rather than ``export`` depending on your shell environment. +On Level 2-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. To check if Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, users can modify or set the required environment variables using commands in the form ``export =``. Users may need to use ``setenv`` rather than ``export`` depending on their shell environment. .. _BuildExecutables: @@ -201,12 +201,12 @@ The build will take a few minutes to complete. When it starts, a random number i +------------------------+---------------------------------------------------------------------------------+ | sfc_climo_gen | Creates surface climatology fields from fixed files for use in ``chgres_cube`` | +------------------------+---------------------------------------------------------------------------------+ - | shave | Shaves the excess halo rows down to what is required for the LBCs in the | - | | orography and grid files | + | shave | Shaves the excess halo rows down to what is required for the lateral boundary | + | | conditions (LBC's) in the orography and grid files | +------------------------+---------------------------------------------------------------------------------+ | vcoord_gen | Generates hybrid coordinate interface profiles | +------------------------+---------------------------------------------------------------------------------+ - | fvcom_to_FV3 | Determine lake surface conditions for the Great Lakes | + | fvcom_to_FV3 | Determines lake surface conditions for the Great Lakes | +------------------------+---------------------------------------------------------------------------------+ | make_hgrid | Computes geo-referencing parameters (e.g., latitude, longitude, grid cell area) | | | for global uniform grids | @@ -237,14 +237,14 @@ Download and Stage the Data ============================ The SRW requires input files to run. These include static datasets, initial and boundary conditions -files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. +files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. .. _GridSpecificConfig: Grid Configuration ======================= -The SRW App officially supports three different predefined grids as shown in :numref:`Table %s `. The "out-of-the-box" SRW case uses the ``RRFS_CONUS_25km`` predefined grid option. More information on the predefined and user-generated grid options can be found in :numref:`Chapter %s ` for those who are curious. Users who plan to utilize one of the three pre-defined domain (grid) options may continue to :numref:`Step %s `. Users who plan to create a new domain should refer to :numref:`Chapter %s ` for details on how to do so. At a minimum, they will need to add the new grid name to the ``valid_param_vals`` script and add the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. +The SRW App officially supports three different predefined grids as shown in :numref:`Table %s `. The "out-of-the-box" SRW case uses the ``RRFS_CONUS_25km`` predefined grid option. More information on the predefined and user-generated grid options can be found in :numref:`Chapter %s ` for those who are curious. Users who plan to utilize one of the three pre-defined domain (grid) options may continue to :numref:`Step %s `. Users who plan to create a new domain should refer to :numref:`Chapter %s ` for details on how to do so. At a minimum, these users will need to add the new grid name to the ``valid_param_vals`` script and add the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. .. _PredefinedGrids: @@ -271,14 +271,14 @@ Generating the forecast experiment requires three steps: * :ref:`Set Python and other environment parameters ` * :ref:`Run a script to generate the experiment workflow ` -The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. +The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. Information in :numref:`Chapter %s: Configuring the Workflow ` can help with this. .. _ExptConfig: Set Experiment Parameters ---------------------------- -Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in ``config_defaults.sh`` and in the user-specific ``config.sh`` file. When generating a new experiment, the SRW App first reads and assigns default values from the ``config_defaults.sh`` file. Then, it reads and (re)assigns variables from the user's custom ``config.sh`` file. For background info on ``config_defaults.sh``, read :numref:`Section %s ` or jump to :numref:`Section %s ` to continue configuring the experiment. +Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in ``config_defaults.sh`` and in the user-specific ``config.sh`` file. When generating a new experiment, the SRW App first reads and assigns default values from the ``config_defaults.sh`` file. Then, it reads and (re)assigns variables from the user's custom ``config.sh`` file. For background info on ``config_defaults.sh``, read :numref:`Section %s `, or jump to :numref:`Section %s ` to continue configuring the experiment. .. _DefaultConfigSection: @@ -286,10 +286,10 @@ Default configuration: ``config_defaults.sh`` ------------------------------------------------ .. note:: - Users may skip to :numref:`Step %s `. This section provides background information on how the SRW App uses the ``config_defaults.sh`` file, but this information is not necessary for running the SRW. + This section provides background information on how the SRW App uses the ``config_defaults.sh`` file, but this information is not necessary for running the SRW. Users may skip to :numref:`Step %s ` to continue configuring their experiment. Important configuration variables in the ``config_defaults.sh`` file appear in -:numref:`Table %s `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified configuration ``config.sh`` file. Any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` +:numref:`Table %s `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified ``config.sh`` file. Any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` settings. There is usually no need for a user to modify the default configuration file. Additional information on the default settings can be found in the file itself and in :numref:`Chapter %s `. .. _ConfigVarsDefault: From 70a051b54aeda17039cec94dd850667223b0e1ed Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 17 Mar 2022 15:47:36 -0400 Subject: [PATCH 056/158] edits to Build/Run and Components --- docs/UsersGuide/source/BuildRunSRW.rst | 59 +++++++++++++++---------- docs/UsersGuide/source/Components.rst | 42 ++++++++---------- docs/UsersGuide/source/Glossary.rst | 17 ++++--- docs/UsersGuide/source/Introduction.rst | 2 +- 4 files changed, 64 insertions(+), 56 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index aaf59faca1..332592e907 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -286,7 +286,7 @@ Default configuration: ``config_defaults.sh`` ------------------------------------------------ .. note:: - This section provides background information on how the SRW App uses the ``config_defaults.sh`` file, but this information is not necessary for running the SRW. Users may skip to :numref:`Step %s ` to continue configuring their experiment. + This section provides background information on how the SRW App uses the ``config_defaults.sh`` file. This information is not helpful but not essential to running the SRW App. Users may skip to :numref:`Step %s ` to continue configuring their experiment. Important configuration variables in the ``config_defaults.sh`` file appear in :numref:`Table %s `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified ``config.sh`` file. Any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` @@ -405,7 +405,7 @@ settings. There is usually no need for a user to modify the default configuratio User-specific configuration: ``config.sh`` -------------------------------------------- -The user must specify certain basic information about the experiment in a ``config.sh`` file located in the ``ufs-srweather-app/regional_workflow/ush`` directory. Two example templates are provided in the ``ufs-srweather-app/regional_workflow/ush`` directory: ``config.community.sh`` and ``config.nco.sh``. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. The operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing. :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. +The user must specify certain basic information about the experiment in a ``config.sh`` file located in the ``ufs-srweather-app/regional_workflow/ush`` directory. Two example templates are provided in that directory: ``config.community.sh`` and ``config.nco.sh``. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. The operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing. :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. .. _ConfigCommunity: @@ -466,7 +466,7 @@ The user must specify certain basic information about the experiment in a ``conf +--------------------------------+-------------------+--------------------------------------------------------+ -To get started, make a copy of ``config.community.sh`` (under ``/regional_workflow/ush``). From the ``ufs-srweather-app`` directory, run: +To get started, make a copy of ``config.community.sh``. From the ``ufs-srweather-app`` directory, run: .. code-block:: console @@ -481,7 +481,7 @@ Sample settings are indicated below for Level 1 platforms. Detailed guidance app .. important:: - If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to add the line ``COMPILER="gnu"`` to the ``config.sh`` file. + If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to check that the line ``COMPILER="gnu"`` appears in the ``config.sh`` file. .. hint:: @@ -548,7 +548,7 @@ For **WCOSS**, edit ``config.sh`` with these WCOSS-specific parameters, and use Set up the Python and other Environment Parameters -------------------------------------------------- -Next, load the appropriate Python environment for the workflow. The workflow requires Python 3, with the packages 'PyYAML', 'Jinja2', and 'f90nml' available. This Python environment has already been set up on Level 1 platforms, and it can be activated in the following way (from ``/ufs-srweather-app/regional_workflow/ush``): +The workflow requires Python 3 with the packages 'PyYAML', 'Jinja2', and 'f90nml' available. This Python environment has already been set up on Level 1 platforms, and it can be activated in the following way (from ``/ufs-srweather-app/regional_workflow/ush``): .. code-block:: console @@ -576,11 +576,11 @@ Run the following command from the ``ufs-srweather-app/regional_workflow/ush`` d The last line of output from this script, starting with ``*/1 * * * *`` or ``*/3 * * * *``, can be saved and :ref:`used later ` to automatically run portions of the workflow. -This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The flowchart in :numref:`Figure %s ` describes the experiment generation process. First, ``generate_FV3LAM_wflow.sh`` runs the ``setup.sh`` script to set the configuration parameters. Second, it copies the time-independent (fix) files and other necessary data input files from their location in the ufs-weather-model directory to the experiment directory (``$EXPTDIR``). Third, it copies the weather model executable (``ufs_model``) from the ``bin`` directory to ``$EXPTDIR`` and creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` file in the regional_workflow/ush/templates directory. Lastly, it creates the workflow XML file ``FV3LAM_wflow.xml`` that is executed when running the experiment with the Rocoto workflow manager. +This workflow generation script creates an experiment directory and populates it with all the data needed to run through the workflow. The flowchart in :numref:`Figure %s ` describes the experiment generation process. First, ``generate_FV3LAM_wflow.sh`` runs the ``setup.sh`` script to set the configuration parameters. Second, it copies the time-independent (fix) files and other necessary data input files from their location in the ufs-weather-model directory to the experiment directory (``EXPTDIR``). Third, it copies the weather model executable (``ufs_model``) from the ``bin`` directory to ``EXPTDIR`` and creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` file in the regional_workflow/ush/templates directory. Lastly, it creates the workflow XML file ``FV3LAM_wflow.xml`` that is executed when running the experiment with the Rocoto workflow manager. The ``setup.sh`` script reads three other configuration scripts in order: (1) ``config_default.sh`` (:numref:`Section %s `), (2) ``config.sh`` (:numref:`Section %s `), and (3) ``set_predef_grid_params.sh`` (:numref:`Section %s `). If a parameter is specified differently in these scripts, the file containing the last defined value will be used. -The generated workflow will appear in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in ``$EXPTDIR``. +The generated workflow will appear in ``EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in the ``config.sh`` file in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.sh`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in ``$EXPTDIR``. .. _WorkflowGeneration: @@ -594,9 +594,16 @@ Description of Workflow Tasks -------------------------------- .. note:: - This section gives an overview of workflow tasks. To begin running the workflow, skip to :numref:`Step %s ` + This section gives a general overview of workflow tasks. To begin running the workflow, skip to :numref:`Step %s ` + +:numref:`Figure %s ` illustrates the overall workflow. Individual tasks that make up the workflow are specified in the ``FV3LAM_wflow.xml`` file. :numref:`Table %s ` describes the function of each task. The first three pre-processing tasks; ``MAKE_GRID``, ``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by adding the following lines to the ``config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script: + +.. code-block:: console + + RUN_TASK_MAKE_GRID=”FALSE” + RUN_TASK_MAKE_OROG=”FALSE” + RUN_TASK_MAKE_SFC_CLIMO=”FALSE” -Workflow tasks are specified in the ``FV3LAM_wflow.xml`` file and illustrated in :numref:`Figure %s `. Each task is described in :numref:`Table %s `. The first three pre-processing tasks; ``MAKE_GRID``, ``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by setting ``RUN_TASK_MAKE_GRID=”FALSE”``, ``RUN_TASK_MAKE_OROG=”FALSE”``, and ``RUN_TASK_MAKE_SFC_CLIMO=”FALSE”`` in the ``regional_workflow/ush/config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script. As shown in the figure, the ``FV3LAM_wflow.xml`` file runs the specific j-job scripts in the prescribed order (``regional_workflow/jobs/JREGIONAL_[task name]``) when the ``launch_FV3LAM_wflow.sh`` is submitted. Each j-job task has its own source script named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. .. _WorkflowTasksFig: @@ -604,6 +611,10 @@ Workflow tasks are specified in the ``FV3LAM_wflow.xml`` file and illustrated in *Flowchart of the workflow tasks* + +The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``regional_workflow/jobs/JREGIONAL_[task name]``) in the prescribed order when the experiment is launched via the ``launch_FV3LAM_wflow.sh`` script or the ``rocotorun`` command. Each j-job task has its own source script named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files named ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. + + .. _WorkflowTasksTable: .. table:: Workflow tasks in SRW App @@ -624,11 +635,11 @@ Workflow tasks are specified in the ``FV3LAM_wflow.xml`` file and illustrated in | | initial conditions | +----------------------+------------------------------------------------------------+ | get_extrn_lbcs | Cycle-specific task to obtain external data for the | - | | lateral boundary (LB) conditions | + | | lateral boundary conditions (LBC's) | +----------------------+------------------------------------------------------------+ | make_ics | Generate initial conditions from the external data | +----------------------+------------------------------------------------------------+ - | make_lbcs | Generate lateral boundary conditions from the external data| + | make_lbcs | Generate LBC's from the external data | +----------------------+------------------------------------------------------------+ | run_fcst | Run the forecast model (UFS weather model) | +----------------------+------------------------------------------------------------+ @@ -641,7 +652,7 @@ Workflow tasks are specified in the ``FV3LAM_wflow.xml`` file and illustrated in Run the Workflow Using Rocoto ============================= -The information in this section assumes that Rocoto is available on the desired platform. (Note that Rocoto cannot be used when running the workflow within a container.) If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts described in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: (1) with the ``launch_FV3LAM_wflow.sh`` script, and (2) by manually calling the ``rocotorun`` command. Users can also automate the workflow using a crontab. +The information in this section assumes that Rocoto is available on the desired platform. (Note that Rocoto cannot be used when running the workflow within a container.) If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts according to the process outlined in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: (1) with the ``launch_FV3LAM_wflow.sh`` script, and (2) by manually calling the ``rocotorun`` command. Users can also automate the workflow using a crontab. Optionally, an environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: @@ -666,19 +677,19 @@ To run Rocoto using the ``launch_FV3LAM_wflow.sh`` script provided, simply call cd $EXPTDIR ./launch_FV3LAM_wflow.sh -This script creates a log file named ``log.launch_FV3LAM_wflow`` in the EXPTDIR directory or appends information to it if the file already exists. Check the end of the log file periodically to see how the experiment is progressing: +This script creates a log file named ``log.launch_FV3LAM_wflow`` in ``$EXPTDIR`` or appends information to it if the file already exists. Check the end of the log file periodically to see how the experiment is progressing: .. code-block:: console - tail -n 30 log.launch_FV3LAM_wflow + tail -n 40 log.launch_FV3LAM_wflow In order to launch additional tasks in the workflow, call the launch script again; this action will need to be repeated until all tasks in the workflow have been launched. To (re)launch the workflow and check its progress on a single line, run: .. code-block:: console - ./launch_FV3LAM_wflow.sh; tail -n 80 log.launch_FV3LAM_wflow + ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow -This will output the last 80 lines of the log file, which includes the status of the workflow tasks (e.g., SUCCEEDED, DEAD, RUNNING, SUBMITTING, QUEUED). The number 80 can be changed according to the user's preferences. The output will look like this: +This will output the last 40 lines of the log file, which list the status of the workflow tasks (e.g., SUCCEEDED, DEAD, RUNNING, SUBMITTING, QUEUED). The number 40 can be changed according to the user's preferences. The output will look like this: .. code-block:: console @@ -706,7 +717,7 @@ This will output the last 80 lines of the log file, which includes the status of 0 out of 1 cycles completed. Workflow status: IN PROGRESS -Error messages for each specific task can be found in the task log files located in the ``$EXPTDIR/log`` directory. +Error messages for each specific task can be found in the task log files located in ``$EXPTDIR/log``. If everything goes smoothly, you will eventually get the following workflow status table as follows: @@ -730,7 +741,7 @@ If everything goes smoothly, you will eventually get the following workflow stat 202006170000 run_post_05 8855464 SUCCEEDED 0 1 6.0 202006170000 run_post_06 8855465 SUCCEEDED 0 1 6.0 -If all the tasks complete successfully, the workflow status in the log file will include the word “SUCCESS." Otherwise, the workflow status will include the word “FAILURE." +If all the tasks complete successfully, the workflow status in the log file will indicate “SUCCESS." Otherwise, the workflow status will indicate “FAILURE." Launch the Rocoto Workflow Manually @@ -808,7 +819,7 @@ After loading Rocoto, call ``rocotorun`` from the experiment directory to launch rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -The ``rocotorun`` and ``rocotostat`` commands will need to be resubmitted regularly and repeatedly until the experiment is finished. In part, this is to avoid having the system time out. This also ensures that when one task ends, tasks dependent on it will run as soon as possible, and ``rocotostat`` will capture the new progress. +The ``rocotorun`` and ``rocotostat`` commands above will need to be resubmitted regularly and repeatedly until the experiment is finished. In part, this is to avoid having the system time out. This also ensures that when one task ends, tasks dependent on it will run as soon as possible, and ``rocotostat`` will capture the new progress. If the experiment fails, the ``rocotostat`` command will indicate which task failed. Users can look at the log file in the ``log`` subdirectory for the failed task to determine what caused the failure. For example, if the ``make_grid`` task failed, users can open the ``make_grid.log`` file to see what caused the problem: @@ -825,13 +836,13 @@ If the experiment fails, the ``rocotostat`` command will indicate which task fai Automated Option ---------------------- -For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry by entering the ``crontab -e`` command, which opens a crontab file. As mentioned in :ref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *``), can be pasted into the crontab file. It can also be found in the``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: +For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry using the ``crontab -e`` command. As mentioned in :numref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *``), can be pasted into the crontab file. It can also be found in the ``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: .. code-block:: console */1 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -where ```` is changed to correspond to the user's machine, and ``/apps/rocoto/1.3.3/bin/rocotorun`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can also be changed and simply means that the workflow will be resubmitted every minute. +where ```` is changed to correspond to the user's ``$EXPTDIR``, and ``/apps/rocoto/1.3.3/bin/rocotorun`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can be changed to a different positive integer and simply means that the workflow will be resubmitted every minute. To check the experiment progress: @@ -844,9 +855,9 @@ After finishing the experiment, open the crontab using `` crontab -e`` and delet .. note:: - On Orion, *cron* is only available on the orion-login-1 node, so please use that node when running cron jobs on Orion. + On Orion, *cron* is only available on the orion-login-1 node, so users will need to work on that node when running *cron* jobs on Orion. -The workflow run is completed when all tasks have “SUCCEEDED”, and the rocotostat command will output the following: +The workflow run is complete when all tasks have “SUCCEEDED”, and the rocotostat command outputs the following: .. code-block:: console @@ -869,4 +880,4 @@ The workflow run is completed when all tasks have “SUCCEEDED”, and the rocot Plot the Output =============== -Two python scripts are provided to generate plots from the FV3-LAM post-processed GRIB2 output. Information on how to generate the graphics can be found in :numref:`Chapter %s `. +Two python scripts are provided to generate plots from the :term:`FV3`-LAM post-processed :term:`GRIB2` output. Information on how to generate the graphics can be found in :numref:`Chapter %s `. diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index ed3eff1f2a..cf3728fbeb 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -4,11 +4,12 @@ SRW Components =============== -The SRW Application v2.0 release assembles a variety of components, including: +The SRW Application assembles a variety of components, including: + * Pre-processor Utilities & Initial Conditions -* Forecast Model -* Post-Processor -* Visualization Example +* UFS Weather Forecast Model +* Unified Post-Processor +* Visualization Examples * Build System and Workflow These components are documented within this User's Guide and supported through a `community forum `_. @@ -19,7 +20,7 @@ Pre-processor Utilities and Initial Conditions ============================================== The SRW Application includes a number of pre-processing utilities that initialize and prepare the -model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid ``regional_esg_grid/make_hgrid`` along with orography ``orog`` and surface climatology ``sfc_climo_gen`` files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of halo cells, additional utilities handle the correct number of halo shave points and topography filtering. The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format, needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. +model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid (``regional_esg_grid/make_hgrid``) along with :term:`orography` (``orog``) and surface climatology (``sfc_climo_gen``) files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of halo cells, additional utilities handle the correct number of halo shave points and topography filtering. The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format. These are needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. The SRW Application can be initialized from a range of operational initial condition files. It is possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (:term:`GRIB2`) format. GFS files also come in :term:`NEMSIO` format for past dates. @@ -36,34 +37,32 @@ 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 64 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 `here `__ and on the `NOAA Geophysical Fluid Dynamics Laboratory website `_. -Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) Land Surface Model options, are supported through the Common Community Physics Package (:term:`CCPP`; described `here `__).Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are two physics options supported for the release. The first is an experimental physics suite 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) v15. 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 +Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) Land Surface Model options, are supported through the Common Community Physics Package (:term:`CCPP`), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are two physics options supported for the release. The first is an experimental physics suite 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) v15. 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. -The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model -ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in -netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal direction and model levels in the vertical direction. +The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal direction and model levels in the vertical direction. Post-processor ============== The SRW Application is distributed with the Unified Post Processor (:term:`UPP`) included in the workflow as a way to convert the netCDF output on the native model grid to :term:`GRIB2` format on -standard isobaric vertical coordinates. UPP can also be used to compute a variety of useful -diagnostic fields, as described in the `UPP User’s Guide `_. +standard isobaric vertical coordinates. The UPP can also be used to compute a variety of useful +diagnostic fields, as described in the `UPP User’s Guide `__. -Output from UPP can be used with visualization, plotting, and verification packages, or for -further downstream post-processing, e.g. statistical post-processing techniques. +Output from UPP can be used with visualization, plotting, and verification packages or in +further downstream post-processing (e.g., statistical post-processing techniques). Visualization Example ===================== A Python script is provided to create basic visualization of the model output. The script is designed to output graphics in PNG format for 14 standard meteorological variables -when using the pre-defined :term:`CONUS` domain. In addition, a difference plotting script is included +when using the pre-defined :term:`CONUS` domain. A difference plotting script is also included to visually compare two runs for the same domain and resolution. These scripts are provided only -as an example for users familiar with Python and may be used to do a visual check to verify +as an example for users familiar with Python. They may be used to perform a visual check to verify that the application is producing reasonable results. -After running ``manage_externals/checkout_externals``, the visualization scripts will be available in the `regional_workflow repository `_ under ush/Python. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. +After running ``manage_externals/checkout_externals``, the visualization scripts will be available in the ``ufs-srweather-app/regional_workflow/ush/Python`` directory. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. Build System and Workflow ========================= @@ -71,8 +70,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: 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. 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 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 :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. 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 `Rocoto documentation @@ -82,13 +80,9 @@ This SRW Application release has been tested on a variety of platforms widely us researchers, such as the NOAA Research and Development High-Performance Computing Systems (RDHPCS), including Hera, Orion, and Jet; NOAA’s Weather and Climate Operational Supercomputing System (WCOSS); the National Center for Atmospheric Research (NCAR) Cheyenne -system; the National Severe Storms Laboratory (NSSL) HPC machine called Odin; the National Science Foundation Stampede2 system; and generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build only platforms (Level 4). Each level is further described below. +system; the National Severe Storms Laboratory (NSSL) HPC machine, Odin; the National Science Foundation Stampede2 system; and generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build only platforms (Level 4). Each level is further described below. -For the selected computational platforms that have been pre-configured (Level 1), all the -required libraries for building the SRW Application are available in a central place. That -means bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) have both -been built. The SRW Application is expected to build and run out-of-the-box on these -pre-configured platforms. Users can download the SRW code and choose whether to run it :ref:`in a container ` or :ref:`locally `. +On pre-configured (Level 1) computational platforms, all the required libraries for building the SRW Application are available in a central place. That means bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) have both been built. The SRW Application is expected to build and run out-of-the-box on these pre-configured platforms. A few additional computational platforms are considered configurable for the SRW Application release. Configurable platforms (Level 2) are platforms where all of the required libraries for building the SRW Application are expected to install successfully but are not available in a central location. Applications and models are expected to build and run once the required bundled libraries (e.g., NCEPLIBS) and third-party libraries (e.g., NCEPLIBS-external) are built. diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index ebded5df4a..3873298cfe 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -44,16 +44,19 @@ Glossary The second version of the World Meterological Organization's (WMO) standard for distributing gridded data. 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. + 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. 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. + `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 Initial conditions/lateral boundary conditions LAM - Limited Area Model. LAM grids use a regional (rather than global) configuration of the FV3 dynamical core. + Limited Area Model, formerly known as the "Stand-Alone Regional Model," or SAR. LAM grids use a regional (rather than global) configuration of the FV3 dynamical core. + + LBC + Lateral boundary conditions. MPI MPI stands for Message Passing Interface. An MPI is a standardized communication system used in parallel programming. It establishes portable and efficient syntax for the exchange of messages and data between multiple processors that are used by a single computer program. An MPI is required for high-performance computing (HPC). @@ -67,11 +70,11 @@ Glossary NCEPLIBS The software libraries created and maintained by :term:`NCEP` that are required for running - :term:`chgres_cube`, the UFS Weather Model, and :term:`UPP`. They are part of the HPC-Stack. + :term:`chgres_cube`, the UFS Weather Model, and :term:`UPP`. They are included in the `HPC-Stack `__. NCEPLIBS-external A collection of third-party libraries required to build :term:`NCEPLIBS`, :term:`chgres_cube`, - the UFS Weather Model, and :term:`UPP`. They are part of the HPC-Stack. + the UFS Weather Model, and :term:`UPP`. They are included in the `HPC-Stack `__. NCL An interpreted programming language designed specifically for scientific data analysis and @@ -88,10 +91,10 @@ Glossary Numerical Weather Prediction (NWP) takes current observations of weather and processes them with computer models to forecast the future state of the weather. Orography - The branch of physical geography dealing with mountains + The branch of physical geography dealing with mountains. RAP - `Rapid Refresh `. The continental-scale NOAA hourly-updated assimilation/modeling system operational at NCEP. RAP covers North America and is comprised primarily of a numerical forecast model and an analysis/assimilation system to initialize that model. RAP is complemented by the higher-resolution 3km High-Resolution Rapid Refresh (HRRR) model. + `Rapid Refresh `__. The continental-scale NOAA hourly-updated assimilation/modeling system operational at NCEP. RAP covers North America and is comprised primarily of a numerical forecast model and an analysis/assimilation system to initialize that model. RAP is complemented by the higher-resolution 3km High-Resolution Rapid Refresh (HRRR) model. Repository A central location in which files (e.g., data, code, documentation) are stored and managed. diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 0cd418f402..6f8f0b6ac8 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -6,7 +6,7 @@ Introduction The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. -The UFS can be configured for `multiple applications `__. The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a :ref:`Quick Start Guide ` for running the application in a container and a :ref:`detailed guide ` for running the SRW on supported platforms. It also provides an overview of the :ref:`release components ` and details on how to customize or modify different portions of the workflow. +The UFS can be configured for `multiple applications `__. The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v1.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a :ref:`Quick Start Guide ` for running the application in a container and a :ref:`detailed guide ` for running the SRW on supported platforms. It also provides an overview of the :ref:`release components ` and details on how to customize or modify different portions of the workflow. The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research conducted with the App: From 99127e7484eea9b177041dc39fa0b3bf1de50f7d Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 18 Mar 2022 11:06:32 -0400 Subject: [PATCH 057/158] remove .gitignore --- .gitignore | 1 - 1 file changed, 1 deletion(-) delete mode 100644 .gitignore diff --git a/.gitignore b/.gitignore deleted file mode 100644 index e43b0f9889..0000000000 --- a/.gitignore +++ /dev/null @@ -1 +0,0 @@ -.DS_Store From b01268d5433f0db0119d9655d2cb086f3404da74 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 18 Mar 2022 11:14:26 -0400 Subject: [PATCH 058/158] fix Ch 3 title, 4 supported platform levels note --- docs/UsersGuide/source/BuildRunSRW.rst | 4 ++-- docs/UsersGuide/source/Quickstart.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 332592e907..015401ac4d 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -1,7 +1,7 @@ .. _BuildRunSRW: ===================================== -Building and Running the SRW +Building and Running the SRW App ===================================== The Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. Once the SRW App is configured and built, users can generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. @@ -10,7 +10,7 @@ This chapter walks users through how to build and run the "out-of-the-box" case .. attention:: - The UFS defines `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems, too, but the user may need to perform additional troubleshooting. + All UFS applications support `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems, too, but the user may need to perform additional troubleshooting. .. note:: The :ref:`container approach ` is recommended for a smoother build and run experience. Building without a container allows for the use of the Rocoto workflow manager and may allow for more cutomization. However, the non-container approach requires more in-depth troubleshooting skills, especially on Level 3 and 4 systems, and is less appropriate for beginners. diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 88c9295de6..e963c528df 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -10,7 +10,7 @@ The "out-of-the-box" SRW case described in this User's Guide builds a weather fo .. attention:: - The UFS defines `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. However, this guide can serve as a starting point for running the SRW App on other systems, too. + All UFS applications support `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. However, this guide can serve as a starting point for running the SRW App on other systems, too. .. _DownloadCodeC: From da35184e6b5c4a1b2cc952d27d687ed34eb41981 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 18 Mar 2022 11:39:54 -0400 Subject: [PATCH 059/158] fix typos, add term links --- docs/UsersGuide/source/BuildRunSRW.rst | 10 +++++----- docs/UsersGuide/source/Quickstart.rst | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 015401ac4d..d634d0bdf0 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -6,14 +6,14 @@ Building and Running the SRW App The Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. Once the SRW App is configured and built, users can generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. -This chapter walks users through how to build and run the "out-of-the-box" case for the SRW App. However, the steps are relevant to any SRW experiment and can be modified to suit user goals. The "out-of-the-box" SRW case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. +This chapter walks users through how to build and run the "out-of-the-box" case for the SRW App. However, the steps are relevant to any SRW experiment and can be modified to suit user goals. The "out-of-the-box" SRW case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: All UFS applications support `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems, too, but the user may need to perform additional troubleshooting. .. note:: - The :ref:`container approach ` is recommended for a smoother build and run experience. Building without a container allows for the use of the Rocoto workflow manager and may allow for more cutomization. However, the non-container approach requires more in-depth troubleshooting skills, especially on Level 3 and 4 systems, and is less appropriate for beginners. + The :ref:`container approach ` is recommended for a smoother build and run experience. Building without a container allows for the use of the Rocoto workflow manager and may allow for more customization. However, the non-container approach requires more in-depth troubleshooting skills, especially on Level 3 and 4 systems, and is less appropriate for beginners. The overall procedure for generating an experiment is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. The steps are as follows: @@ -286,7 +286,7 @@ Default configuration: ``config_defaults.sh`` ------------------------------------------------ .. note:: - This section provides background information on how the SRW App uses the ``config_defaults.sh`` file. This information is not helpful but not essential to running the SRW App. Users may skip to :numref:`Step %s ` to continue configuring their experiment. + This section provides background information on how the SRW App uses the ``config_defaults.sh`` file. This information is helpful but not essential to running the SRW App. Users may skip to :numref:`Step %s ` to continue configuring their experiment. Important configuration variables in the ``config_defaults.sh`` file appear in :numref:`Table %s `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified ``config.sh`` file. Any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` @@ -405,7 +405,7 @@ settings. There is usually no need for a user to modify the default configuratio User-specific configuration: ``config.sh`` -------------------------------------------- -The user must specify certain basic information about the experiment in a ``config.sh`` file located in the ``ufs-srweather-app/regional_workflow/ush`` directory. Two example templates are provided in that directory: ``config.community.sh`` and ``config.nco.sh``. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. The operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing. :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. +The user must specify certain basic information about the experiment in a ``config.sh`` file located in the ``ufs-srweather-app/regional_workflow/ush`` directory. Two example templates are provided in that directory: ``config.community.sh`` and ``config.nco.sh``. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. The operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing for the Rapid-Refresh Forecast System (RRFS). :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. .. _ConfigCommunity: @@ -473,7 +473,7 @@ To get started, make a copy of ``config.community.sh``. From the ``ufs-srweather cd regional_workflow/ush cp config.community.sh config.sh -The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. +The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. Next, edit the new ``config.sh`` file to customize it for your machine. At a minimum, change the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If you have pre-staged the initialization data for the experiment, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and set the paths to the data for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index e963c528df..50436af86a 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -6,7 +6,7 @@ Quick Start Guide This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via an :term:`EPIC`-provided container reduces this variability and allows for a smoother SRW build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW. -The "out-of-the-box" SRW case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. +The "out-of-the-box" SRW case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: @@ -149,7 +149,7 @@ Make a copy of ``config.community.sh`` to get started. From the ``ufs-srweather- cd regional_workflow/ush cp config.community.sh config.sh -The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 CCPP), and :term:`FV3`-based GFS raw external model data for initialization. +The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. Next, edit the new ``config.sh`` file to customize it for your experiment. At a minimum, update the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``: From 1302868646eb26d61916ae953c7798ea242abe03 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 18 Mar 2022 13:11:22 -0400 Subject: [PATCH 060/158] other minor fixes/suggestions implemented --- docs/UsersGuide/source/BuildRunSRW.rst | 74 +++++--------------------- docs/UsersGuide/source/Quickstart.rst | 9 ++-- 2 files changed, 16 insertions(+), 67 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index d634d0bdf0..e7baac2ebc 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -113,7 +113,7 @@ Check Out External Components The SRW App relies on a variety of components (e.g., regional_workflow, UFS_UTILS, ufs-weather-model, and UPP) detailed in :numref:`Chapter %s ` of this User's Guide. Users must run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App to clone the correct tags (code versions) of the external repositories listed in :numref:`Section %s ` into the appropriate directories under the ``regional_workflow`` and ``src`` directories. -Run the executable that pulls in SRW components from external repositories: +Run the executable that pulls in SRW App components from external repositories: .. code-block:: console @@ -236,8 +236,7 @@ The build will take a few minutes to complete. When it starts, a random number i Download and Stage the Data ============================ -The SRW requires input files to run. These include static datasets, initial and boundary conditions -files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. +The SRW App requires input files to run. These include static datasets, initial and boundary conditions files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. .. _GridSpecificConfig: @@ -554,7 +553,7 @@ The workflow requires Python 3 with the packages 'PyYAML', 'Jinja2', and 'f90nml source ../../env/wflow_.env -This command will activate the ``regional_workflow``. The user should see ``(regional_workflow)`` in front of the Terminal prompt at this point. If this is not the case, activate the regional workflow from the ``ush`` directory by running: +This command will activate the ``regional_workflow`` conda environment. The user should see ``(regional_workflow)`` in front of the Terminal prompt at this point. If this is not the case, activate the regional workflow from the ``ush`` directory by running: .. code-block:: console @@ -612,12 +611,12 @@ Description of Workflow Tasks *Flowchart of the workflow tasks* -The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``regional_workflow/jobs/JREGIONAL_[task name]``) in the prescribed order when the experiment is launched via the ``launch_FV3LAM_wflow.sh`` script or the ``rocotorun`` command. Each j-job task has its own source script named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files named ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. +The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``regional_workflow/jobs/JREGIONAL_[task name]``) in the prescribed order when the experiment is launched via the ``launch_FV3LAM_wflow.sh`` script or the ``rocotorun`` command. Each j-job task has its own source script (or "ex-script") named ``exregional_[task name].sh`` in the ``regional_workflow/scripts`` directory. Two database files named ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are generated and updated by the Rocoto calls. There is usually no need for users to modify these files. To relaunch the workflow from scratch, delete these two ``*.db`` files and then call the launch script repeatedly for each task. .. _WorkflowTasksTable: -.. table:: Workflow tasks in SRW App +.. table:: Workflow tasks in the SRW App +----------------------+------------------------------------------------------------+ | **Workflow Task** | **Task Description** | @@ -677,7 +676,7 @@ To run Rocoto using the ``launch_FV3LAM_wflow.sh`` script provided, simply call cd $EXPTDIR ./launch_FV3LAM_wflow.sh -This script creates a log file named ``log.launch_FV3LAM_wflow`` in ``$EXPTDIR`` or appends information to it if the file already exists. Check the end of the log file periodically to see how the experiment is progressing: +This script creates a log file named ``log.launch_FV3LAM_wflow`` in ``$EXPTDIR`` or appends information to it if the file already exists. The launch script also creates the ``log/FV3LAM_wflow.log`` file, which shows Rocoto task information. Check the end of the log files periodically to see how the experiment is progressing: .. code-block:: console @@ -750,63 +749,14 @@ Launch the Rocoto Workflow Manually Load Rocoto ^^^^^^^^^^^^^^^^ -Instead of running the ``./launch_FV3LAM_wflow.sh`` script, users can load Rocoto and any other required modules. This gives the user more control over the process and allows them to view experiment progress more easily. - -For most systems, a variant on the following commands will be necessary to load the Rocoto module: +Instead of running the ``./launch_FV3LAM_wflow.sh`` script, users can load Rocoto and any other required modules. This gives the user more control over the process and allows them to view experiment progress more easily. On Level 1 systems, the Rocoto modules are loaded automatically in :numref:`Step %s `. For most other systems, a variant on the following commands will be necessary to load the Rocoto module: .. code-block:: console module use module load rocoto -The commands for specific Level 1 platforms are described here: - -Cheyenne: - -.. code-block:: console - - module use -a /glade/p/ral/jntp/UFS_SRW_app/modules/ - module load rocoto - -Hera and Jet: - -.. code-block:: console - - module purge - module load rocoto - -Orion: - -.. code-block:: console - - module purge - module load contrib rocoto - -Gaea: - -.. code-block:: console - - module use /lustre/f2/pdata/esrl/gsd/contrib/modulefiles - module load rocoto/1.3.3 - -WCOSS_DELL_P3: - -.. code-block:: console - - module purge - module load lsf/10.1 - module use /gpfs/dell3/usrx/local/dev/emc_rocoto/modulefiles/ - module load ruby/2.5.1 rocoto/1.2.4 - -WCOSS_CRAY: - -.. code-block:: console - - module purge - module load xt-lsfhpc/9.1.3 - module use -a /usrx/local/emc_rocoto/modulefiles - module load rocoto/1.2.4 - +Some systems may require a version number (e.g., ``module load rocoto/1.3.3``) Run the Rocoto Workflow ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -836,13 +786,13 @@ If the experiment fails, the ``rocotostat`` command will indicate which task fai Automated Option ---------------------- -For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry using the ``crontab -e`` command. As mentioned in :numref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *``), can be pasted into the crontab file. It can also be found in the ``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: +For automatic resubmission of the workflow at regular intervals (e.g., every minute), the user can add a crontab entry using the ``crontab -e`` command. As mentioned in :numref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.sh`` (starting with ``*/1 * * * *`` or ``*/3 * * * *``), can be pasted into the crontab file. It can also be found in the ``$EXPTDIR/log.generate_FV3LAM_wflow`` file. The crontab entry should resemble the following: .. code-block:: console - */1 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 + */3 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -where ```` is changed to correspond to the user's ``$EXPTDIR``, and ``/apps/rocoto/1.3.3/bin/rocotorun`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``1`` can be changed to a different positive integer and simply means that the workflow will be resubmitted every minute. +where ```` is changed to correspond to the user's ``$EXPTDIR``, and ``/apps/rocoto/1.3.3/bin/rocotorun`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``3`` can be changed to a different positive integer and simply means that the workflow will be resubmitted every three minutes. To check the experiment progress: @@ -851,7 +801,7 @@ To check the experiment progress: cd $EXPTDIR rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -After finishing the experiment, open the crontab using `` crontab -e`` and delete the crontab entry. +After finishing the experiment, open the crontab using ``crontab -e`` and delete the crontab entry. .. note:: diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 50436af86a..e79ad9e316 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -4,7 +4,7 @@ Quick Start Guide ==================================== -This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via an :term:`EPIC`-provided container reduces this variability and allows for a smoother SRW build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW. +This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via an :term:`EPIC`-provided container reduces this variability and allows for a smoother SRW App build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW. The "out-of-the-box" SRW case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. @@ -29,7 +29,7 @@ To build and run the SRW App using a Singularity container, first install the Si Working in the Cloud ----------------------- -For those working on non-cloud-based systems, skip to :numref:`Step %s `. Users building the SRW using NOAA's Cloud resources must complete a few additional steps to ensure that the SRW builds and runs correctly. +For those working on non-cloud-based systems, skip to :numref:`Step %s `. Users building the SRW App using NOAA's Cloud resources must complete a few additional steps to ensure that the SRW App builds and runs correctly. On NOAA Cloud systems, certain environment variables must be set *before* building the container: @@ -59,7 +59,7 @@ On HPC systems (including NOAA's Cloud platforms), allocate a compute node on wh mpirun -n 1 hostname ssh -The third command will output a hostname. Replace ```` in the last command with the output from the third command. After "ssh-ing" to the compute node in the last command, build and run the SRW from that node. +The third command will output a hostname. Replace ```` in the last command with the output from the third command. After "ssh-ing" to the compute node in the last command, build and run the SRW App from that node. The appropriate commands on other Level 1 platforms will vary, and users should consult the documentation for those platforms. @@ -121,8 +121,7 @@ From the ``ufs-srweather-app`` directory, ``cd`` into the build directory and ru Download and Stage the Data ============================ -The SRW requires input files to run. These include static datasets, initial and boundary condition -files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. +The SRW App requires input files to run. These include static datasets, initial and boundary condition files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. .. _GenerateForecastC: From a704a2fa61001d5944210d6ab36a5cc38ddfd4c0 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 21 Mar 2022 15:46:56 -0400 Subject: [PATCH 061/158] updated Intro based on feedback; changed SRW to SRW App throughout --- docs/UsersGuide/source/BuildRunSRW.rst | 15 +++--- docs/UsersGuide/source/Components.rst | 22 +++------ docs/UsersGuide/source/ConfigNewPlatform.rst | 6 +-- docs/UsersGuide/source/InputOutputFiles.rst | 48 +++++++------------- docs/UsersGuide/source/Introduction.rst | 44 +++++++++--------- docs/UsersGuide/source/Quickstart.rst | 8 ++-- 6 files changed, 60 insertions(+), 83 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index e7baac2ebc..d9967dce23 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -6,7 +6,7 @@ Building and Running the SRW App The Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. Once the SRW App is configured and built, users can generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. -This chapter walks users through how to build and run the "out-of-the-box" case for the SRW App. However, the steps are relevant to any SRW experiment and can be modified to suit user goals. The "out-of-the-box" SRW case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. +This chapter walks users through how to build and run the "out-of-the-box" case for the SRW App. However, the steps are relevant to any SRW Application experiment and can be modified to suit user goals. The "out-of-the-box" SRW App case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: @@ -50,18 +50,18 @@ Install the HPC-Stack Background ---------------- -The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF, etc.) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `__ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW. +The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF, etc.) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `__ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW App. Instructions ------------------------- -Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to run applications (such as the SRW) or models that depend on it. Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. +Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to run applications (such as the SRW App) or models that depend on it. Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. After completing installation, continue to the next section. .. _DownloadSRWApp: Download the UFS SRW Application Code -===================================== +====================================== The SRW Application source code is publicly available on GitHub. To download the SRW App, clone the release branch of the repository: .. code-block:: console @@ -84,7 +84,8 @@ The cloned repository contains the configuration files and sub-directories shown | CMakeLists.txt | Main cmake file for SRW App | +--------------------------------+--------------------------------------------------------+ | Externals.cfg | Includes tags pointing to the correct version of the | - | | external GitHub repositories/branches used in the SRW. | + | | external GitHub repositories/branches used in the SRW | + | | App. | +--------------------------------+--------------------------------------------------------+ | LICENSE.md | CC0 license information | +--------------------------------+--------------------------------------------------------+ @@ -236,14 +237,14 @@ The build will take a few minutes to complete. When it starts, a random number i Download and Stage the Data ============================ -The SRW App requires input files to run. These include static datasets, initial and boundary conditions files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. +The SRW App requires input files to run. These include static datasets, initial and boundary conditions files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW App tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. .. _GridSpecificConfig: Grid Configuration ======================= -The SRW App officially supports three different predefined grids as shown in :numref:`Table %s `. The "out-of-the-box" SRW case uses the ``RRFS_CONUS_25km`` predefined grid option. More information on the predefined and user-generated grid options can be found in :numref:`Chapter %s ` for those who are curious. Users who plan to utilize one of the three pre-defined domain (grid) options may continue to :numref:`Step %s `. Users who plan to create a new domain should refer to :numref:`Chapter %s ` for details on how to do so. At a minimum, these users will need to add the new grid name to the ``valid_param_vals`` script and add the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. +The SRW App officially supports three different predefined grids as shown in :numref:`Table %s `. The "out-of-the-box" SRW App case uses the ``RRFS_CONUS_25km`` predefined grid option. More information on the predefined and user-generated grid options can be found in :numref:`Chapter %s ` for those who are curious. Users who plan to utilize one of the three pre-defined domain (grid) options may continue to :numref:`Step %s `. Users who plan to create a new domain should refer to :numref:`Chapter %s ` for details on how to do so. At a minimum, these users will need to add the new grid name to the ``valid_param_vals`` script and add the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. .. _PredefinedGrids: diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index cf3728fbeb..6a358594e0 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -1,8 +1,8 @@ .. _Components: -=============== -SRW Components -=============== +============================ +SRW Application Components +============================ The SRW Application assembles a variety of components, including: @@ -19,11 +19,9 @@ These components are documented within this User's Guide and supported through a Pre-processor Utilities and Initial Conditions ============================================== -The SRW Application includes a number of pre-processing utilities that initialize and prepare the -model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid (``regional_esg_grid/make_hgrid``) along with :term:`orography` (``orog``) and surface climatology (``sfc_climo_gen``) files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of halo cells, additional utilities handle the correct number of halo shave points and topography filtering. The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format. These are needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. +The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid (``regional_esg_grid/make_hgrid``) along with :term:`orography` (``orog``) and surface climatology (``sfc_climo_gen``) files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of halo cells, additional utilities handle the correct number of halo shave points and topography filtering. The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format. These are needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. -The SRW Application can be initialized from a range of operational initial condition files. It is -possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (:term:`GRIB2`) format. GFS files also come in :term:`NEMSIO` format for past dates. +The SRW Application can be initialized from a range of operational initial condition files. It is possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (:term:`GRIB2`) format. GFS files also come in :term:`NEMSIO` format for past dates. .. WARNING:: For GFS data, dates prior to 1 January 2018 may work but are not guaranteed. Public archives of model data can be accessed through the `National Centers for Environmental Information `_ (NCEI) or through the `NOAA Operational Model Archive and Distribution System `_ (NOMADS). Raw external model data may be pre-staged on disk by the user. @@ -45,10 +43,7 @@ The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data Post-processor ============== -The SRW Application is distributed with the Unified Post Processor (:term:`UPP`) included in the -workflow as a way to convert the netCDF output on the native model grid to :term:`GRIB2` format on -standard isobaric vertical coordinates. The UPP can also be used to compute a variety of useful -diagnostic fields, as described in the `UPP User’s Guide `__. +The SRW Application is distributed with the Unified Post Processor (:term:`UPP`) included in the workflow as a way to convert the netCDF output on the native model grid to :term:`GRIB2` format on standard isobaric vertical coordinates. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `__. Output from UPP can be used with visualization, plotting, and verification packages or in further downstream post-processing (e.g., statistical post-processing techniques). @@ -57,10 +52,7 @@ Visualization Example ===================== A Python script is provided to create basic visualization of the model output. The script is designed to output graphics in PNG format for 14 standard meteorological variables -when using the pre-defined :term:`CONUS` domain. A difference plotting script is also included -to visually compare two runs for the same domain and resolution. These scripts are provided only -as an example for users familiar with Python. They may be used to perform a visual check to verify -that the application is producing reasonable results. +when using the pre-defined :term:`CONUS` domain. A difference plotting script is also included to visually compare two runs for the same domain and resolution. These scripts are provided only as an example for users familiar with Python. They may be used to perform a visual check to verify that the application is producing reasonable results. After running ``manage_externals/checkout_externals``, the visualization scripts will be available in the ``ufs-srweather-app/regional_workflow/ush/Python`` directory. Usage information and instructions are described in :numref:`Chapter %s ` and are also included at the top of the script. diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index 4d972d7e31..9e6f719851 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -57,7 +57,7 @@ However, it is also possible to install these utilities via Macports (https://ww Installing NCEPLIBS-external ============================ -In order to facilitate the installation of NCEPLIBS (and therefore, the SRW and other UFS applications) on new platforms, EMC maintains a one-stop package containing most of the prerequisite libraries and software necessary for installing NCEPLIBS. This package is known as NCEPLIBS-external, and is maintained in a git repository at https://github.com/NOAA-EMC/NCEPLIBS-external. Instructions for installing these will depend on your platform, but generally so long as all the above-mentioned prerequisites have been installed you can follow the proceeding instructions verbatim (in bash; a csh-based shell will require different commands). Some examples for installing on specific platforms can be found in the `NCEPLIBS-external/doc directory `. +In order to facilitate the installation of NCEPLIBS (and therefore, the SRW App and other UFS applications) on new platforms, EMC maintains a one-stop package containing most of the prerequisite libraries and software necessary for installing NCEPLIBS. This package is known as NCEPLIBS-external, and is maintained in a git repository at https://github.com/NOAA-EMC/NCEPLIBS-external. Instructions for installing these will depend on your platform, but generally so long as all the above-mentioned prerequisites have been installed you can follow the proceeding instructions verbatim (in bash; a csh-based shell will require different commands). Some examples for installing on specific platforms can be found in the `NCEPLIBS-external/doc directory `. These instructions will install the NCEPLIBS-external in the current directory tree, so be sure you are in the desired location before starting. @@ -126,8 +126,8 @@ Further information on including prerequisite libraries, as well as other helpfu Once the NCEPLIBS package has been successfully installed, you can move on to building the UFS SRW Application. -Building the UFS Short-Range Weather Application (UFS SRW App) -============================================================== +Building the UFS SRW Application +======================================= Building the UFS SRW App is similar to building NCEPLIBS, in that the code is stored in a git repository and is built using CMake software. The first step is to retrieve the code from GitHub, using the variables defined earlier: .. code-block:: console diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index d1079c78fb..5e2f118cd0 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -1,10 +1,10 @@ .. _InputOutputFiles: -====================== +======================= Input and Output Files -====================== +======================= This chapter provides an overview of the input and output files needed by the components -of the UFS SRW Application (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`). Links to more detailed documentation for each of the components are provided. For SRW users who want to jump straight to downloading and staging the files, see :numref:`Section %s `. +of the UFS SRW Application (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`). Links to more detailed documentation for each of the components are provided. For SRW App users who want to jump straight to downloading and staging the files, see :numref:`Section %s `. .. _Input: @@ -25,8 +25,7 @@ the external model data can be found in :numref:`Section %s `, :numref:`Step %s Generate the Forecast Experiment ` links the input data for the pre-processing utilities from a location on disk to the experiment directory. The -pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here `__. +When a user runs the SRW Application as described in the Quick Start Guide :numref:`Chapter %s `, :numref:`Step %s Generate the Forecast Experiment ` links the input data for the pre-processing utilities from a location on disk to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here `__. UFS Weather Model ----------------- @@ -44,8 +43,7 @@ Workflow -------- The SRW Application uses a series of template files, combined with user-selected settings, to create the required namelists and parameter files needed by the Application. These -templates can be reviewed to see what defaults are being used and where configuration parameters -from the ``config.sh`` file are assigned. +templates can be reviewed to see what defaults are being used and where configuration parameters from the ``config.sh`` file are assigned. List of Template Files ^^^^^^^^^^^^^^^^^^^^^^ @@ -103,10 +101,7 @@ while information on the ``regional_grid.nml`` can be found in the `UFS_UTILS Us Migratory Route of the Input Files in the Workflow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :numref:`Figure %s ` shows how the case-specific input files in the -``ufs-srweather-app/regional_workflow/ush/templates/`` directory flow to the experiment directory. -The value of ``CCPP_PHYS_SUITE`` is specified in the configuration file ``config.sh``. The template -input files corresponding to ``CCPP_PHYS_SUITE``, such as ``field_table`` and ``nems_configure``, are copied to the experiment directory ``EXPTDIR``, and the namelist file of the weather model ``input.nml`` is created from the ``input.nml.FV3`` and ``FV3.input.yml`` files by running the script ``generate_FV3LAM_wflow.sh``. -While running the task ``RUN_FCST`` in the regional workflow as shown in :numref:`Figure %s `, the ``field_table``, ``nems.configure``, and ``input.nml`` files, located in ``EXPTDIR``, are linked to the cycle directory ``CYCLE_DIR/``. Additionally, ``diag_table`` and ``model_configure`` are copied from the ``templates`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. +``ufs-srweather-app/regional_workflow/ush/templates/`` directory flow to the experiment directory. The value of ``CCPP_PHYS_SUITE`` is specified in the configuration file ``config.sh``. The template input files corresponding to ``CCPP_PHYS_SUITE``, such as ``field_table`` and ``nems_configure``, are copied to the experiment directory ``EXPTDIR``, and the namelist file of the weather model ``input.nml`` is created from the ``input.nml.FV3`` and ``FV3.input.yml`` files by running the script ``generate_FV3LAM_wflow.sh``. While running the task ``RUN_FCST`` in the regional workflow as shown in :numref:`Figure %s `, the ``field_table``, ``nems.configure``, and ``input.nml`` files, located in ``EXPTDIR``, are linked to the cycle directory ``CYCLE_DIR/``. Additionally, ``diag_table`` and ``model_configure`` are copied from the ``templates`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. .. _MigratoryRoute: @@ -150,14 +145,12 @@ UFS Weather Model As mentioned previously, the workflow can be run in ‘community’ or ‘nco’ mode, which determines the location and names of the output files. In addition to this option, output can also be in netCDF or NEMSIO format. The output file format is set in the ``model_configure`` files using the -``output_file`` variable. At this time, due to limitations in the post-processing component, only netCDF -format output is recommended for the SRW application. +``output_file`` variable. At this time, due to limitations in the post-processing component, only netCDF format output is recommended for the SRW Application. .. note:: In summary, the fully supported options for this release include running in ‘community’ mode with netCDF format output files. -In this case, the netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH`` directory. The bases of -the file names are specified in the input file ``model_configure`` and are set to the following in the SRW Application: +In this case, the netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH`` directory. The bases of the file names are specified in the input file ``model_configure`` and are set to the following in the SRW Application: * ``dynfHHH.nc`` * ``phyfHHH.nc`` @@ -169,16 +162,14 @@ Unified Post Processor (UPP) ---------------------------- Documentation for the UPP output files can be found `here `__. -For the SRW Application, the weather model netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH/postprd`` -directory and have the naming convention (file->linked to): +For the SRW Application, the weather model netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH/postprd`` directory and have the naming convention (file->linked to): * ``BGRD3D_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgrd3df{fhr}.tmXX.grib2`` * ``BGDAWP_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgdawpf{fhr}.tmXX.grib2`` The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by the user in the ``config.sh`` settings. -If you wish to modify the fields or levels that are output from the UPP, you will need to make -modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. +If you wish to modify the fields or levels that are output from the UPP, you will need to make modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. .. note:: This process requires advanced knowledge of which fields can be output for the UFS Weather Model. @@ -193,8 +184,7 @@ Once you have created the new flat text file reflecting your changes, you will n USE_CUSTOM_POST_CONFIG_FILE=”TRUE” CUSTOM_POST_CONFIG_PATH=”” -which tells the workflow to use the custom file located in the user-defined path. The path should -include the filename. If this is set to true and the file path is not found, then an error will occur when trying to generate the SRW Application workflow. +which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If this is set to true and the file path is not found, then an error will occur when trying to generate the SRW Application workflow. You may then start your case workflow as usual and the UPP will use the new flat ``*.txt`` file. @@ -202,8 +192,7 @@ You may then start your case workflow as usual and the UPP will use the new flat Downloading and Staging Input Data ================================== -A set of input files, including static (fix) data and raw initial and lateral boundary conditions -(:term:`IC/LBC`'s), are needed to run the SRW Application. +A set of input files, including static (fix) data and raw initial and lateral boundary conditions (:term:`IC/LBC`'s), are needed to run the SRW Application. .. _StaticFixFiles: @@ -229,7 +218,7 @@ Initial Condition Formats and Source ------------------------------------ The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, netCDF, or :term:`GRIB2`. The SRW Application currently only supports the use of NEMSIO and netCDF input files from the GFS. -The data required to run the "out-of'the-box" SRW case described in :numref:`Chapter %s ` is already preinstalled on `Level 1 `__ systems. Users on other systems can find the required IC/LBC data in the `FTP data repository `__ or on `AWS cloud storage `_. +The data required to run the "out-of-the-box" SRW App case described in :numref:`Chapter %s ` is already preinstalled on `Level 1 `__ systems. Users on other systems can find the required IC/LBC data in the `FTP data repository `__ or on `AWS cloud storage `_. To add this data to your system, run the following commands from the ``ufs-srweather-app`` directory: @@ -260,13 +249,9 @@ These environment variables describe what :term:`IC/LBC` files to use (pre-stage Initial and Lateral Boundary Condition Organization --------------------------------------------------- The suggested directory structure and naming convention for the raw input files is described -below. While there is flexibility to modify these settings, this will provide the most reusability -for multiple dates when using the SRW Application workflow. +below. While there is flexibility to modify these settings, this will provide the most reusability for multiple dates when using the SRW Application workflow. -For ease of reusing the ``config.sh`` for multiple dates and cycles, it is recommended to set up -your raw :term:`IC/LBC` files such that it includes the model name (e.g., FV3GFS, NAM, RAP, HRRR) and ``YYYYMMDDHH``, for example: ``/path-to/model_data/FV3GFS/2019061518``. Since both initial -and lateral boundary condition files are necessary, you can also include an ICS and LBCS directory. -The sample IC/LBC's available at the FTP data repository are structured as follows: +For ease of reusing the ``config.sh`` for multiple dates and cycles, it is recommended to set up your raw :term:`IC/LBC` files such that it includes the model name (e.g., FV3GFS, NAM, RAP, HRRR) and ``YYYYMMDDHH``, for example: ``/path-to/model_data/FV3GFS/2019061518``. Since both initial and lateral boundary condition files are necessary, you can also include an ICS and LBCS directory. The sample IC/LBC's available at the FTP data repository are structured as follows: * ``/path-to/model_data/MODEL/YYYYMMDDHH/ICS`` * ``/path-to/model_data/MODEL/YYYYMMDDHH/LBCS`` @@ -330,8 +315,7 @@ Staging Initial Conditions Manually ----------------------------------- If users want to run the SRW Application with raw model files for dates other than what are currently available on the preconfigured platforms, they need to stage the data manually. -The data should be placed in ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. -The path to these variables can be set in the ``config.sh`` file. Raw model files are available from a number of sources. A few examples are provided here for convenience. +The data should be placed in ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. The path to these variables can be set in the ``config.sh`` file. Raw model files are available from a number of sources. A few examples are provided here for convenience. NOMADS: https://nomads.ncep.noaa.gov/pub/data/nccf/com/{model}/prod, where model may be: diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 6f8f0b6ac8..4f94a9ae2c 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -4,9 +4,11 @@ Introduction ============== -The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. The UFS is the source system for NOAA’s operational numerical weather prediction applications. It enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. +The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. NOAA’s operational model suite for numerical weather prediction (:term:`NWP`) is quickly transitioning to the UFS from a number of different modeling systems. The UFS enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. -The UFS can be configured for `multiple applications `__. The configuration described in this documentation is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to several days. The SRW Application v1.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. Future work will expand the capabilities of the application to include data assimilation (DA) and a verification package (e.g., METplus). This documentation provides a :ref:`Quick Start Guide ` for running the application in a container and a :ref:`detailed guide ` for running the SRW on supported platforms. It also provides an overview of the :ref:`release components ` and details on how to customize or modify different portions of the workflow. +The UFS includes `multiple applications `__ that support different forecast durations and spatial domains. This documentation describes the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes to several days. The SRW Application v1.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. New and improved capabilities for this release include the addition of a verification package (MetPLUS) for both deterministic and ensemble simulations and support for four Stochastically Perturbed Perturbation (SPP) schemes. Future work will expand the capabilities of the application to include data assimilation (DA) and a forecast restart/cycling capability. + +This documentation provides a :ref:`Quick Start Guide ` for running the SRW Application in a container and a :ref:`detailed guide ` for running the SRW App on supported platforms. It also provides an overview of the :ref:`release components ` and details on how to customize or modify different portions of the workflow. The SRW App v1.0.0 citation is as follows and should be used when presenting results based on research conducted with the App: @@ -28,23 +30,23 @@ This guide instructs both novice and experienced users on downloading, building, Variables presented as ``AaBbCc123`` in this User's Guide typically refer to variables in scripts, names of files, and directories. -File paths or code that include angle brackets (e.g., ``build__.env``) indicate that users should insert options appropriate to their SRW configuration (e.g., ``build_orion_intel.env``). +File paths or code that include angle brackets (e.g., ``build__.env``) indicate that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel.env``). .. hint:: - * To get started running the SRW, see the :ref:`Quick Start Guide ` for beginners or refer to the in-depth chapter on :ref:`Running the Short-Range Weather Application `. - * For background information on the SRW code repositories and directory structure, see :numref:`Section %s ` below. - * For an outline of SRW components, see section :numref:`Section %s ` below or refer to :numref:`Chapter %s ` for a more in-depth treatment. + * To get started running the SRW App, see the :ref:`Quick Start Guide ` for beginners or refer to the in-depth chapter on :ref:`Running the Short-Range Weather Application `. + * For background information on the SRW App code repositories and directory structure, see :numref:`Section %s ` below. + * For an outline of SRW App components, see section :numref:`Section %s ` below or refer to :numref:`Chapter %s ` for a more in-depth treatment. .. _ComponentsOverview: -SRW Components Overview -============================ +SRW App Components Overview +============================== Pre-processor Utilities and Initial Conditions ------------------------------------------------ -The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. The pre-processing software converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, these files are used as input to the atmospheric model (FV3-LAM). Additional information about the pre-processor utilities can be found in :numref:`Chapter %s ` and in the `UFS_UTILS User’s Guide `_. +The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Tasks include generating a regional grid along with :term:`orography` and surface climatology files for that grid. One pre-processing utility converts the raw external model data into initial and lateral boundary condition files in netCDF format. Later, these files are used as input to the atmospheric model (FV3-LAM). Additional information about the pre-processor utilities can be found in :numref:`Chapter %s ` and in the `UFS_UTILS User’s Guide `_. Forecast Model @@ -54,24 +56,23 @@ Atmospheric Model ^^^^^^^^^^^^^^^^^^^^^^ The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability (:cite:t:`BlackEtAl2020`). -The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. +(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability (:cite:t:`BlackEtAl2020`). The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. Common Community Physics Package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and Noah Multi-parameterization (Noah MP) Land Surface Model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW release includes an experimental physics version and an updated operational version. +The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and land surface model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW App release includes an experimental physics version and an updated operational version. Data Format ^^^^^^^^^^^^^^^^^^^^^^ -The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube`. +The SRW App supports the use of external model data in :term:`GRIB2`, :term:`NEMSIO`, and netCDF format when generating initial and boundary conditions. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube`. Unified Post-Processor (UPP) -------------------------------- -The `Unified Post Processor `__ (:term:`UPP`) processes raw output from a variety of numerical weather prediction (:term:`NWP`) models. In the SRW, it converts data output formats from netCDF format on the native model grid to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from the UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). +The `Unified Post Processor `__ (:term:`UPP`) processes raw output from a variety of numerical weather prediction (:term:`NWP`) models. In the SRW App, it converts data output from netCDF format to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from the UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). Visualization Example @@ -84,9 +85,9 @@ Build System and Workflow The SRW Application has a portable CMake-based build system that packages together all the components required to build the SRW Application. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see `Rocoto documentation `__ for more on workflow management). Individual components can also be run in a stand-alone, command line fashion. -The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite for the forecast. +The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite used for the simulation. -This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application. Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW code ` without first installing prerequisites. On other platforms, the SRW can be :ref:`run within a container ` that includes the HPC-Stack, or the required libraries will need to be installed as part of the :ref:`SRW build ` process. Once these prerequisite libraries are installed, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application. Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW App code ` without first installing prerequisites. On other platforms, the SRW App can be :ref:`run within a container ` that includes the HPC-Stack, or the required libraries will need to be installed as part of the :ref:`SRW Application build ` process. Once these prerequisite libraries are installed, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. @@ -99,7 +100,7 @@ Code Repositories and Directory Structure Hierarchical Repository Structure ----------------------------------- -The :term:`umbrella repository` for the SRW Application is named ``ufs-srweather-app`` and is available on GitHub at https://github.com/ufs-community/ufs-srweather-app. An umbrella repository is a repository that houses external code, called "externals," from additional repositories. The SRW Application includes the ``manage_externals`` tool and a configuration file called ``Externals.cfg``, which describes the external repositories associated with the SRW umbrella repository (see :numref:`Table %s `). +The :term:`umbrella repository` for the SRW Application is named ``ufs-srweather-app`` and is available on GitHub at https://github.com/ufs-community/ufs-srweather-app. An umbrella repository is a repository that houses external code, called "externals," from additional repositories. The SRW Application includes the ``manage_externals`` tool and a configuration file called ``Externals.cfg``, which describes the external repositories associated with the SRW App umbrella repository (see :numref:`Table %s `). .. _top_level_repos: @@ -255,7 +256,7 @@ When the user generates an experiment using the ``generate_FV3LAM_wflow.sh`` scr | YYYYMMDDHH | Cycle directory (empty) | +---------------------------+-------------------------------------------------------------------------------------------------------+ -In addition, running the SRW in *community* mode creates the ``fix_am`` and ``fix_lam`` directories in ``EXPTDIR``. The ``fix_lam`` directory is initially empty but will contain some *fix* (time-independent) files after the grid, orography, and/or surface climatology generation tasks are run. +In addition, running the SRW App in *community* mode creates the ``fix_am`` and ``fix_lam`` directories in ``EXPTDIR``. The ``fix_lam`` directory is initially empty but will contain some *fix* (time-independent) files after the grid, orography, and/or surface climatology generation tasks are run. .. _FixDirectories: @@ -363,7 +364,7 @@ A list of available documentation is shown in :numref:`Table %s `. +utilities, model code, and infrastructure. Users can post issues in the related GitHub repositories to report bugs or to announce upcoming contributions to the code base. For code to be accepted in the authoritative repositories, users must follow the code management rules of each UFS component repository, which are outlined in the respective User's Guides listed in :numref:`Table %s `. Future Direction ================= @@ -372,9 +373,8 @@ Users can expect to see incremental improvements and additional capabilities in * A more extensive set of supported developmental physics suites. * A larger number of pre-defined domains/resolutions and a fully supported capability to create a user-defined domain. -* Inclusion of data assimilation, cycling, and ensemble capabilities. -* A verification package (e.g., METplus) integrated into the workflow. -* Inclusion of stochastic perturbation techniques. +* Inclusion of data assimilation and forecast restart/cycling capabilities. + .. bibliography:: references.bib diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index e79ad9e316..af48734a60 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -4,9 +4,9 @@ Quick Start Guide ==================================== -This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via an :term:`EPIC`-provided container reduces this variability and allows for a smoother SRW App build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW. +This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via an :term:`EPIC`-provided container reduces this variability and allows for a smoother SRW App build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW App. -The "out-of-the-box" SRW case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. +The "out-of-the-box" SRW App case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: @@ -50,7 +50,7 @@ Working on HPC Systems -------------------------- Those *not* working on HPC systems may skip to the :ref:`next step `. -On HPC systems (including NOAA's Cloud platforms), allocate a compute node on which to run the SRW. On NOAA's Cloud platforms, the following commands will allocate a compute node: +On HPC systems (including NOAA's Cloud platforms), allocate a compute node on which to run the SRW App. On NOAA's Cloud platforms, the following commands will allocate a compute node: .. code-block:: console @@ -121,7 +121,7 @@ From the ``ufs-srweather-app`` directory, ``cd`` into the build directory and ru Download and Stage the Data ============================ -The SRW App requires input files to run. These include static datasets, initial and boundary condition files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW. +The SRW App requires input files to run. These include static datasets, initial and boundary condition files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW App tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. .. _GenerateForecastC: From 7fc263d169aa88fbd8aa61561ef200ca119b7761 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 21 Mar 2022 16:21:17 -0400 Subject: [PATCH 062/158] update comment to Intro citation --- docs/UsersGuide/source/Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 4f94a9ae2c..b63fedc989 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -15,7 +15,7 @@ The SRW App v1.0.0 citation is as follows and should be used when presenting res UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994 .. - COMMENT: Update version numbers/citation for release! + COMMENT: Update version numbers/citation for release! Also update release date for citation! How to Use This Document From 10de71f603f34bf1f8ba6557409247e89517a269 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 22 Mar 2022 10:48:29 -0400 Subject: [PATCH 063/158] add user-defined vertical levels to future work --- docs/UsersGuide/source/Introduction.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index b63fedc989..0f57424d20 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -373,6 +373,7 @@ Users can expect to see incremental improvements and additional capabilities in * A more extensive set of supported developmental physics suites. * A larger number of pre-defined domains/resolutions and a fully supported capability to create a user-defined domain. +* Add user-defined vertical levels (number and distribution). * Inclusion of data assimilation and forecast restart/cycling capabilities. From 92bddcae8da6ca734826fb1a145bae08b4c43937 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Mar 2022 11:41:03 -0400 Subject: [PATCH 064/158] Add instructions for srw_common module load --- docs/UsersGuide/source/BuildRunSRW.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index d9967dce23..0be096c74c 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -128,7 +128,14 @@ Run the executable that pulls in SRW App components from external repositories: Set up the Build Environment ============================ -Before building the SRW App, the build environment must be set up for the user's specific platform. For Level 1 systems, scripts for loading the proper modules and/or setting the correct environment variables can be found in the ``env`` directory of the SRW App in files named ``build__.env``. Here is a sample directory listing of these build files: +Before building the SRW App, the build environment must be set up for the user's specific platform. There is a set of common modules required to build the SRW App. These are located in the ``env/srw_common`` file. To load the set of common modules, run: + +.. code-block:: console + module use + +where ```` is the full path to the ``env`` directory. + +Then, users must set up the platform-specific elements of the build environment. For Level 1 systems, scripts for loading the proper modules and/or setting the correct environment variables can be found in the ``env`` directory of the SRW App in files named ``build__.env``. Here is a sample directory listing of these build files: .. code-block:: console From 6fa50748e64d1dad7d63b7a2b333b3eadbad6c73 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Mar 2022 11:52:35 -0400 Subject: [PATCH 065/158] fix typo --- docs/UsersGuide/source/BuildRunSRW.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 0be096c74c..5481f6b25e 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -131,6 +131,7 @@ Set up the Build Environment Before building the SRW App, the build environment must be set up for the user's specific platform. There is a set of common modules required to build the SRW App. These are located in the ``env/srw_common`` file. To load the set of common modules, run: .. code-block:: console + module use where ```` is the full path to the ``env`` directory. From a5ae76eff8261007ea1f46023dd0372bf2b96802 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Mar 2022 18:51:42 -0400 Subject: [PATCH 066/158] update Intro & BuildRunSRW based on Mark's feedback --- docs/UsersGuide/source/BuildRunSRW.rst | 7 ++++++- docs/UsersGuide/source/Introduction.rst | 4 +++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 5481f6b25e..85ae658c5e 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -801,7 +801,12 @@ For automatic resubmission of the workflow at regular intervals (e.g., every min */3 * * * * cd && /apps/rocoto/1.3.3/bin/rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -where ```` is changed to correspond to the user's ``$EXPTDIR``, and ``/apps/rocoto/1.3.3/bin/rocotorun`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``3`` can be changed to a different positive integer and simply means that the workflow will be resubmitted every three minutes. +where ```` is changed to correspond to the user's ``$EXPTDIR``, and ``/apps/rocoto/1.3.3/bin/rocotorun`` corresponds to the location of the ``rocotorun`` command on the user's system. The number ``3`` can be changed to a different positive integer and simply means that the workflow will be resubmitted every three minutes. + +.. hint:: + + * On NOAA Cloud instances, ``*/1 * * * *`` is the preferred option for cron jobs because compute nodes will shut down if they remain idle too long. If the compute node shuts down, it can take 15-20 minutes to start up a new one. + * On other NOAA HPC systems, admins discourage the ``*/1 * * * *`` due to load problems. ``*/3 * * * *`` is the preferred option for cron jobs on non-Cloud systems. To check the experiment progress: diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 0f57424d20..62c98c7c47 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -87,7 +87,7 @@ The SRW Application has a portable CMake-based build system that packages togeth The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite used for the simulation. -This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application. Preconfigured (Level 1) systems already have the required external libraries (e.g., NCEPLIBS) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW App code ` without first installing prerequisites. On other platforms, the SRW App can be :ref:`run within a container ` that includes the HPC-Stack, or the required libraries will need to be installed as part of the :ref:`SRW Application build ` process. Once these prerequisite libraries are installed, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application. Preconfigured (Level 1) systems already have the required external libraries (e.g., HPC-Stack) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW App code ` without first installing prerequisites. On other platforms, the SRW App can be :ref:`run within a container ` that includes the HPC-Stack, or the required libraries will need to be installed as part of the :ref:`SRW Application build ` process. Once these prerequisite libraries are installed, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. @@ -345,6 +345,8 @@ A list of available documentation is shown in :numref:`Table %s ` | + +----------------------------+---------------------------------------------------------------------------------+ | NCEPLIBS Documentation | https://github.com/NOAA-EMC/NCEPLIBS/wiki | +----------------------------+---------------------------------------------------------------------------------+ | NCEPLIBS-external | https://github.com/NOAA-EMC/NCEPLIBS-external/wiki | From ea17b193f04db2f3989d524ecee2007a8a5c6a1a Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 23 Mar 2022 19:01:44 -0400 Subject: [PATCH 067/158] minor intro updates --- docs/UsersGuide/source/Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 62c98c7c47..f266640f3d 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -87,7 +87,7 @@ The SRW Application has a portable CMake-based build system that packages togeth The SRW Application allows for configuration of various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, time step, and the physics suite used for the simulation. -This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application. Preconfigured (Level 1) systems already have the required external libraries (e.g., HPC-Stack) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW App code ` without first installing prerequisites. On other platforms, the SRW App can be :ref:`run within a container ` that includes the HPC-Stack, or the required libraries will need to be installed as part of the :ref:`SRW Application build ` process. Once these prerequisite libraries are installed, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. +This SRW Application release has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g. Hera, Orion), cloud environments, and generic Linux and macOS systems. Four `levels of support `_ have been defined for the SRW Application. Preconfigured (Level 1) systems already have the required external libraries (HPC-Stack) available in a central location. The SRW Application is expected to build and run out-of-the-box on these systems, and users can :ref:`download the SRW App code ` without first installing prerequisites. On other platforms, the SRW App can be :ref:`run within a container ` that includes the HPC-Stack, or the required libraries will need to be installed as part of the :ref:`SRW Application build ` process. Once these prerequisite libraries are installed, applications and models should build and run successfully. However, users may need to perform additional troubleshooting on Level 3 or 4 systems since little or no pre-release testing has been conducted on these systems. From 1aa932247cabc1a2d8d0801e786c82ab6923a59b Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 25 Mar 2022 15:23:50 -0400 Subject: [PATCH 068/158] 1st round of jwolff's edits --- docs/UsersGuide/source/BuildRunSRW.rst | 26 +++++++++++++------------- docs/UsersGuide/source/Components.rst | 2 +- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 85ae658c5e..4a22720537 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -6,14 +6,14 @@ Building and Running the SRW App The Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application is an :term:`umbrella repository` consisting of a number of different :ref:`components ` housed in external repositories. Once the SRW App is configured and built, users can generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. -This chapter walks users through how to build and run the "out-of-the-box" case for the SRW App. However, the steps are relevant to any SRW Application experiment and can be modified to suit user goals. The "out-of-the-box" SRW App case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. +This chapter walks users through how to build and run the "out-of-the-box" case for the SRW App. However, the steps are relevant to any SRW Application experiment and can be modified to suit user goals. The "out-of-the-box" SRW App case builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) domain (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: All UFS applications support `four platform levels `_. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. On Level 1 systems, all of the required libraries for building community releases of UFS models and applications are available in a central location. This guide can serve as a starting point for running the SRW App on other systems, too, but the user may need to perform additional troubleshooting. .. note:: - The :ref:`container approach ` is recommended for a smoother build and run experience. Building without a container allows for the use of the Rocoto workflow manager and may allow for more customization. However, the non-container approach requires more in-depth troubleshooting skills, especially on Level 3 and 4 systems, and is less appropriate for beginners. + The :ref:`container approach ` is recommended for a smoother build and run experience. Building without a container allows for the use of the Rocoto workflow manager and may allow for more customization. However, the non-container approach requires more in-depth system-based knowledge, especially on Level 3 and 4 systems; it is less appropriate for beginners. The overall procedure for generating an experiment is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. The steps are as follows: @@ -54,7 +54,7 @@ The UFS Weather Model draws on over 50 code libraries to run its applications. T Instructions ------------------------- -Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to run applications (such as the SRW App) or models that depend on it. Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. +Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to build applications (such as the SRW App) or models that depend on it. Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. After completing installation, continue to the next section. @@ -62,7 +62,7 @@ After completing installation, continue to the next section. Download the UFS SRW Application Code ====================================== -The SRW Application source code is publicly available on GitHub. To download the SRW App, clone the release branch of the repository: +The SRW Application source code is publicly available on GitHub. To download the SRW App, clone the ``develop`` branch of the repository: .. code-block:: console @@ -98,7 +98,7 @@ The cloned repository contains the configuration files and sub-directories shown +--------------------------------+--------------------------------------------------------+ | env | Contains build and workflow environment files | +--------------------------------+--------------------------------------------------------+ - | docs | Contains release notes, documentation, and Users' Guide| + | docs | Contains release notes, documentation, and User's Guide| +--------------------------------+--------------------------------------------------------+ | manage_externals | Utility for checking out external repositories | +--------------------------------+--------------------------------------------------------+ @@ -154,7 +154,7 @@ On Level 1 systems, the commands in the ``build__.env`` file from the main ``ufs-srweather-app`` directory to source the appropriate file. -On Level 2-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. To check if Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, users can modify or set the required environment variables using commands in the form ``export =``. Users may need to use ``setenv`` rather than ``export`` depending on their shell environment. +On Level 2-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. To check if Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, users can modify or set the required environment variables using commands in the form ``export =``. Users may need to use ``setenv`` rather than ``export`` depending on their shell environment. For example, ``setenv ``. .. _BuildExecutables: @@ -294,7 +294,7 @@ Default configuration: ``config_defaults.sh`` ------------------------------------------------ .. note:: - This section provides background information on how the SRW App uses the ``config_defaults.sh`` file. This information is helpful but not essential to running the SRW App. Users may skip to :numref:`Step %s ` to continue configuring their experiment. + This section provides background information on how the SRW App uses the ``config_defaults.sh`` file. This information is informative, but users do not need to modify ``config_defaults.sh`` to run the out-of-the-box case for the SRW App. Users may skip to :numref:`Step %s ` to continue configuring their experiment. Important configuration variables in the ``config_defaults.sh`` file appear in :numref:`Table %s `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified ``config.sh`` file. Any settings provided in ``config.sh`` will override the default ``config_defaults.sh`` @@ -413,7 +413,7 @@ settings. There is usually no need for a user to modify the default configuratio User-specific configuration: ``config.sh`` -------------------------------------------- -The user must specify certain basic information about the experiment in a ``config.sh`` file located in the ``ufs-srweather-app/regional_workflow/ush`` directory. Two example templates are provided in that directory: ``config.community.sh`` and ``config.nco.sh``. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. The operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing for the Rapid-Refresh Forecast System (RRFS). :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. +The user must specify certain basic information about the experiment in a ``config.sh`` file located in the ``ufs-srweather-app/regional_workflow/ush`` directory. Two example templates are provided in that directory: ``config.community.sh`` and ``config.nco.sh``. The first file is a minimal example for creating and running an experiment in the *community* mode (with ``RUN_ENVIR`` set to ``community``). The second is an example for creating and running an experiment in the *NCO* (operational) mode (with ``RUN_ENVIR`` set to ``nco``). The *community* mode is recommended in most cases and will be fully supported for this release. The operational/NCO mode will typically be used by those at the NOAA/NCEP/Environmental Modeling Center (EMC) and the NOAA/Global Systems Laboratory (GSL) working on pre-implementation testing for the Rapid Refresh Forecast System (RRFS). :numref:`Table %s ` shows the configuration variables, along with their default values in ``config_default.sh`` and the values defined in ``config.community.sh``. .. _ConfigCommunity: @@ -426,7 +426,7 @@ The user must specify certain basic information about the experiment in a ``conf +--------------------------------+-------------------+--------------------------------------------------------+ | ACCOUNT | "project_name" | "an_account" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXPT_SUBDIR | "" | "test_CONUS_25km_GFSv15p2" | + | EXPT_SUBDIR | "" | "test_CONUS_25km_GFSv16" | +--------------------------------+-------------------+--------------------------------------------------------+ | VERBOSE | "TRUE" | "TRUE" | +--------------------------------+-------------------+--------------------------------------------------------+ @@ -440,7 +440,7 @@ The user must specify certain basic information about the experiment in a ``conf +--------------------------------+-------------------+--------------------------------------------------------+ | QUILTING | "TRUE" | "TRUE" | +--------------------------------+-------------------+--------------------------------------------------------+ - | CCPP_PHYS_SUITE | "FV3_GSD_V0" | "FV3_GFS_v15p2" | + | CCPP_PHYS_SUITE | "FV3_GSD_V0" | "FV3_GFS_v16" | +--------------------------------+-------------------+--------------------------------------------------------+ | FCST_LEN_HRS | "24" | "48" | +--------------------------------+-------------------+--------------------------------------------------------+ @@ -481,7 +481,7 @@ To get started, make a copy of ``config.community.sh``. From the ``ufs-srweather cd regional_workflow/ush cp config.community.sh config.sh -The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. +The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. Next, edit the new ``config.sh`` file to customize it for your machine. At a minimum, change the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If you have pre-staged the initialization data for the experiment, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and set the paths to the data for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. @@ -505,8 +505,8 @@ Minimum parameter settings for Level 1 machines: ACCOUNT="" EXPT_SUBDIR="" USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_app/model_data/FV3GFS" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_app/model_data/FV3GFS" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_app/develop/staged_extrn_mdl_files" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_app/develop/staged_extrn_mdl_files" **Hera:** diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index 6a358594e0..eb76b19c10 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 64 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 `here `__ and on the `NOAA Geophysical Fluid Dynamics Laboratory website `_. -Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) Land Surface Model options, are supported through the Common Community Physics Package (:term:`CCPP`), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are two physics options supported for the release. The first is an experimental physics suite 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) v15. 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 +Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) Land Surface Model options, are supported through the Common Community Physics Package (:term:`CCPP`), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are two physics options supported for the release. The first is an experimental physics suite 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. 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. The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal direction and model levels in the vertical direction. From 3d1cddbebc7e3f3664f6887ca614e82a7a33c740 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 28 Mar 2022 19:20:31 -0400 Subject: [PATCH 069/158] 2nd round of jwolff updates --- docs/UsersGuide/source/BuildRunSRW.rst | 71 ++++++++++++++++----- docs/UsersGuide/source/Components.rst | 9 ++- docs/UsersGuide/source/InputOutputFiles.rst | 18 ++++-- docs/UsersGuide/source/Introduction.rst | 16 ++--- docs/UsersGuide/source/Quickstart.rst | 15 ++--- 5 files changed, 85 insertions(+), 44 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 4a22720537..5eee295f30 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -154,7 +154,13 @@ On Level 1 systems, the commands in the ``build__.env`` file from the main ``ufs-srweather-app`` directory to source the appropriate file. -On Level 2-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. To check if Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, users can modify or set the required environment variables using commands in the form ``export =``. Users may need to use ``setenv`` rather than ``export`` depending on their shell environment. For example, ``setenv ``. +On Level 2-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__.env`` files can be copied and used as a template. To check whether Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, users can modify or set the required environment variables with the ``export`` or ``setenv`` commands despending on whether they are using a bash or csh/tcsh shell, respectively: + +.. code-block:: + + export = + setenv + .. _BuildExecutables: @@ -495,7 +501,7 @@ Sample settings are indicated below for Level 1 platforms. Detailed guidance app To determine an appropriate ACCOUNT field for Level 1 systems, run ``groups``, and it will return a list of projects you have permissions for. Not all of the listed projects/groups have an HPC allocation, but those that do are potentially valid account names. -Minimum parameter settings for Level 1 machines: +Minimum parameter settings for running the out-of-the-box SRW App case on Level 1 machines: **Cheyenne:** @@ -505,28 +511,61 @@ Minimum parameter settings for Level 1 machines: ACCOUNT="" EXPT_SUBDIR="" USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_app/develop/staged_extrn_mdl_files" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_app/develop/staged_extrn_mdl_files" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_app/staged_extrn_mdl_files" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_app/staged_extrn_mdl_files" -**Hera:** +**Hera, Jet, Orion, Gaea:** + +The ``MACHINE``, ``ACCOUNT``, and ``EXPT_SUBDIR`` settings are the same as for Cheyenne, except that ``"cheyenne"`` should be switched to ``"hera"``, ``"jet"``, ``"orion"``, or ``"gaea"``, respectively. Set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, but replace the file paths to Cheyenne's data with the file paths for the correct machine. ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` use the same file path. + +On Hera: .. code-block:: console - MACHINE="hera" - ACCOUNT="" - EXPT_SUBDIR="" + "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data" + +On Jet: + +.. code-block:: console + + "/lfs4/BMC/wrfruc/FV3-LAM/model_data" + +On Orion: + +.. code-block:: console -**Jet, Orion, Gaea:** + "/work/noaa/fv3-cam/UFS_SRW_app/v1p0/model_data" -The settings are the same as for Hera, except that ``"hera"`` should be switched to ``"jet"``, ``"orion"``, or ``"gaea"``, respectively. -For **WCOSS**, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: +On Gaea: + +.. code-block:: console + + "/lustre/f2/pdata/esrl/gsd/ufs/ufs-srw-release-v1.0.0/staged_extrn_mdl_files" + + +For **WCOSS** systems, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: .. code-block:: console MACHINE=”wcoss_cray” or MACHINE=”wcoss_dell_p3” ACCOUNT="my_account" EXPT_SUBDIR="my_expt_name" + USE_USER_STAGED_EXTRN_FILES="TRUE" + +For WCOSS_DELL_P3: + +.. code-block:: console + + EXTRN_MDL_SOURCE_BASEDIR_ICS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/model_data" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/model_data" + +For WCOSS_CRAY: + +.. code-block:: console + + EXTRN_MDL_SOURCE_BASEDIR_ICS="/gpfs/hps3/emc/meso/noscrub/UFS_SRW_App/model_data" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/gpfs/hps3/emc/meso/noscrub/UFS_SRW_App/model_data" **NOAA Cloud Systems:** @@ -630,14 +669,14 @@ The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``regional_workfl +----------------------+------------------------------------------------------------+ | **Workflow Task** | **Task Description** | +======================+============================================================+ - | make_grid | Pre-processing task to generate regional grid files. Can | - | | be run, at most, once per experiment. | + | make_grid | Pre-processing task to generate regional grid files. Only | + | | needs to be run once per experiment. | +----------------------+------------------------------------------------------------+ - | make_orog | Pre-processing task to generate orography files. Can be | - | | run, at most, once per experiment. | + | make_orog | Pre-processing task to generate orography files. Only | + | | needs to be run once per experiment. | +----------------------+------------------------------------------------------------+ | make_sfc_climo | Pre-processing task to generate surface climatology files. | - | | Can be run, at most, once per experiment. | + | | Only needs to be run, at most, once per experiment. | +----------------------+------------------------------------------------------------+ | get_extrn_ics | Cycle-specific task to obtain external data for the | | | initial conditions | diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index eb76b19c10..5576837164 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -19,7 +19,7 @@ These components are documented within this User's Guide and supported through a Pre-processor Utilities and Initial Conditions ============================================== -The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid (``regional_esg_grid/make_hgrid``) along with :term:`orography` (``orog``) and surface climatology (``sfc_climo_gen``) files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of halo cells, additional utilities handle the correct number of halo shave points and topography filtering. The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format. These are needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User’s Guide `_. +The SRW Application includes a number of pre-processing utilities that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), it is necessary to first generate a regional grid (``regional_esg_grid/make_hgrid``) along with :term:`orography` (``orog``) and surface climatology (``sfc_climo_gen``) files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of halo cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software ``chgres_cube`` is used to convert the raw external model data into initial and lateral boundary condition files in netCDF format. These are needed as input to the FV3-LAM. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS User's Guide `_. The SRW Application can be initialized from a range of operational initial condition files. It is possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (:term:`GRIB2`) format. GFS files also come in :term:`NEMSIO` format for past dates. @@ -31,19 +31,18 @@ Forecast Model ============== The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (:term:`LAM`) capability :cite:`BlackEtAl2020`. The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `__. +(:term:`FV3`) dynamical core configured with a Limited Area Model (:term:`LAM`) capability :cite:`BlackEtAl2020`. The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `__. Supported model resolutions in this release include 3-, 13-, and 25-km predefined Contiguous U.S. (:term:`CONUS`) domains, each with 64 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 `here `__ and on the `NOAA Geophysical Fluid Dynamics Laboratory website `_. -Interoperable atmospheric physics, along with the Noah Multi-parameterization (Noah MP) Land Surface Model options, are supported through the Common Community Physics Package (:term:`CCPP`), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are two physics options supported for the release. The first is an experimental physics suite 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. 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. +Interoperable atmospheric physics, along with various land surface model options, are supported through the Common Community Physics Package (:term:`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 options supported for the v2.0 release. The first is an experimental physics suite 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 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. The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal direction and model levels in the vertical direction. Post-processor ============== -The SRW Application is distributed with the Unified Post Processor (:term:`UPP`) included in the workflow as a way to convert the netCDF output on the native model grid to :term:`GRIB2` format on standard isobaric vertical coordinates. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `__. +The SRW Application is distributed with the Unified Post Processor (:term:`UPP`) included in the workflow as a way to convert the netCDF output on the native model grid to :term:`GRIB2` format on standard isobaric vertical coordinates. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `__. Output from UPP can be used with visualization, plotting, and verification packages or in further downstream post-processing (e.g., statistical post-processing techniques). diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 5e2f118cd0..cfda134b60 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -25,17 +25,17 @@ the external model data can be found in :numref:`Section %s `, :numref:`Step %s Generate the Forecast Experiment ` links the input data for the pre-processing utilities from a location on disk to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here `__. +When a user runs the SRW Application as described in the Quick Start Guide :numref:`Chapter %s `, :numref:`Step %s Generate the Forecast Experiment ` links the input data for the pre-processing utilities from a location on disk to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here `__. UFS Weather Model ----------------- The input files for the weather model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix files -must be staged by the user unless you are running on a Level 1/pre-configured platform, in which case you can link to the existing copy of the data on that machine. See :numref:`Section %s ` for more information. The static, grid, and date-specific files are linked in the experiment directory by the workflow scripts. An extensive description of the input files for the weather model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow, as described in :numref:`Section %s `. +must be staged by the user unless you are running on a Level 1/pre-configured platform, in which case you can link to the existing copy of the data on that machine. See :numref:`Section %s ` for more information. The static, grid, and date-specific files are linked in the experiment directory by the workflow scripts. An extensive description of the input files for the weather model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow, as described in :numref:`Section %s `. Unified Post Processor (UPP) ---------------------------- Documentation for the UPP input files can be found in the `UPP User's Guide -`__. +`__. .. _WorkflowTemplates: @@ -96,7 +96,7 @@ and are shown in :numref:`Table %s `. Additional information related to the ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``, ``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, while information on the ``regional_grid.nml`` can be found in the `UFS_UTILS User’s Guide -`_. +`_. Migratory Route of the Input Files in the Workflow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -140,6 +140,9 @@ experiment run directory ``EXPTDIR/YYYYMMDDHH/INPUT`` and consist of the followi These output files are used as inputs for the UFS weather model, and are described in the `Users Guide `__. +.. + COMMENT: Change link above (structure of "latest" is significantly different) + UFS Weather Model ----------------- As mentioned previously, the workflow can be run in ‘community’ or ‘nco’ mode, which determines @@ -156,11 +159,12 @@ In this case, the netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH`` * ``phyfHHH.nc`` Additional details may be found in the UFS Weather Model `Users Guide -`__. +`__. + Unified Post Processor (UPP) ---------------------------- -Documentation for the UPP output files can be found `here `__. +Documentation for the UPP output files can be found `here `__. For the SRW Application, the weather model netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH/postprd`` directory and have the naming convention (file->linked to): @@ -174,7 +178,7 @@ If you wish to modify the fields or levels that are output from the UPP, you wil .. note:: This process requires advanced knowledge of which fields can be output for the UFS Weather Model. -Use the directions in the `UPP User's Guide `__ for details on how to make modifications to the ``fv3lam.xml`` file and for remaking the flat text file that the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default). +Use the directions in the `UPP User's Guide `__ for details on how to make modifications to the ``fv3lam.xml`` file and for remaking the flat text file that the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default). Once you have created the new flat text file reflecting your changes, you will need to modify your ``config.sh`` to point the workflow to the new text file. In your ``config.sh``, set the following: diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index f266640f3d..6905e5a846 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -6,7 +6,7 @@ Introduction The Unified Forecast System (:term:`UFS`) is a community-based, coupled, comprehensive Earth modeling system. NOAA’s operational model suite for numerical weather prediction (:term:`NWP`) is quickly transitioning to the UFS from a number of different modeling systems. The UFS enables research, development, and contribution opportunities within the broader :term:`weather enterprise` (e.g. government, industry, and academia). For more information about the UFS, visit the `UFS Portal `__. -The UFS includes `multiple applications `__ that support different forecast durations and spatial domains. This documentation describes the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes to several days. The SRW Application v1.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. New and improved capabilities for this release include the addition of a verification package (MetPLUS) for both deterministic and ensemble simulations and support for four Stochastically Perturbed Perturbation (SPP) schemes. Future work will expand the capabilities of the application to include data assimilation (DA) and a forecast restart/cycling capability. +The UFS includes `multiple applications `__ that support different forecast durations and spatial domains. This documentation describes the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes to several days. The SRW Application v2.0 release includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within this User's Guide and supported through a `community forum `_. New and improved capabilities for this release include the addition of a verification package (METplus) for both deterministic and ensemble simulations and support for four Stochastically Perturbed Perturbation (SPP) schemes. Future work will expand the capabilities of the application to include data assimilation (DA) and a forecast restart/cycling capability. This documentation provides a :ref:`Quick Start Guide ` for running the SRW Application in a container and a :ref:`detailed guide ` for running the SRW App on supported platforms. It also provides an overview of the :ref:`release components ` and details on how to customize or modify different portions of the workflow. @@ -61,7 +61,7 @@ The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Common Community Physics Package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and land surface model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW App release includes an experimental physics version and an updated operational version. +The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and land surface model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW App release includes an four physics suites. Data Format ^^^^^^^^^^^^^^^^^^^^^^ @@ -336,13 +336,13 @@ A list of available documentation is shown in :numref:`Table %s ` | @@ -360,9 +360,9 @@ A list of available documentation is shown in :numref:`Table %s ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW App. +This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via container reduces this variability and allows for a smoother SRW App build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW App. -The "out-of-the-box" SRW App case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. +The "out-of-the-box" SRW App case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: @@ -121,7 +121,7 @@ From the ``ufs-srweather-app`` directory, ``cd`` into the build directory and ru Download and Stage the Data ============================ -The SRW App requires input files to run. These include static datasets, initial and boundary condition files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW App tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. +The SRW App requires input files to run. These include static datasets, initial and boundary condition files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW App tests are already available, as long as the ``--bind`` command in :numref:`Step %s ` included the directory with the data. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. .. _GenerateForecastC: @@ -130,7 +130,7 @@ Generate the Forecast Experiment To generate the forecast experiment, users must: #. :ref:`Set experiment parameters ` -#. :ref:`Set Python and other environment parameters ` +#. :ref:`Set Python and other environment parameters to activate the regional workflow ` #. :ref:`Run a script to generate the experiment workflow ` The first two steps depend on the platform being used and are described here for each Level 1 platform. Users will need to adjust the instructions to their machine if they are working on a Level 2-4 platform. @@ -148,7 +148,7 @@ Make a copy of ``config.community.sh`` to get started. From the ``ufs-srweather- cd regional_workflow/ush cp config.community.sh config.sh -The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v15.2 physics suite (FV3_GFS_v15p2 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. +The default settings in this file include a predefined 25-km :term:`CONUS` grid (RRFS_CONUS_25km), the :term:`GFS` v16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. Next, edit the new ``config.sh`` file to customize it for your experiment. At a minimum, update the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``: @@ -285,7 +285,7 @@ Check the batch script output file in your experiment directory for a “SUCCESS .. table:: List of tasks in the regional workflow in the order that they are executed. Scripts with the same stage number may be run simultaneously. The number of processors and wall clock time is a good starting point for Cheyenne or Hera - when running a 48-h forecast on the 25-km CONUS domain. + when running a 48-h forecast on the 25-km CONUS domain. For a brief description of tasks, see :numref:`Table %s `. +------------+------------------------+----------------+----------------------------+ | **Stage/** | **Task Run Script** | **Number of** | **Wall clock time (H:MM)** | @@ -313,7 +313,6 @@ Check the batch script output file in your experiment directory for a “SUCCESS | | | | forecast hour) | +------------+------------------------+----------------+----------------------------+ - .. hint:: If any of the scripts return an error that "Primary job terminated normally, but one process returned a non-zero exit code," there may not be enough space on one node to run the process. On an HPC system, the user will need to allocate a(nother) compute node. The process for doing so is system-dependent, and users should check the documentation available for their HPC system. Instructions for allocating a compute node on NOAA Cloud systems can be viewed in the :numref:`Step %s ` as an example. From 173b8380fd1e01b04f12dfbcd8990d9c6a8ce33b Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 29 Mar 2022 10:43:38 -0400 Subject: [PATCH 070/158] update QS intro --- docs/UsersGuide/source/Quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index bf94555a6f..8485ce1d2a 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -4,7 +4,7 @@ Container-Based Quick Start Guide ==================================== -This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via container reduces this variability and allows for a smoother SRW App build and run experience. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability, particularly if they already have experience running the SRW App. +This Quick Start Guide will help users to build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a `Singularity `__ :term:`container`. The container approach provides a uniform enviroment in which to build and run the SRW App. Normally, the details of building and running the SRW App vary from system to system due to the many possible combinations of operating systems, compilers, :term:`MPI`’s, and package versions available. Installation via Singularity container reduces this variability and allows for a smoother SRW App build experience. However, the container is not compatible with the `Rocoto workflow manager `__, so users must run each task in the workflow manually. Additionally, the Singularity container can only run on a single compute node, which makes the container-based approach inadequate for large experiments. It is an excellent starting point for running the "out-of-the-box" SRW App case and other small experiments. However, the :ref:`non-container approach ` may be more appropriate for those users who desire additional customizability or more compute power, particularly if they already have experience running the SRW App. The "out-of-the-box" SRW App case described in this User's Guide builds a weather forecast for June 15-16, 2019. Multiple convective weather events during these two days produced over 200 filtered storm reports. Severe weather was clustered in two areas: the Upper Midwest through the Ohio Valley and the Southern Great Plains. This forecast uses a predefined 25-km Continental United States (:term:`CONUS`) grid (RRFS_CONUS_25km), the Global Forecast System (:term:`GFS`) version 16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. From 09581c810e0fc6322981cf9a85764e56cb347cee Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 29 Mar 2022 12:11:27 -0400 Subject: [PATCH 071/158] fix minor physics details --- docs/UsersGuide/source/Components.rst | 2 +- docs/UsersGuide/source/Introduction.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index 5576837164..e92d8c922e 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 64 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 `here `__ 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 (:term:`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 options supported for the v2.0 release. The first is an experimental physics suite 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 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. +Interoperable atmospheric physics, along with various land surface model options, are supported through the Common Community Physics Package (:term:`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 options supported for the v2.0 release. The first is a physics suite 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 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. The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal direction and model levels in the vertical direction. diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 6905e5a846..03d3dff1f5 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -61,7 +61,7 @@ The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Common Community Physics Package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and land surface model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The SRW App release includes an four physics suites. +The `Common Community Physics Package `_ (:term:`CCPP`) supports interoperable atmospheric physics and land surface model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. The upcoming SRW App release includes four physics suites. Data Format ^^^^^^^^^^^^^^^^^^^^^^ From a714d43581caaa774339e3c7f3066a63631e7014 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 29 Mar 2022 12:44:27 -0400 Subject: [PATCH 072/158] update citation and physics suite name --- docs/UsersGuide/source/Components.rst | 4 ++-- docs/UsersGuide/source/Introduction.rst | 2 +- docs/UsersGuide/source/references.bib | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index e92d8c922e..f2f17c149a 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -31,11 +31,11 @@ Forecast Model ============== The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (:term:`LAM`) capability :cite:`BlackEtAl2020`. The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `__. +(:term:`FV3`) dynamical core configured with a Limited Area Model (:term:`LAM`) capability :cite:`BlackEtAl2021`. The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` is `here `__. Supported model resolutions in this release include 3-, 13-, and 25-km predefined Contiguous U.S. (:term:`CONUS`) domains, each with 64 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 `here `__ 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 (:term:`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 options supported for the v2.0 release. The first is a physics suite 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 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. +Interoperable atmospheric physics, along with various land surface model options, are supported through the Common Community Physics Package (:term:`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 options supported for the v2.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 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. The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal direction and model levels in the vertical direction. diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 03d3dff1f5..91473c9f7a 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -56,7 +56,7 @@ Atmospheric Model ^^^^^^^^^^^^^^^^^^^^^^ The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Cubed-Sphere -(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability (:cite:t:`BlackEtAl2020`). The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. +(:term:`FV3`) dynamical core configured with a Limited Area Model (LAM) capability (:cite:t:`BlackEtAl2021`). The dynamical core is the computational part of a model that solves the equations of fluid motion. A User’s Guide for the UFS :term:`Weather Model` can be found `here `__. Common Community Physics Package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/UsersGuide/source/references.bib b/docs/UsersGuide/source/references.bib index 984bff6f8a..836b246d10 100644 --- a/docs/UsersGuide/source/references.bib +++ b/docs/UsersGuide/source/references.bib @@ -1,6 +1,6 @@ -@article{BlackEtAl2020, - title={A Limited Area Modeling Capability for the Finite-Volume Cubed-Sphere (FV3) Dynamical Core}, +@article{BlackEtAl2021, + title={A limited area modeling capability for the finite-volume cubed-sphere (fv3) dynamical core}, author={T.L. Black and J.A. Abeles and B.T. Blake and D. Jovic and E. Rogers and X. Zhang and E.A. Aligo and L.C. Dawson and Y. Lin and E. Strobach and P.C. Shafran, and J.R. Carley}, - journal={Monthly Weather Review}, - year={Submitted}, + journal={AGU Journal of Advances in Earth Modeling Systems}, + year={2021}, } From 4757b40c307fce66d796dd3d6c91965b7ef30c18 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 29 Mar 2022 15:48:18 -0400 Subject: [PATCH 073/158] add compute node allocation info to QS --- docs/UsersGuide/source/Quickstart.rst | 23 ++++++++++++++++++++++- docs/UsersGuide/source/conf.py | 2 +- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 8485ce1d2a..23c3f0aeea 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -61,7 +61,28 @@ On HPC systems (including NOAA's Cloud platforms), allocate a compute node on wh The third command will output a hostname. Replace ```` in the last command with the output from the third command. After "ssh-ing" to the compute node in the last command, build and run the SRW App from that node. -The appropriate commands on other Level 1 platforms will vary, and users should consult the documentation for those platforms. +The appropriate commands on other Level 1 platforms will vary, and users should consult the `documentation `__ for those platforms. In general, the allocation command will follow one of these two patterns depending on whether the system uses the Slurm or PBS resource manager respectively: + +.. code-block:: console + + salloc -N 1 -n -A -t + module load met/<10.0.0> -Then, the path to the MET and METplus directories must be set: +Then, the path to the MET and METplus directories must be added to ``config.sh``: .. code-block:: console - METPLUS_PATH="/contrib/METplus/METplus-4.1.0" - MET_INSTALL_DIR="/contrib/met/10.1.0" + METPLUS_PATH="" + MET_INSTALL_DIR="" -Users who have already staged the METplus verification data (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data and set the corresponding ``RUN_TASK_GET_OBS_*`` parameters to "FALSE". +Users who have already staged the METplus verification data (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data and set the corresponding ``RUN_TASK_GET_OBS_*`` parameters to "FALSE" in ``config.sh``. .. code-block:: console @@ -647,7 +660,7 @@ If users have access to NOAA HPSS but have not pre-staged the data, they can sim Users who do not have access to NOAA HPSS and do not have the data on their system will need to download :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data manually from collections of publicly available data, such as the ones listed `here `__. -Next, the verification tasks must be turned on according to the user's needs: +Next, the verification tasks must be turned on according to the user's needs. Users should add the some or all of the following tasks to ``config.sh``, depending on the verification procedure(s) they have in mind: .. code-block:: console @@ -656,7 +669,7 @@ Next, the verification tasks must be turned on according to the user's needs: RUN_TASK_VX_ENSGRID="TRUE" RUN_TASK_VX_ENSPOINT="TRUE" -These tasks are independent, so users may set some values to "TRUE" and others to "FALSE" depending on the needs of their experiment. Note that the ENSGRID and ENSPOINT tasks apply only to ensemble model verification. More details on all of the parameters in this section are available in :numref:`Chapter %s `. +These tasks are independent, so users may set some values to "TRUE" and others to "FALSE" depending on the needs of their experiment. Note that the ENSGRID and ENSPOINT tasks apply only to ensemble model verification. Additional verification tasks appear in :numref:`Table %s ` More details on all of the parameters in this section are available in :numref:`Chapter %s `. .. _SetUpPythonEnv: @@ -770,114 +783,114 @@ In addition to the baseline tasks described in :numref:`Table %s `__) verification system has been integrated into the SRW App to facilitate forecast evaluation. METplus is a verification framework that spans a wide range of temporal (warn-on-forecast to climate) and spatial (storm to global) scales. It is supported via the `Developmental Testbed Center (DTC) `__. +The enhanced Model Evaluation Tools (`METplus `__) verification system has been integrated into the SRW App to facilitate forecast evaluation. METplus is a verification framework that spans a wide range of temporal scales (warn-on-forecast to climate) and spatial scales (storm to global). It is supported by the `Developmental Testbed Center (DTC) `__. -The core components of the framework include the statistical driver, MET, the associated database and display systems known as METviewer and METexpress, and a suite of Python wrappers to provide low-level automation and examples, also called use-cases. MET is a set of verification tools developed for use by the :term:`NWP` community. It matches up grids with either gridded analyses or point observations and applies configurable methods to compute statistics and diagnostics. Extensive documentation is available in the `METplus User’s Guide `__ and `MET User’s Guide `__, along with documentation for all other components of the framework found at the Documentation link for each component on the METplus `downloads `__ page. +METplus is preinstalled on all `Level 1 `__ systems; existing builds can be viewed `here `__. METplus can be installed on other systems individually or as part of :term:`HPC-Stack`. Users on non-Level 1 systems can follow the `MET Installation `__ and `METplus Installation `__ Guides for individual installation. Currently, METplus *installation* is not a supported feature for this release of the SRW App. However, METplus *use* is supported on systems with a functioning METplus installation. -Among other techniques, MET provides the capability to compute standard verification scores for comparing deterministic gridded model data to point-based and gridded observations, along with ensemble and probabilistic verification methods for comparing gridded model data to point-based or gridded observations. Verification tasks to accomplish these comparisons are defined in the SRW App. Currently, the SRW App supports the use of NDAS observation files in prepBUFR format (which include conventional point-based surface and upper-air data) for point-based verification, gridded Climatology-Calibrated Precipitation Analysis (CCPA) data for accumulated precipitation evaluation, and Multi-Radar/Multi-Sensor (MRMS) gridded analysis data for composite reflectivity and echo top verification. +The core components of the METplus framework include the statistical driver, MET, the associated database and display systems known as METviewer and METexpress, and a suite of Python wrappers to provide low-level automation and examples, also called use-cases. MET is a set of verification tools developed for use by the :term:`NWP` community. It matches up grids with either gridded analyses or point observations and applies configurable methods to compute statistics and diagnostics. Extensive documentation is available in the `METplus User’s Guide `__ and `MET User’s Guide `__. Documentation for all other components of the framework can be found at the Documentation link for each component on the METplus `downloads `__ page. -METplus is being actively developed by :term:`NCAR`/Research Applications Laboratory (RAL), NOAA/Earth Systems Research Laboratories (ESRL), NOAA/Environmental Modeling Center (EMC), and is open to community contributions. +Among other techniques, MET provides the capability to compute standard verification scores for comparing deterministic gridded model data to point-based and gridded observations. It also provides ensemble and probabilistic verification methods for comparing gridded model data to point-based or gridded observations. Verification tasks to accomplish these comparisons are defined in the SRW App in :numref:`Table %s `. Currently, the SRW App supports the use of :term:`NDAS` observation files in `prepBUFR format `__ (which include conventional point-based surface and upper-air data) for point-based verification. It also supports gridded Climatology-Calibrated Precipitation Analysis (:term:`CCPA`) data for accumulated precipitation evaluation and Multi-Radar/Multi-Sensor (:term:`MRMS`) gridded analysis data for composite reflectivity and :term:`echo top` verification. + +METplus is being actively developed by :term:`NCAR`/Research Applications Laboratory (RAL), NOAA/Earth Systems Research Laboratories (ESRL), and NOAA/Environmental Modeling Center (EMC), and it is open to community contributions. Visualization Example diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index 17194c6b6f..0a8e0dd7db 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -295,7 +295,7 @@ METplus Parameters Path to top-level directory of METplus installation. ``MET_BIN_EXEC``: (Default: "bin") - Name of the directory where the METplus executable is installed. + Location where METplus executables are installed. .. _METParamNote: diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index de5bd4ab3a..135b2c2a5e 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -46,6 +46,9 @@ Glossary dynamical core Global atmospheric model based on fluid dynamics principles, including Euler's equations of motion. + echo top + The radar-indicated top of an area of precipitation. Specifically, it contains the height of the 18 dBZ reflectivity value. + EPIC EPIC stands for the `Earth Prediction Innovation Center `__. EPIC seeks to accelerate scientific research and modeling contributions through continuous and sustained community engagement to produce the most accurate and reliable operational modeling system in the world. @@ -55,7 +58,7 @@ Glossary FV3 The Finite-Volume Cubed-Sphere dynamical core (dycore). Developed at NOAA's Geophysical Fluid Dynamics Laboratory (GFDL), it is a scalable and flexible dycore capable of both - hydrostatic and non-hydrostatic atmospheric simulations. It is the dycore used in the + hydrostatic and non-hydrostatic atmospheric simulations. It is the dycore used in the UFS Weather Model. FVCOM @@ -120,7 +123,7 @@ Glossary visualization. Stands for NCAR Command Language. More information can be found at https://www.ncl.ucar.edu. NDAS - :term:`NAM` Data Assimilation System (NDAS) data. This data is required for use of the METplus verification suite within the SRW App. The most recent 1-2 days worth of data are publicly available in PrepBufr format and can be accessed `here `__. + :term:`NAM` Data Assimilation System (NDAS) data. This data is required for use of the METplus verification suite within the SRW App. The most recent 1-2 days worth of data are publicly available in PrepBufr format and can be accessed `here `__. The most recent 8 days of data can be accessed `here `__. NEMS The NOAA Environmental Modeling System is a common modeling framework whose purpose is diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 0a5a39f08b..96aa65c1d2 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -77,7 +77,7 @@ The `Unified Post Processor ` and on the `METplus website `__. +The Model Evaluation Tools (MET) package is a set of statistical verification tools developed by the `Developmental Testbed Center `__ (DTC) for use by the :term:`NWP` community to help them assess and evaluate the performance of numerical weather predictions. MET is the core component of the unified METplus verification framework. The suite also includes the associated database and display systems called METviewer and METexpress. METplus spans a wide range of temporal and spatial scales. It is intended to be extensible through additional capabilities developed by the community. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. Visualization Example ------------------------- From 676a3512a91cf736e0d007aaf1b374378987852a Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 28 Apr 2022 17:48:37 -0400 Subject: [PATCH 115/158] add workflow svg diagram --- docs/UsersGuide/source/BuildRunSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 046f7c87a0..566a50b015 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -734,7 +734,7 @@ Description of Workflow Tasks .. _WorkflowTasksFig: -.. figure:: _static/FV3LAM_wflow_flowchart.png +.. figure:: _static/FV3LAM_wflow_flowchart_v2.svg *Flowchart of the workflow tasks* From 41527b7178aa4f53b80f018b3305388fdacb7c78 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 28 Apr 2022 18:45:09 -0400 Subject: [PATCH 116/158] edits to rocoto ch --- docs/UsersGuide/source/RocotoInfo.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/UsersGuide/source/RocotoInfo.rst b/docs/UsersGuide/source/RocotoInfo.rst index 03d13571cb..60d972413b 100644 --- a/docs/UsersGuide/source/RocotoInfo.rst +++ b/docs/UsersGuide/source/RocotoInfo.rst @@ -4,9 +4,9 @@ Additional Rocoto Information ============================= The tasks in the SRW Application (:numref:`Table %s `) are typically run using -the Rocoto Workflow Manager. Rocoto is a Ruby program that interfaces with the batch system on an +the Rocoto Workflow Manager. Rocoto is a Ruby program that communicates with the batch system on an 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 +system as the task dependencies allow and runs one instance of the workflow for a set of user-defined cycles. More information on Rocoto can be found at https://github.com/christopherwharrop/rocoto/wiki/documentation. The SRW App workflow is defined in a Jinja-enabled Rocoto XML template called ``FV3LAM_wflow.xml``, @@ -17,11 +17,11 @@ and task interdependencies. The generated XML file is then copied to the experi ``$EXPTDIR/FV3LAM_wflow.xml``. There are a number of Rocoto commands available to run and monitor the workflow and can be found in the -complete `Rocoto documentation `_. +complete `Rocoto documentation `__. Descriptions and examples of commonly used commands are discussed below. rocotorun -========= +========== The ``rocotorun`` command is used to run the workflow by submitting tasks to the batch system. It will automatically resubmit failed tasks and can recover from system outages without user intervention. An example is: @@ -58,7 +58,7 @@ the workflow from scratch, both database files can be deleted, and the workflow or the launch script ``launch_FV3LAM_wflow.sh`` (executed multiple times as described above). rocotostat -========== +=========== ``rocotostat`` is a tool for querying the status of tasks in an active Rocoto workflow. Once the workflow has been started with the ``rocotorun`` command, Rocoto can also check the status of the workflow using the ``rocotostat`` command: @@ -129,7 +129,7 @@ messages. Optional arguments for the ``rocotostat`` command can be found at htt .. _rocotocheck: rocotocheck -=========== +============ Sometimes, issuing a ``rocotorun`` command will not cause the next task to launch. ``rocotocheck`` is a tool that can be used to query detailed information about a task or cycle in the Rocoto workflow. To determine the cause of a particular task not being submitted, the ``rocotocheck`` command can be used @@ -201,7 +201,7 @@ have been met. If not, the dependencies section in the output of ``rocotocheck` dependency "is NOT satisfied". rocotorewind -============ +============= ``rocotorewind`` is a tool that attempts to undo the effects of running a task and is commonly used to rerun part of a workflow that has failed. If a task fails to run (the STATE is DEAD), and needs to be restarted, the ``rocotorewind`` command will rerun tasks in the workflow. The command line options are the same as those described in the ``rocotocheck`` @@ -222,7 +222,7 @@ command to rerun the forecast task from ``$EXPTDIR`` is: rocotorewind -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201907010000 -t run_fcst rocotoboot -========== +=========== ``rocotoboot`` will force a specific task of a cycle in a Rocoto workflow to run. All dependencies and throttle limits are ignored, and it is generally recommended to use ``rocotorewind`` instead. An example of how to use this command to rerun the ``make_ics`` task from ``$EXPTDIR`` is: From 0591d602470277d841217484ac3f7995f7ec2a3a Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 29 Apr 2022 16:29:09 -0400 Subject: [PATCH 117/158] updates to Rocoto chapter --- docs/UsersGuide/source/BuildRunSRW.rst | 5 +- docs/UsersGuide/source/Components.rst | 6 +- docs/UsersGuide/source/ConfigWorkflow.rst | 2 + docs/UsersGuide/source/RocotoInfo.rst | 187 +++++++++++----------- docs/UsersGuide/source/index.rst | 2 +- 5 files changed, 102 insertions(+), 100 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 566a50b015..34524b3fe5 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -897,14 +897,15 @@ In addition to the baseline tasks described in :numref:`Table %s `. There are two main ways to run the workflow with Rocoto: (1) with the ``launch_FV3LAM_wflow.sh`` script, and (2) by manually calling the ``rocotorun`` command. Users can also automate the workflow using a crontab. +.. note:: + Users may find it helpful to review :numref:`Chapter %s ` to gain a better understanding of Rocoto commands and workflow management before continuing, but this is not required to run the experiment. + Optionally, an environment variable can be set to navigate to the ``$EXPTDIR`` more easily. If the login shell is bash, it can be set as follows: .. code-block:: console diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index ab537a81a3..dc28411aca 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -74,14 +74,12 @@ After running ``manage_externals/checkout_externals``, the visualization scripts Build System and Workflow ========================= -The SRW Application has a portable build system and a user-friendly, modular, and -expandable workflow framework. +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. 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 `Rocoto documentation -`_). 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, whether to run some or all of the pre-processing, forecast model, and post-processing steps. +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. 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, whether to run some or all of the pre-processing, forecast model, and post-processing steps. This SRW Application release has been tested on a variety of platforms widely used by researchers, such as the NOAA Research and Development High-Performance Computing Systems diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index 0a8e0dd7db..e7109af658 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -869,6 +869,8 @@ Debug Parameter ``DEBUG``: (Default: "FALSE") Flag that determines whether to print out very detailed debugging messages. Note that if DEBUG is set to TRUE, then VERBOSE will also get reset to TRUE if it isn't already. Valid values: "TRUE" "true" "YES" "yes" "FALSE" "false" "NO" "no" +.. _WFTasks: + Rocoto Workflow Tasks ======================== diff --git a/docs/UsersGuide/source/RocotoInfo.rst b/docs/UsersGuide/source/RocotoInfo.rst index 60d972413b..97177e4029 100644 --- a/docs/UsersGuide/source/RocotoInfo.rst +++ b/docs/UsersGuide/source/RocotoInfo.rst @@ -10,25 +10,24 @@ system as the task dependencies allow and runs one instance of the workflow for cycles. More information on Rocoto can be found at https://github.com/christopherwharrop/rocoto/wiki/documentation. The SRW App workflow is defined in a Jinja-enabled Rocoto XML template called ``FV3LAM_wflow.xml``, -which resides in the ``regional_workflow/ufs/templates`` directory. When the ``generate_FV3LAM_wflow.sh`` +which resides in the ``regional_workflow/ufs/templates`` directory. When the ``generate_FV3LAM_wflow.sh`` script is run, the ``fill_jinja_template.py`` script is called, and the parameters in the template file are filled in. The completed file contains the workflow task names, parameters needed by the job scheduler, -and task interdependencies. The generated XML file is then copied to the experiment directory: +and task interdependencies. The generated XML file is then copied to the experiment directory: ``$EXPTDIR/FV3LAM_wflow.xml``. -There are a number of Rocoto commands available to run and monitor the workflow and can be found in the +There are a number of Rocoto commands available to run and monitor the workflow; users can find more information in the complete `Rocoto documentation `__. Descriptions and examples of commonly used commands are discussed below. rocotorun ========== The ``rocotorun`` command is used to run the workflow by submitting tasks to the batch system. It will -automatically resubmit failed tasks and can recover from system outages without user intervention. -An example is: +automatically resubmit failed tasks and can recover from system outages without user intervention. An example is: .. code-block:: console - rocotorun -w /path/to/workflow/xml/file -d /path/to/workflow/database/file -v 10 + rocotorun -w -d -v 10 where @@ -45,17 +44,17 @@ From the ``$EXPTDIR`` directory, the ``rocotorun`` command for the workflow woul rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db It is important to note that the ``rocotorun`` process is iterative; the command must be executed -many times before the entire workflow is completed, usually every 2-10 minutes. This command can be -placed in the user’s crontab and cron will call it with a specified frequency. More information on +many times before the entire workflow is completed, usually every 1-10 minutes. This command can be +placed in the user’s crontab, and cron will call it with a specified frequency. More information on this command can be found at https://github.com/christopherwharrop/rocoto/wiki/documentation. The first time the ``rocotorun`` command is executed for a workflow, the files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are created. There is usually no need for the user to modify these files. Each time this command is executed, the last known state of the workflow is read from the ``FV3LAM_wflow.db`` file, the batch system is queried, jobs are submitted for tasks whose dependencies have been satisfied, -and the current state of the workflow is saved in ``FV3LAM_wflow.db``. If there is a need to relaunch +and the current state of the workflow is saved in ``FV3LAM_wflow.db``. If there is a need to relaunch the workflow from scratch, both database files can be deleted, and the workflow can be run using ``rocotorun`` -or the launch script ``launch_FV3LAM_wflow.sh`` (executed multiple times as described above). +or the launch script ``launch_FV3LAM_wflow.sh`` (executed multiple times). rocotostat =========== @@ -65,38 +64,38 @@ workflow using the ``rocotostat`` command: .. code-block:: console - rocotostat -w /path/to/workflow/xml/file -d /path/to/workflow/database/file + rocotostat -w -d Executing this command will generate a workflow status table similar to the following: .. code-block:: console - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION ============================================================================================================================= - 201907010000 make_grid 175805 QUEUED - 0 0.0 - 201907010000 make_orog - - - - - - 201907010000 make_sfc_climo - - - - - - 201907010000 get_extrn_ics druby://hfe01:36261 SUBMITTING - 0 0.0 - 201907010000 get_extrn_lbcs druby://hfe01:36261 SUBMITTING - 0 0.0 - 201907010000 make_ics - - - - - - 201907010000 make_lbcs - - - - - - 201907010000 run_fcst - - - - - - 201907010000 run_post_f000 - - - - - - 201907010000 run_post_f001 - - - - - - 201907010000 run_post_f002 - - - - - - 201907010000 run_post_f003 - - - - - - 201907010000 run_post_f004 - - - - - - 201907010000 run_post_f005 - - - - - - 201907010000 run_post_f006 - - - - - + 201907010000 make_grid 175805 QUEUED - 0 0.0 + 201907010000 make_orog - - - - - + 201907010000 make_sfc_climo - - - - - + 201907010000 get_extrn_ics druby://hfe01:36261 SUBMITTING - 0 0.0 + 201907010000 get_extrn_lbcs druby://hfe01:36261 SUBMITTING - 0 0.0 + 201907010000 make_ics - - - - - + 201907010000 make_lbcs - - - - - + 201907010000 run_fcst - - - - - + 201907010000 run_post_f000 - - - - - + 201907010000 run_post_f001 - - - - - + 201907010000 run_post_f002 - - - - - + 201907010000 run_post_f003 - - - - - + 201907010000 run_post_f004 - - - - - + 201907010000 run_post_f005 - - - - - + 201907010000 run_post_f006 - - - - - This table indicates that the ``make_grid`` task was sent to the batch system and is now queued, while the ``get_extrn_ics`` and ``get_extrn_lbcs`` tasks for the ``201907010000`` cycle are in the process of being submitted to the batch system. Note that issuing a ``rocotostat`` command without an intervening ``rocotorun`` command will not result in an -updated workflow status table; it will print out the same table. It is the ``rocotorun`` command that updates -the workflow database file (in this case ``FV3LAM_wflow.db``, located in ``$EXPTDIR``); the ``rocotostat`` command -reads the database file and prints the table to the screen. To see an updated table, the ``rocotorun`` command +updated workflow status table; it will print out the same table. It is the ``rocotorun`` command that updates +the workflow database file (in this case ``FV3LAM_wflow.db``, located in ``$EXPTDIR``). The ``rocotostat`` command +reads the database file and prints the table to the screen. To see an updated table, the ``rocotorun`` command must be executed followed by the ``rocotostat`` command. After issuing the ``rocotorun`` command several times (over the course of several minutes or longer, depending @@ -104,45 +103,47 @@ on your grid size and computational resources), the output of the ``rocotostat`` .. code-block:: console - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION ============================================================================================================================ - 201907010000 make_grid 175805 SUCCEEDED 0 1 10.0 - 201907010000 make_orog 175810 SUCCEEDED 0 1 27.0 - 201907010000 make_sfc_climo 175822 SUCCEEDED 0 1 38.0 - 201907010000 get_extrn_ics 175806 SUCCEEDED 0 1 37.0 - 201907010000 get_extrn_lbcs 175807 SUCCEEDED 0 1 53.0 - 201907010000 make_ics 175825 SUCCEEDED 0 1 99.0 - 201907010000 make_lbcs 175826 SUCCEEDED 0 1 90.0 - 201907010000 run_fcst 175937 RUNNING - 0 0.0 - 201907010000 run_post_f000 - - - - - - 201907010000 run_post_f001 - - - - - - 201907010000 run_post_f002 - - - - - - 201907010000 run_post_f003 - - - - - - 201907010000 run_post_f004 - - - - - - 201907010000 run_post_f005 - - - - - - 201907010000 run_post_f006 - - - - - - -When the workflow runs to completion, all tasks will be marked as SUCCEEDED. The log files from the tasks + 201907010000 make_grid 175805 SUCCEEDED 0 1 10.0 + 201907010000 make_orog 175810 SUCCEEDED 0 1 27.0 + 201907010000 make_sfc_climo 175822 SUCCEEDED 0 1 38.0 + 201907010000 get_extrn_ics 175806 SUCCEEDED 0 1 37.0 + 201907010000 get_extrn_lbcs 175807 SUCCEEDED 0 1 53.0 + 201907010000 make_ics 175825 SUCCEEDED 0 1 99.0 + 201907010000 make_lbcs 175826 SUCCEEDED 0 1 90.0 + 201907010000 run_fcst 175937 RUNNING - 0 0.0 + 201907010000 run_post_f000 - - - - - + 201907010000 run_post_f001 - - - - - + 201907010000 run_post_f002 - - - - - + 201907010000 run_post_f003 - - - - - + 201907010000 run_post_f004 - - - - - + 201907010000 run_post_f005 - - - - - + 201907010000 run_post_f006 - - - - - + +When the workflow runs to completion, all tasks will be marked as SUCCEEDED. The log files from the tasks are located in ``$EXPTDIR/log``. If any tasks fail, the corresponding log file can be checked for error -messages. Optional arguments for the ``rocotostat`` command can be found at https://github.com/christopherwharrop/rocoto/wiki/documentation. +messages. Optional arguments for the ``rocotostat`` command can be found at https://github.com/christopherwharrop/rocoto/wiki/documentation. .. _rocotocheck: rocotocheck ============ -Sometimes, issuing a ``rocotorun`` command will not cause the next task to launch. ``rocotocheck`` is a -tool that can be used to query detailed information about a task or cycle in the Rocoto workflow. To +Sometimes, issuing a ``rocotorun`` command will not cause the next task to launch. ``rocotocheck`` is a +tool that can be used to query detailed information about a task or cycle in the Rocoto workflow. To determine the cause of a particular task not being submitted, the ``rocotocheck`` command can be used from the ``$EXPTDIR`` directory as follows: .. code-block:: console - rocotocheck -w /path/to/workflow/xml/file -d /path/to/workflow/database/ file -c YYYYMMDDHHMM -t taskname + rocotocheck -w -d file -c -t where -* ``-c`` is the cycle to query -* ``-t`` is the task name +* ``-c`` is the cycle to query in YYYYMMDDHHmm format +* ``-t`` is the task name (see default task names in :numref:`Chapter %s `) + +The cycle and task names appear in the first and second columns of the table output by ``rocotostat``. A specific example is: @@ -150,71 +151,71 @@ A specific example is: rocotocheck -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201907010000 -t run_fcst -This will result in output similar to the following: +Running ``rocotocheck`` will result in output similar to the following: .. code-block:: console :emphasize-lines: 8,19,34 Task: run_fcst - account: gsd-fv3 - command: /scratch2/BMC/det/$USER/ufs-srweather-app/regional_workflow/ush/load_modules_run_task.sh "run_fcst" "/scratch2/BMC/det/$USER/ufs-srweather-app/regional_workflow/jobs/JREGIONAL_RUN_FCST" - cores: 24 - final: false - jobname: run_FV3 - join: /scratch2/BMC/det/$USER/expt_dirs/test_community/log/run_fcst_2019070100.log - maxtries: 3 - name: run_fcst - nodes: 1:ppn=24 - queue: batch - throttle: 9999999 - walltime: 04:30:00 - environment - CDATE ==> 2019070100 - CYCLE_DIR ==> /scratch2/BMC/det/$USER/UFS_CAM/expt_dirs/test_community/2019070100 - PDY ==> 20190701 - SCRIPT_VAR_DEFNS_FP ==> /scratch2/BMC/det/$USER/expt_dirs/test_community/var_defns.sh - dependencies - AND is satisfied - make_ICS_surf_LBC0 of cycle 201907010000 is SUCCEEDED - make_LBC1_to_LBCN of cycle 201907010000 is SUCCEEDED + account: gsd-fv3 + command: /scratch2/BMC/det/$USER/ufs-srweather-app/regional_workflow/ush/load_modules_run_task.sh "run_fcst" "/scratch2/BMC/det/$USER/ufs-srweather-app/regional_workflow/jobs/JREGIONAL_RUN_FCST" + cores: 24 + final: false + jobname: run_FV3 + join: /scratch2/BMC/det/$USER/expt_dirs/test_community/log/run_fcst_2019070100.log + maxtries: 3 + name: run_fcst + nodes: 1:ppn=24 + queue: batch + throttle: 9999999 + walltime: 04:30:00 + environment + CDATE ==> 2019070100 + CYCLE_DIR ==> /scratch2/BMC/det/$USER/UFS_CAM/expt_dirs/test_community/2019070100 + PDY ==> 20190701 + SCRIPT_VAR_DEFNS_FP ==> /scratch2/BMC/det/$USER/expt_dirs/test_community/var_defns.sh + dependencies + AND is satisfied + make_ICS_surf_LBC0 of cycle 201907010000 is SUCCEEDED + make_LBC1_to_LBCN of cycle 201907010000 is SUCCEEDED Cycle: 201907010000 - Valid for this task: YES - State: active - Activated: 2019-10-29 18:13:10 UTC - Completed: - - Expired: - + Valid for this task: YES + State: active + Activated: 2019-10-29 18:13:10 UTC + Completed: - + Expired: - Job: 513615 - State: DEAD (FAILED) - Exit Status: 1 - Tries: 3 - Unknown count: 0 - Duration: 58.0 + State: DEAD (FAILED) + Exit Status: 1 + Tries: 3 + Unknown count: 0 + Duration: 58.0 This shows that although all dependencies for this task are satisfied (see the dependencies section, highlighted above), it cannot run because its ``maxtries`` value (highlighted) is 3. Rocoto will attempt to launch it at most 3 times, and it has already been tried 3 times (the ``Tries`` value, also highlighted). The output of the ``rocotocheck`` command is often useful in determining whether the dependencies for a given task -have been met. If not, the dependencies section in the output of ``rocotocheck`` will indicate this by stating that a +have been met. If not, the dependencies section in the output of ``rocotocheck`` will indicate this by stating that a dependency "is NOT satisfied". rocotorewind ============= ``rocotorewind`` is a tool that attempts to undo the effects of running a task and is commonly used to rerun part -of a workflow that has failed. If a task fails to run (the STATE is DEAD), and needs to be restarted, the ``rocotorewind`` +of a workflow that has failed. If a task fails to run (the STATE is DEAD) and needs to be restarted, the ``rocotorewind`` command will rerun tasks in the workflow. The command line options are the same as those described in the ``rocotocheck`` :numref:`section %s `, and the general usage statement looks like: .. code-block:: console - rocotorewind -w /path/to/workflow/xml/file -d /path/to/workflow/database/ file -c YYYYMMDDHHMM -t taskname + rocotorewind -w /path/to/workflow/xml/file -d /path/to/workflow/database/ file -c YYYYMMDDHHmm -t taskname Running this command will edit the Rocoto database file ``FV3LAM_wflow.db`` to remove evidence that the job has been run. ``rocotorewind`` is recommended over ``rocotoboot`` for restarting a task, since ``rocotoboot`` will force a specific -task to run, ignoring all dependencies and throttle limits. The throttle limit, denoted by the variable cyclethrottle -in the ``FV3LAM_wflow.xml`` file, limits how many cycles can be active at one time. An example of how to use this +task to run, ignoring all dependencies and throttle limits. The throttle limit, denoted by the variable cyclethrottle +in the ``FV3LAM_wflow.xml`` file, limits how many cycles can be active at one time. An example of how to use this command to rerun the forecast task from ``$EXPTDIR`` is: .. code-block:: console @@ -223,8 +224,8 @@ command to rerun the forecast task from ``$EXPTDIR`` is: rocotoboot =========== -``rocotoboot`` will force a specific task of a cycle in a Rocoto workflow to run. All dependencies and throttle -limits are ignored, and it is generally recommended to use ``rocotorewind`` instead. An example of how to +``rocotoboot`` will force a specific task of a cycle in a Rocoto workflow to run. All dependencies and throttle +limits are ignored, and it is generally recommended to use ``rocotorewind`` instead. An example of how to use this command to rerun the ``make_ics`` task from ``$EXPTDIR`` is: .. code-block:: console diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index 93f240d672..8cc67f48e8 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -20,9 +20,9 @@ UFS Short-Range Weather App Users Guide ConfigWorkflow LAMGrids ConfigNewPlatform + RocotoInfo WE2Etests Graphics ContributorsGuide FAQ - RocotoInfo Glossary From 50018dd24797eaa431fdbff3673d38c10e2e405b Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 29 Apr 2022 17:49:23 -0400 Subject: [PATCH 118/158] fix minor formatting/wording issues --- docs/UsersGuide/source/RocotoInfo.rst | 40 +++++++++++++-------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/docs/UsersGuide/source/RocotoInfo.rst b/docs/UsersGuide/source/RocotoInfo.rst index 97177e4029..f2ed1836ef 100644 --- a/docs/UsersGuide/source/RocotoInfo.rst +++ b/docs/UsersGuide/source/RocotoInfo.rst @@ -7,10 +7,10 @@ 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 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 -cycles. More information on Rocoto can be found at https://github.com/christopherwharrop/rocoto/wiki/documentation. +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/ufs/templates`` directory. When the ``generate_FV3LAM_wflow.sh`` +which resides in the ``regional_workflow/ush/templates`` directory. When the ``generate_FV3LAM_wflow.sh`` script is run, the ``fill_jinja_template.py`` script is called, and the parameters in the template file are filled in. The completed file contains the workflow task names, parameters needed by the job scheduler, and task interdependencies. The generated XML file is then copied to the experiment directory: @@ -23,7 +23,7 @@ Descriptions and examples of commonly used commands are discussed below. rocotorun ========== The ``rocotorun`` command is used to run the workflow by submitting tasks to the batch system. It will -automatically resubmit failed tasks and can recover from system outages without user intervention. An example is: +automatically resubmit failed tasks and can recover from system outages without user intervention. The command takes the following format: .. code-block:: console @@ -32,10 +32,8 @@ automatically resubmit failed tasks and can recover from system outages without where * ``-w`` specifies the name of the workflow definition file. This must be an XML file. -* ``-d`` specifies the name of the database file that is to be used to store the state of the workflow. - The database file is a binary file created and used only by Rocoto and need not exist prior to the first - time the command is run. -* ``-v`` (optional) specified level of verbosity. If no level is specified, a level of 1 is used. +* ``-d`` specifies the name of the database file that stores the state of the workflow. The database file is a binary file created and used only by Rocoto. It need not exist prior to the first time the command is run. +* ``-v`` (optional) specified level of verbosity. If no level is specified, a level of 1 is used. From the ``$EXPTDIR`` directory, the ``rocotorun`` command for the workflow would be: @@ -46,15 +44,15 @@ From the ``$EXPTDIR`` directory, the ``rocotorun`` command for the workflow woul It is important to note that the ``rocotorun`` process is iterative; the command must be executed many times before the entire workflow is completed, usually every 1-10 minutes. This command can be placed in the user’s crontab, and cron will call it with a specified frequency. More information on -this command can be found at https://github.com/christopherwharrop/rocoto/wiki/documentation. +this command can be found in the `Rocoto documentation `__. The first time the ``rocotorun`` command is executed for a workflow, the files ``FV3LAM_wflow.db`` and ``FV3LAM_wflow_lock.db`` are created. There is usually no need for the user to modify these files. Each time this command is executed, the last known state of the workflow is read from the ``FV3LAM_wflow.db`` file, the batch system is queried, jobs are submitted for tasks whose dependencies have been satisfied, and the current state of the workflow is saved in ``FV3LAM_wflow.db``. If there is a need to relaunch -the workflow from scratch, both database files can be deleted, and the workflow can be run using ``rocotorun`` -or the launch script ``launch_FV3LAM_wflow.sh`` (executed multiple times). +the workflow from scratch, both database files can be deleted, and the workflow can be run by executing the ``rocotorun`` command +or the launch script (``launch_FV3LAM_wflow.sh``) multiple times. rocotostat =========== @@ -71,7 +69,7 @@ Executing this command will generate a workflow status table similar to the foll .. code-block:: console CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ============================================================================================================================= + ============================================================================================================= 201907010000 make_grid 175805 QUEUED - 0 0.0 201907010000 make_orog - - - - - 201907010000 make_sfc_climo - - - - - @@ -104,7 +102,7 @@ on your grid size and computational resources), the output of the ``rocotostat`` .. code-block:: console CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ============================================================================================================================ + ==================================================================================================== 201907010000 make_grid 175805 SUCCEEDED 0 1 10.0 201907010000 make_orog 175810 SUCCEEDED 0 1 27.0 201907010000 make_sfc_climo 175822 SUCCEEDED 0 1 38.0 @@ -123,7 +121,7 @@ on your grid size and computational resources), the output of the ``rocotostat`` When the workflow runs to completion, all tasks will be marked as SUCCEEDED. The log files from the tasks are located in ``$EXPTDIR/log``. If any tasks fail, the corresponding log file can be checked for error -messages. Optional arguments for the ``rocotostat`` command can be found at https://github.com/christopherwharrop/rocoto/wiki/documentation. +messages. Optional arguments for the ``rocotostat`` command can be found in the `Rocoto documentation `__. .. _rocotocheck: @@ -131,7 +129,7 @@ rocotocheck ============ Sometimes, issuing a ``rocotorun`` command will not cause the next task to launch. ``rocotocheck`` is a tool that can be used to query detailed information about a task or cycle in the Rocoto workflow. To -determine the cause of a particular task not being submitted, the ``rocotocheck`` command can be used +determine why a particular task has not been submitted, the ``rocotocheck`` command can be used from the ``$EXPTDIR`` directory as follows: .. code-block:: console @@ -193,9 +191,9 @@ Running ``rocotocheck`` will result in output similar to the following: Unknown count: 0 Duration: 58.0 -This shows that although all dependencies for this task are satisfied (see the dependencies section, highlighted above), +This output shows that although all dependencies for this task are satisfied (see the dependencies section, highlighted above), it cannot run because its ``maxtries`` value (highlighted) is 3. Rocoto will attempt to launch it at most 3 times, -and it has already been tried 3 times (the ``Tries`` value, also highlighted). +and it has already been tried 3 times (note the ``Tries`` value, also highlighted). The output of the ``rocotocheck`` command is often useful in determining whether the dependencies for a given task have been met. If not, the dependencies section in the output of ``rocotocheck`` will indicate this by stating that a @@ -203,19 +201,19 @@ dependency "is NOT satisfied". rocotorewind ============= -``rocotorewind`` is a tool that attempts to undo the effects of running a task and is commonly used to rerun part +``rocotorewind`` is a tool that attempts to undo the effects of running a task. It is commonly used to rerun part of a workflow that has failed. If a task fails to run (the STATE is DEAD) and needs to be restarted, the ``rocotorewind`` -command will rerun tasks in the workflow. The command line options are the same as those described in the ``rocotocheck`` -:numref:`section %s `, and the general usage statement looks like: +command will rerun tasks in the workflow. The command line options are the same as those described for ``rocotocheck`` +(in :numref:`section %s `), and the general usage statement looks like the following: .. code-block:: console - rocotorewind -w /path/to/workflow/xml/file -d /path/to/workflow/database/ file -c YYYYMMDDHHmm -t taskname + rocotorewind -w -d file -c -t Running this command will edit the Rocoto database file ``FV3LAM_wflow.db`` to remove evidence that the job has been run. ``rocotorewind`` is recommended over ``rocotoboot`` for restarting a task, since ``rocotoboot`` will force a specific task to run, ignoring all dependencies and throttle limits. The throttle limit, denoted by the variable cyclethrottle -in the ``FV3LAM_wflow.xml`` file, limits how many cycles can be active at one time. An example of how to use this +in the ``FV3LAM_wflow.xml`` file, limits how many cycles can be active at one time. An example of how to use the ``rocotorewind`` command to rerun the forecast task from ``$EXPTDIR`` is: .. code-block:: console From 5e28faf6bcbbb88f29e730b4dc9a9cacc97b4c2c Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 2 May 2022 14:55:54 -0400 Subject: [PATCH 119/158] updates to LAMgrid chapter --- docs/UsersGuide/source/ConfigWorkflow.rst | 1 + docs/UsersGuide/source/Graphics.rst | 4 +- docs/UsersGuide/source/LAMGrids.rst | 49 +++++++++-------------- 3 files changed, 23 insertions(+), 31 deletions(-) diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index e7109af658..a7b445286e 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -726,6 +726,7 @@ Computational Forecast Parameters #. If the experiment is using a predefined grid and the user sets the ``BLOCKSIZE`` parameter in the user-specified experiment configuration file (i.e., ``config.sh``), that value will be used in the forecast(s). Otherwise, the default ``BLOCKSIZE`` 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 ``BLOCKSIZE`` parameter in that configuration file. Otherwise, it 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. +.. _WriteComp: Write-Component (Quilting) Parameters ====================================== diff --git a/docs/UsersGuide/source/Graphics.rst b/docs/UsersGuide/source/Graphics.rst index 51f03f8a6d..73929fe7eb 100644 --- a/docs/UsersGuide/source/Graphics.rst +++ b/docs/UsersGuide/source/Graphics.rst @@ -3,8 +3,8 @@ =================== Graphics Generation =================== -Two Python plotting scripts are provided to generate plots from the FV3-LAM post-processed GRIB2 -output over the CONUS for a number of variables, including: +Two Python plotting scripts are provided to generate plots from the FV3-LAM post-processed :term:`GRIB2` +output over the :term:`CONUS` for a number of variables, including: * 2-m temperature * 2-m dew point temperature diff --git a/docs/UsersGuide/source/LAMGrids.rst b/docs/UsersGuide/source/LAMGrids.rst index 84d7cd84f2..7083e63f7a 100644 --- a/docs/UsersGuide/source/LAMGrids.rst +++ b/docs/UsersGuide/source/LAMGrids.rst @@ -3,17 +3,17 @@ ======================================================================== Limited Area Model (LAM) Grids: Predefined and User-Generated Options ======================================================================== -In order to set up the workflow and experiment generation of the UFS SRW App, the user +In order to set up the workflow and generate an experiment with the UFS SRW App, the user must choose between three predefined FV3-LAM grids or generate a user-defined grid. At this time, full support will only be provided to those using one of the three predefined grids supported in this release. However, preliminary information is provided at the end of this chapter that describes how users can leverage the SRW App workflow scripts to generate -their own user-defined grid. This feature is not fully supported at this time and is +their own user-defined grid. Currently, this feature is not fully supported and is "use at your own risk". Predefined Grids ================ -The UFS SRW App release includes three predefined LAM grids that users can choose from +The UFS SRW App release includes three predefined LAM grids to choose between prior to generating a workflow/experiment configuration. To select a predefined grid, the ``PREDEF_GRID_NAME`` variable within the ``config.sh`` script needs to be set to one of the following three options: @@ -28,32 +28,23 @@ of the following three options: *The boundary of the RRFS_CONUS_3km computational grid (red) and corresponding write-component grid (blue).* -The predefined grids are named after the prototype 3-km continental United States (CONUS) grid being -tested for the Rapid Refresh Forecast System (RRFS), which will be a convection-allowing, -hourly-cycled, FV3-LAM-based ensemble planned for operational implementation in 2024. To allow -for use of High Resolution Rapid Refresh (`HRRR `_) data to -initialize the SRW App, all three supported grids were created to fit completely within the HRRR domain. -Three resolution options were provided for flexibility related to compute resources -and physics options. For example, a user may wish to use the 13-km or 25-km domain when running -with the ``FV3_GFS_v16`` suite definition file (SDF), since that SDF uses cumulus physics that are -not configured to run at the 3-km resolution. In addition, users will have fewer computational -constraints when running with the 13-km and 25-km domains. - -The boundary of the ``RRFS_CONUS_3km`` domain is shown in :numref:`Figure %s ` (in red). -Note that while it is possible to initialize the FV3-LAM with coarser external model data when using the -``RRFS_CONUS_3km`` domain, it is generally advised to use external model data that has a resolution -similar to that of the native FV3-LAM (predefined) grid. In addition, this grid is ideal for running the -``FV3_RRFS_v1beta`` suite definition file (SDF), since this SDF was specifically created for convection-allowing scales and is the -precursor to the operational physics suite that will be used in the RRFS. - -As can be seen in :numref:`Figure %s `, the boundary of the write-component grid (in blue) sits -just inside the computational domain (in red). This extra grid is required because the post-processing -utility (UPP) is currently unable to process data on the native FV3 gnomonic grid (in red). Therefore, -model data are interpolated to a Lambert conformal grid (the write component grid) in order for UPP to -read in and correctly process the data. - -The ``RRFS_CONUS_13km`` grid (:numref:`Fig. %s `) also covers the full CONUS. This grid is meant to -be run with the ``FV3_GFS_v16`` SDF. +The predefined grids follow the naming conventions (RRFS_CONUS_*km) of the prototype 3-km continental United States (CONUS) grid being tested for the Rapid Refresh Forecast System (:term:`RRFS`). The RRFS will be a convection-allowing, hourly-cycled, FV3-LAM-based ensemble planned for operational implementation in 2024. All three supported grids were created to fit completely within the High Resolution Rapid Refresh (`HRRR `_) domain to allow for use of HRRR data to initialize the SRW App. + +Three resolution options were provided for flexibility related to compute resources and physics options. + +| Grid | Physics Suite | +| RRFS_CONUS_3km | FV3_RRFS_v1beta | +| | FV3_HRRR | +| | +| RRFS_CONUS_13km | +| RRFS_CONUS_25km | + + +For example, a user may wish to use the ``FV3_GFS_v16`` physics suite definition file (:term:`SDF`), which uses cumulus physics that are not configured to run at the 3-km resolution. In this case, the 13-km or 25-km domain options are better suited to the experiment. In addition, users will have fewer computational constraints when running with the 13-km and 25-km domains. However, the 3km domain is ideal for running the ``FV3_RRFS_v1beta`` physics suite, since this :term:`SDF` was specifically created for convection-allowing scales and is the precursor to the operational physics suite that will be used in the RRFS. The boundary of the ``RRFS_CONUS_3km`` domain is shown in :numref:`Figure %s ` (in red). Note that while it is possible to initialize the FV3-LAM with coarser external model data when using the ``RRFS_CONUS_3km`` domain, it is generally advised to use external model data that has a resolution similar to that of the native FV3-LAM (predefined) grid. + +As can be seen in :numref:`Figure %s `, the boundary of the :ref:`write-component grid ` (in blue) sits just inside the computational domain (in red). This extra grid is required because the post-processing utility (:term:`UPP`) is currently unable to process data on the native FV3 gnomonic grid (in red). Therefore, model data are interpolated to a Lambert conformal grid (the write component grid) in order for UPP to read in and correctly process the data. + +The ``RRFS_CONUS_13km`` grid (:numref:`Fig. %s `) also covers the full CONUS. This grid is meant to be run with the ``FV3_GFS_v16`` :term:`SDF`. .. _RRFS_CONUS_13km: From 43cd2ea3e526e9ae46fdf8dc983e7220a92e8c0a Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 3 May 2022 13:56:35 -0400 Subject: [PATCH 120/158] LAM Grid edits --- docs/UsersGuide/source/BuildRunSRW.rst | 6 +- docs/UsersGuide/source/ConfigWorkflow.rst | 18 ++-- docs/UsersGuide/source/Glossary.rst | 5 + docs/UsersGuide/source/LAMGrids.rst | 124 +++++++++++++++------- 4 files changed, 104 insertions(+), 49 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 34524b3fe5..f3a13359ee 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -258,7 +258,7 @@ The SRW App requires input files to run. These include static datasets, initial Grid Configuration ======================= -The SRW App officially supports three different predefined grids as shown in :numref:`Table %s `. The "out-of-the-box" SRW App case uses the ``RRFS_CONUS_25km`` predefined grid option. More information on the predefined and user-generated grid options can be found in :numref:`Chapter %s ` for those who are curious. Users who plan to utilize one of the three pre-defined domain (grid) options may continue to :numref:`Step %s `. Users who plan to create a new domain should refer to :numref:`Chapter %s ` for details on how to do so. At a minimum, these users will need to add the new grid name to the ``valid_param_vals`` script and add the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. +The SRW App officially supports four different predefined grids as shown in :numref:`Table %s `. The "out-of-the-box" SRW App case uses the ``RRFS_CONUS_25km`` predefined grid option. More information on the predefined and user-generated grid options can be found in :numref:`Chapter %s ` for those who are curious. Users who plan to utilize one of the four predefined domain (grid) options may continue to :numref:`Step %s `. Users who plan to create a new domain should refer to :numref:`Chapter %s ` for details on how to do so. At a minimum, these users will need to add the new grid name to the ``valid_param_vals`` script and add the corresponding grid-specific parameters in the ``set_predef_grid_params`` script. .. _PredefinedGrids: @@ -273,6 +273,8 @@ The SRW App officially supports three different predefined grids as shown in :nu +----------------------+-------------------+--------------------------------+ | RRFS_CONUS_3km | ESG grid | lambert_conformal | +----------------------+-------------------+--------------------------------+ + | RRFS_SUBCONUS_3km | ESG grid | lambert_conformal | + +----------------------+-------------------+--------------------------------+ .. _GenerateForecast: @@ -523,7 +525,7 @@ The default settings in this file include a predefined 25-km :term:`CONUS` grid Next, edit the new ``config.sh`` file to customize it for your machine. At a minimum, change the ``MACHINE`` and ``ACCOUNT`` variables; then choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If you have pre-staged the initialization data for the experiment, set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, and set the paths to the data for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. -Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the three predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. +Sample settings are indicated below for Level 1 platforms. Detailed guidance applicable to all systems can be found in :numref:`Chapter %s: Configuring the Workflow `, which discusses each variable and the options available. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. .. important:: diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index a7b445286e..13342eece3 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -312,14 +312,14 @@ METplus Parameters User-specified location of top-level directory where CCPA hourly precipitation files used by METplus are located. This parameter needs to be set for both user-provided observations and for observations that are retrieved from the NOAA HPSS (if the user has access) via the ``get_obs_ccpa_tn`` task. (This task is activated in the workflow by setting ``RUN_TASK_GET_OBS_CCPA="TRUE"``). METplus configuration files require the use of predetermined directory structure and file names. If the CCPA files are user-provided, they need to follow the anticipated naming structure: ``{YYYYMMDD}/ccpa.t{HH}z.01h.hrap.conus.gb2``, where YYYYMMDD and HH are as described in the note :ref:`above `. When pulling observations from NOAA HPSS, the data retrieved will be placed in the ``CCPA_OBS_DIR`` directory. This path must be defind as ``//ccpa/proc``. METplus is configured to verify 01-, 03-, 06-, and 24-h accumulated precipitation using hourly CCPA files. - .. note:: - There is a problem with the valid time in the metadata for files valid from 19 - 00 UTC (i.e., files under the "00" directory). The script to pull the CCPA data from the NOAA HPSS (``regional_workflow/scripts/exregional_get_ccpa_files.sh``) has an example of how to account for this and organize the data into a more intuitive format. When a fix is provided, it will be accounted for in the ``exregional_get_ccpa_files.sh`` script. +.. note:: + There is a problem with the valid time in the metadata for files valid from 19 - 00 UTC (i.e., files under the "00" directory). The script to pull the CCPA data from the NOAA HPSS (``regional_workflow/scripts/exregional_get_ccpa_files.sh``) has an example of how to account for this and organize the data into a more intuitive format. When a fix is provided, it will be accounted for in the ``exregional_get_ccpa_files.sh`` script. ``MRMS_OBS_DIR``: (Default: "") User-specified location of top-level directory where MRMS composite reflectivity files used by METplus are located. This parameter needs to be set for both user-provided observations and for observations that are retrieved from the NOAA HPSS (if the user has access) via the ``get_obs_mrms_tn`` task (activated in the workflow by setting ``RUN_TASK_GET_OBS_MRMS="TRUE"``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. Please note, this path must be defind as ``//mrms/proc``. METplus configuration files require the use of a predetermined directory structure and file names. Therefore, if the MRMS files are user-provided, they need to follow the anticipated naming structure: ``{YYYYMMDD}/MergedReflectivityQCComposite_00.50_{YYYYMMDD}-{HH}{mm}{SS}.grib2``, where YYYYMMDD and {HH}{mm}{SS} are as described in the note :ref:`above `. - .. note:: - METplus is configured to look for a MRMS composite reflectivity file for the valid time of the forecast being verified; since MRMS composite reflectivity files do not always exactly match the valid time, a script, within the main script to retrieve MRMS data from the NOAA HPSS, is used to identify and rename the MRMS composite reflectivity file to match the valid time of the forecast. The script to pull the MRMS data from the NOAA HPSS has an example of the expected file naming structure: ``regional_workflow/scripts/exregional_get_mrms_files.sh``. This script calls the script used to identify the MRMS file closest to the valid time: ``regional_workflow/ush/mrms_pull_topofhour.py``. +.. note:: + METplus is configured to look for a MRMS composite reflectivity file for the valid time of the forecast being verified; since MRMS composite reflectivity files do not always exactly match the valid time, a script, within the main script to retrieve MRMS data from the NOAA HPSS, is used to identify and rename the MRMS composite reflectivity file to match the valid time of the forecast. The script to pull the MRMS data from the NOAA HPSS has an example of the expected file naming structure: ``regional_workflow/scripts/exregional_get_mrms_files.sh``. This script calls the script used to identify the MRMS file closest to the valid time: ``regional_workflow/ush/mrms_pull_topofhour.py``. ``NDAS_OBS_DIR``: (Default: "") @@ -732,12 +732,12 @@ Write-Component (Quilting) Parameters ====================================== .. note:: - The :term:`UPP` (called by the ``RUN_POST_TN`` task) cannot process output on the native grid types ("GFDLgrid" and "ESGgrid"), so output fields are interpolated to a write-component grid before writing them to an output file. The output files written by the UFS Weather Model model use an Earth System Modeling Framework (ESMF) component, referred to as the write component. This model component is configured with settings in the ``model_configure`` file, as described in `Section 4.2.3 `__ of the UFS Weather Model documentation. + The :term:`UPP` (called by the ``RUN_POST_TN`` task) cannot process output on the native grid types ("GFDLgrid" and "ESGgrid"), so output fields are interpolated to a **write-component grid** before writing them to an output file. The output files written by the UFS Weather Model model use an Earth System Modeling Framework (ESMF) component, referred to as the **write component**. This model component is configured with settings in the ``model_configure`` file, as described in `Section 4.2.3 `__ of the UFS Weather Model documentation. ``QUILTING``: (Default: "TRUE") - .. attention:: - The regional grid requires the use of the write component, so users generally should not need to change the default value for ``QUILTING``. +.. attention:: + The regional grid requires the use of the write component, so users generally should not need to change the default value for ``QUILTING``. Flag that determines whether to use the write component for writing forecast output files to disk. If set to "TRUE", the forecast model will output files named ``dynf$HHH.nc`` and ``phyf$HHH.nc`` (where HHH is the 3-hour output forecast hour) containing dynamics and physics fields, respectively, on the write-component grid. (The regridding from the native FV3-LAM grid to the write-component grid is done by the forecast model.) If ``QUILTING`` is set to "FALSE", then the output file names are ``fv3_history.nc`` and ``fv3_history2d.nc``, and they contain fields on the native grid. Although the UFS Weather Model can run without quilting, the regional grid requires the use of the write component. Therefore, QUILTING should be set to "TRUE" when running the SRW App. If ``QUILTING`` is set to "FALSE", the ``RUN_POST_TN`` (meta)task cannot run because the :term:`UPP` code that this task calls cannot process fields on the native grid. In that case, the ``RUN_POST_TN`` (meta)task will be automatically removed from the Rocoto workflow XML. The :ref:`INLINE POST ` option also requires ``QUILTING`` to be set to "TRUE" in the SRW App. @@ -818,11 +818,11 @@ Predefined Grid Parameters | "RRFS_CONUS_25km" | "RRFS_CONUS_13km" - | "RRFS_CONUS_3km" + | "RRFS_CONUS_3km" + | "RRFS_SUBCONUS_3km" **Other valid values include:** - | "RRFS_SUBCONUS_3km" | "RRFS_AK_13km" | "RRFS_AK_3km" | "CONUS_25km_GFDLgrid" diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 135b2c2a5e..a9fd13e5ba 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -31,6 +31,10 @@ Glossary CONUS Continental United States + convection-allowing models + CAM + Convection-allowing models (CAMs) are models that run on high-resolution grids (usually with grid spacing at 4km or less) that 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 even subhourly). + cycle An hour of the day on which a forecast is started. @@ -142,6 +146,7 @@ Glossary 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. RAP diff --git a/docs/UsersGuide/source/LAMGrids.rst b/docs/UsersGuide/source/LAMGrids.rst index 7083e63f7a..651dd32707 100644 --- a/docs/UsersGuide/source/LAMGrids.rst +++ b/docs/UsersGuide/source/LAMGrids.rst @@ -4,47 +4,88 @@ Limited Area Model (LAM) Grids: Predefined and User-Generated Options ======================================================================== In order to set up the workflow and generate an experiment with the UFS SRW App, the user -must choose between three predefined FV3-LAM grids or generate a user-defined grid. -At this time, full support will only be provided to those using one of the three predefined +must choose between four predefined :term:`FV3`-:term:`LAM` grids or generate a user-defined grid. +At this time, full support will only be provided to those using one of the four predefined grids supported in this release. However, preliminary information is provided at the end of this chapter that describes how users can leverage the SRW App workflow scripts to generate their own user-defined grid. Currently, this feature is not fully supported and is "use at your own risk". Predefined Grids -================ -The UFS SRW App release includes three predefined LAM grids to choose between -prior to generating a workflow/experiment configuration. To select a predefined grid, +================= +The UFS SRW App release includes four predefined LAM grids to choose between +prior to generating a workflow/experiment configuration. To select a predefined grid, the ``PREDEF_GRID_NAME`` variable within the ``config.sh`` script needs to be set to one -of the following three options: +of the following four options: * ``RRFS_CONUS_3km`` +* ``SUBCONUS_Ind_3km`` * ``RRFS_CONUS_13km`` * ``RRFS_CONUS_25km`` +These four options are provided for flexibility related to compute resources and supported physics options. The high-resolution 3-km :term:`CONUS` grid generally requires more compute power and works well with three of the four supported physics suites (see :numref:`Table %s `). Low-resolution grids (i.e., 13-km and 25-km domains) require less compute power and should generally be used with the fourth supported physics suite: ``FV3_GFS_v16``. + +.. + COMMENT: FV3_WoFS can run on a 13-km and 25-km grid according to Yunheng. Can the HRRR and RRFS_v1beta also run on the 13-km and 25-km grids? Why is FV3_GFS_v16 preferred? Because it has cumulus physics? + +.. _GridPhysicsCombos: + +.. table:: Preferred grid and physics combinations for supported domains & physics suites + + +-------------------+------------------+ + | Grid | Physics Suite(s) | + +===================+==================+ + | RRFS_CONUS_3km | FV3_RRFS_v1beta | + | | | + | | FV3_HRRR | + | | | + | | FV3_WoFS | + +-------------------+------------------+ + | SUBCONUS_Ind_3km | FV3_RRFS_v1beta | + | | | + | | FV3_HRRR | + | | | + | | FV3_WoFS | + +-------------------+------------------+ + | RRFS_CONUS_13km | FV3_GFS_v16 | + +-------------------+------------------+ + | RRFS_CONUS_25km | FV3_GFS_v16 | + +-------------------+------------------+ + +In theory, any of the supported physics suites could be used with any of the predefined grids, but the results will be more accurate and meaningful with appropriate grid/physics pairings. + +The predefined :term:`CONUS` grids follow the naming convention (e.g., RRFS_CONUS_*km) of the prototype 3-km continental United States (CONUS) grid being tested for the Rapid Refresh Forecast System (RRFS). The RRFS will be a convection-allowing, hourly-cycled, :term:`FV3`-:term:`LAM`-based ensemble planned for operational implementation in 2024. All four supported grids were created to fit completely within the High Resolution Rapid Refresh (`HRRR `_) domain to allow for use of HRRR data to initialize the SRW App. + +Predefined 3-km CONUS Grid +----------------------------- + +The 3km CONUS domain is ideal for running the ``FV3_RRFS_v1beta`` physics suite, since this suite definition file (:term:`SDF`) was specifically created for convection-allowing scales and is the precursor to the operational physics suite that will be used in the RRFS. The 3-km domain can also be used with the ``FV3_HRRR`` and ``FV3_WoFS`` physics suites, which likewise do not include convective parameterization. In fact, the ``FV3_WoFS`` physics suite is configured to run at 3-km *or less* and could therefore run with even higher-resolution user-defined domains if desired. However, the ``FV3_GFS_v16`` suite generally should *not* be used with the 3-km domain because the cumulus physics used in that physics suite are not configured to run at the 3-km resolution. + .. _RRFS_CONUS_3km: .. figure:: _static/RRFS_CONUS_3km.sphr.native_wrtcmp.png *The boundary of the RRFS_CONUS_3km computational grid (red) and corresponding write-component grid (blue).* -The predefined grids follow the naming conventions (RRFS_CONUS_*km) of the prototype 3-km continental United States (CONUS) grid being tested for the Rapid Refresh Forecast System (:term:`RRFS`). The RRFS will be a convection-allowing, hourly-cycled, FV3-LAM-based ensemble planned for operational implementation in 2024. All three supported grids were created to fit completely within the High Resolution Rapid Refresh (`HRRR `_) domain to allow for use of HRRR data to initialize the SRW App. +The boundary of the ``RRFS_CONUS_3km`` domain is shown in :numref:`Figure %s ` (in red), and the boundary of the :ref:`write-component grid ` sits just inside the computational domain (in blue). This extra grid is required because the post-processing utility (:term:`UPP`) is currently unable to process data on the native FV3 gnomonic grid (in red). Therefore, model data are interpolated to a Lambert conformal grid (the write component grid) in order for UPP to read in and correctly process the data. + +.. note:: + While it is possible to initialize the FV3-LAM with coarser external model data when using the ``RRFS_CONUS_3km`` domain, it is generally advised to use external model data that has a resolution similar to that of the native FV3-LAM (predefined) grid. -Three resolution options were provided for flexibility related to compute resources and physics options. -| Grid | Physics Suite | -| RRFS_CONUS_3km | FV3_RRFS_v1beta | -| | FV3_HRRR | -| | -| RRFS_CONUS_13km | -| RRFS_CONUS_25km | +Predefined SUBCONUS Grid Over Indianapolis +-------------------------------------------- +.. _SUBCONUS_Ind_3km: -For example, a user may wish to use the ``FV3_GFS_v16`` physics suite definition file (:term:`SDF`), which uses cumulus physics that are not configured to run at the 3-km resolution. In this case, the 13-km or 25-km domain options are better suited to the experiment. In addition, users will have fewer computational constraints when running with the 13-km and 25-km domains. However, the 3km domain is ideal for running the ``FV3_RRFS_v1beta`` physics suite, since this :term:`SDF` was specifically created for convection-allowing scales and is the precursor to the operational physics suite that will be used in the RRFS. The boundary of the ``RRFS_CONUS_3km`` domain is shown in :numref:`Figure %s ` (in red). Note that while it is possible to initialize the FV3-LAM with coarser external model data when using the ``RRFS_CONUS_3km`` domain, it is generally advised to use external model data that has a resolution similar to that of the native FV3-LAM (predefined) grid. +.. figure:: _static/SUBCONUS_Ind_3km.sphr.native_wrtcmp.png -As can be seen in :numref:`Figure %s `, the boundary of the :ref:`write-component grid ` (in blue) sits just inside the computational domain (in red). This extra grid is required because the post-processing utility (:term:`UPP`) is currently unable to process data on the native FV3 gnomonic grid (in red). Therefore, model data are interpolated to a Lambert conformal grid (the write component grid) in order for UPP to read in and correctly process the data. + *The boundary of the SUBCONUS_Ind_3km computational grid (red) and corresponding write-component grid (blue).* -The ``RRFS_CONUS_13km`` grid (:numref:`Fig. %s `) also covers the full CONUS. This grid is meant to be run with the ``FV3_GFS_v16`` :term:`SDF`. +The ``SUBCONUS_Ind_3km`` grid covers only a small section of the CONUS over Indianapolis. Like the ``RRFS_CONUS_3km`` grid, it is ideally paired with the ``FV3_RRFS_v1beta``, ``FV3_HRRR``, or ``FV3_WoFS`` physics suites, since these are all convection-allowing physics suites designed to work well on high-resolution grids. + +Predefined 13-km Grid +------------------------ .. _RRFS_CONUS_13km: @@ -52,9 +93,10 @@ The ``RRFS_CONUS_13km`` grid (:numref:`Fig. %s `) also covers t *The boundary of the RRFS_CONUS_13km computational grid (red) and corresponding write-component grid (blue).* -The final predefined CONUS grid (:numref:`Fig. %s `) uses a 25-km resolution and -is meant mostly for quick testing to ensure functionality prior to using a higher-resolution domain. -However, for users who would like to use this domain for research, the ``FV3_GFS_v16`` SDF is recommended. +The ``RRFS_CONUS_13km`` grid (:numref:`Fig. %s `) covers the full :term:`CONUS`. This grid is meant to be run with the ``FV3_GFS_v16`` :term:`SDF`. The ``FV3_GFS_v16`` physics suite uses convective :term:`parameterizations`, whereas the other supported suites do not. Convective parameterizations are necessary for low-resolution grids because convection occurs on scales smaller than 25km and 13km. + +Predefined 25-km Grid +------------------------ .. _RRFS_CONUS_25km: @@ -62,26 +104,32 @@ However, for users who would like to use this domain for research, the ``FV3_GFS *The boundary of the RRFS_CONUS_25km computational grid (red) and corresponding write-component grid (blue).* +The final predefined :term:`CONUS` grid (:numref:`Fig. %s `) uses a 25-km resolution and +is meant mostly for quick testing to ensure functionality prior to using a higher-resolution domain. +However, for users who would like to use this domain for research, the ``FV3_GFS_v16`` SDF is recommended for the reasons mentioned above. + +Ultimately, the choice of grid is experiment-dependent and resource-dependent. For example, a user may wish to use the ``FV3_GFS_v16`` physics suite definition file (:term:`SDF`), which uses cumulus physics that are not configured to run at the 3-km resolution. In this case, the 13-km or 25-km domain options are better suited to the experiment. Users will also have fewer computational constraints when running with the 13-km and 25-km domains, so depending on the resources available to them, certain grids may be better options than others. + Creating User-Generated Grids -============================= -While the three predefined grids available in this release are ideal for users just starting +=============================== +While the four predefined grids available in this release are ideal for users just starting out with the SRW App, more advanced users may wish to create their own grid for testing over -a different region and/or with a different resolution. Creating a user-defined grid requires -knowledge of how the SRW App workflow functions, in particular, understanding the set of -scripts that handle the workflow and experiment generation. It is also important to note that -user-defined grids are not a supported feature of the current release; however information is +a different region and/or with a different resolution. Creating a user-defined grid requires +knowledge of how the SRW App workflow functions. In particular, it is important to understand the set of +scripts that handle the workflow and experiment generation. It is also important to note that +user-defined grids are not a supported feature of the current release; however, information is being provided for the benefit of the FV3-LAM community. With those caveats in mind, this section provides instructions for adding a new grid to the FV3-LAM workflow that will be generated using the "ESGgrid" method (i.e., using the regional_esg_grid code -in the UFS_UTILS repository, where ESG stands for "Extended Schmidt Gnomonic"). We assume here +in the UFS_UTILS repository, where ESG stands for "Extended Schmidt Gnomonic"). We assume here that the grid to be generated covers a domain that (1) does not contain either of the poles and (2) does not cross the -180 deg --> +180 deg discontinuity in longitude near the international date line. Instructions for domains that do not have these restrictions will be provided in a future release. The steps to add such a grid to the workflow are as follows: -#. Decide on the name of the grid. For the purposes of this documentation, the grid will be called "NEW_GRID". +#. Decide on the name of the grid. For the purposes of this documentation, the grid will be called "NEW_GRID". #. Add NEW_GRID to the array ``valid_vals_PREDEF_GRID_NAME`` in the ``ufs-srweather-app/regional_workflow/ush/valid_param_vals.sh`` file. @@ -125,7 +173,7 @@ The following is an example of a stanza for "NEW_GRID" to be added to ``set_pred ESGgrid_LAT_CTR=38.5 # The grid cell sizes in the x and y directions, where x and y are the - # native coordinates of any ESG grid. The units of x and y are in + # native coordinates of any ESG grid. The units of x and y are in # meters. These should be set to the nominal resolution we want the # grid to have. The cells will have exactly these sizes in xy-space # (computational space) but will have varying size in physical space. @@ -143,9 +191,9 @@ The following is an example of a stanza for "NEW_GRID" to be added to ``set_pred # The width of the halo (in units of grid cells) that the temporary # wide-halo grid created during the grid generation task (make_grid) - # will have. This wide-halo grid gets "shaved" down to obtain the + # will have. This wide-halo grid gets "shaved" down to obtain the # 4-cell-wide halo and 3-cell-wide halo grids that the forecast model - # (as well as other codes) will actually use. Recall that the halo is + # (as well as other codes) will actually use. Recall that the halo is # needed to provide lateral boundary conditions to the forecast model. # Usually, there is no need to modify this parameter. @@ -155,9 +203,9 @@ The following is an example of a stanza for "NEW_GRID" to be added to ``set_pred # is the (inverse) frequency with which (most of) the physics suite is # called. The smaller the grid cell size is, the smaller this value # needs to be in order to avoid numerical instabilities during the - # forecast. The values specified below are used only if DT_ATMOS is + # forecast. The values specified below are used only if DT_ATMOS is # not explicitly set in the user-specified experiment configuration - # file config.sh. Note that this parameter may be suite dependent. + # file config.sh. Note that this parameter may be suite dependent. if [ "${CCPP_PHYS_SUITE}" = "FV3_GFS_v16" ]; then DT_ATMOS=${DT_ATMOS:-"300"} @@ -180,18 +228,18 @@ The following is an example of a stanza for "NEW_GRID" to be added to ``set_pred # interpolated. The output fields are not specified on the native grid # but are instead remapped to this write-component grid because the # post-processing software (UPP; called during the run_post tasks) is - # not able to process fields on the native grid. The variable + # not able to process fields on the native grid. The variable # "QUILTING", which specifies whether or not to use the # write-component grid, is by default set to "TRUE". if [ "$QUILTING" = "TRUE" ]; then # The number of "groups" of MPI tasks that may be running at any given - # time to write out the output. Each write group will be writing to + # time to write out the output. Each write group will be writing to # one set of output files (a dynf${fhr}.nc and a phyf${fhr}.nc file, - # where $fhr is the forecast hour). Each write group contains + # where $fhr is the forecast hour). Each write group contains # WRTCMP_write_tasks_per_group tasks. Usually, it is sufficient to - # have just one write group. This may need to be increased if the + # have just one write group. This may need to be increased if the # forecast is proceeding so quickly that a single write group cannot # complete writing to its set of files before there is a need/request # to start writing the next set of files at the next output time (this @@ -240,7 +288,7 @@ The following is an example of a stanza for "NEW_GRID" to be added to ``set_pred WRTCMP_lat_lwr_left="23.89394570" # The grid cell sizes along the x and y directions of the - # write-component grid. Units depend on the coordinate system used by + # write-component grid. Units depend on the coordinate system used by # the grid (i.e. the value of WRTCMP_output_grid). For a Lambert # conformal write-component grid, the units are in meters. From d2ca2b8433c73b80d990e15e0ccdc995c87f3436 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 3 May 2022 15:45:32 -0400 Subject: [PATCH 121/158] LAM ch: user-defined grid section --- docs/UsersGuide/source/BuildRunSRW.rst | 1 - docs/UsersGuide/source/LAMGrids.rst | 52 +++++++++++++------------- 2 files changed, 25 insertions(+), 28 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index c08c2b9c28..8d2f324ada 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -124,7 +124,6 @@ Run the executable that pulls in SRW App components from external repositories: ./manage_externals/checkout_externals - Build with ``devbuild.sh`` ========================== diff --git a/docs/UsersGuide/source/LAMGrids.rst b/docs/UsersGuide/source/LAMGrids.rst index 651dd32707..2c81e6cc2f 100644 --- a/docs/UsersGuide/source/LAMGrids.rst +++ b/docs/UsersGuide/source/LAMGrids.rst @@ -1,20 +1,20 @@ .. _LAMGrids: -======================================================================== -Limited Area Model (LAM) Grids: Predefined and User-Generated Options -======================================================================== +================================================================================= +Limited Area Model (:term:`LAM`) Grids: Predefined and User-Generated Options +================================================================================= In order to set up the workflow and generate an experiment with the UFS SRW App, the user must choose between four predefined :term:`FV3`-:term:`LAM` grids or generate a user-defined grid. At this time, full support will only be provided to those using one of the four predefined grids supported in this release. However, preliminary information is provided at the end of this chapter that describes how users can leverage the SRW App workflow scripts to generate their own user-defined grid. Currently, this feature is not fully supported and is -"use at your own risk". +"use at your own risk." Predefined Grids ================= -The UFS SRW App release includes four predefined LAM grids to choose between -prior to generating a workflow/experiment configuration. To select a predefined grid, +The UFS SRW App release includes four predefined limited area model (:term:`LAM`) grids to choose between +prior to configuring an experiment and generating a workflow. To select a predefined grid, the ``PREDEF_GRID_NAME`` variable within the ``config.sh`` script needs to be set to one of the following four options: @@ -59,7 +59,7 @@ The predefined :term:`CONUS` grids follow the naming convention (e.g., RRFS_CONU Predefined 3-km CONUS Grid ----------------------------- -The 3km CONUS domain is ideal for running the ``FV3_RRFS_v1beta`` physics suite, since this suite definition file (:term:`SDF`) was specifically created for convection-allowing scales and is the precursor to the operational physics suite that will be used in the RRFS. The 3-km domain can also be used with the ``FV3_HRRR`` and ``FV3_WoFS`` physics suites, which likewise do not include convective parameterization. In fact, the ``FV3_WoFS`` physics suite is configured to run at 3-km *or less* and could therefore run with even higher-resolution user-defined domains if desired. However, the ``FV3_GFS_v16`` suite generally should *not* be used with the 3-km domain because the cumulus physics used in that physics suite are not configured to run at the 3-km resolution. +The 3km CONUS domain is ideal for running the ``FV3_RRFS_v1beta`` physics suite, since this suite definition file (:term:`SDF`) was specifically created for convection-allowing scales and is the precursor to the operational physics suite that will be used in the RRFS. The 3-km domain can also be used with the ``FV3_HRRR`` and ``FV3_WoFS`` physics suites, which likewise do not include convective parameterization. In fact, the ``FV3_WoFS`` physics suite is configured to run at 3-km *or less* and could therefore run with even higher-resolution user-defined domains if desired. However, the ``FV3_GFS_v16`` suite generally should *not* be used with the 3-km domain because the cumulus physics used in that physics suite is not configured to run at the 3-km resolution. .. _RRFS_CONUS_3km: @@ -82,7 +82,7 @@ Predefined SUBCONUS Grid Over Indianapolis *The boundary of the SUBCONUS_Ind_3km computational grid (red) and corresponding write-component grid (blue).* -The ``SUBCONUS_Ind_3km`` grid covers only a small section of the CONUS over Indianapolis. Like the ``RRFS_CONUS_3km`` grid, it is ideally paired with the ``FV3_RRFS_v1beta``, ``FV3_HRRR``, or ``FV3_WoFS`` physics suites, since these are all convection-allowing physics suites designed to work well on high-resolution grids. +The ``SUBCONUS_Ind_3km`` grid covers only a small section of the :term:`CONUS` over Indianapolis. Like the ``RRFS_CONUS_3km`` grid, it is ideally paired with the ``FV3_RRFS_v1beta``, ``FV3_HRRR``, or ``FV3_WoFS`` physics suites, since these are all convection-allowing physics suites designed to work well on high-resolution grids. Predefined 13-km Grid ------------------------ @@ -93,7 +93,7 @@ Predefined 13-km Grid *The boundary of the RRFS_CONUS_13km computational grid (red) and corresponding write-component grid (blue).* -The ``RRFS_CONUS_13km`` grid (:numref:`Fig. %s `) covers the full :term:`CONUS`. This grid is meant to be run with the ``FV3_GFS_v16`` :term:`SDF`. The ``FV3_GFS_v16`` physics suite uses convective :term:`parameterizations`, whereas the other supported suites do not. Convective parameterizations are necessary for low-resolution grids because convection occurs on scales smaller than 25km and 13km. +The ``RRFS_CONUS_13km`` grid (:numref:`Fig. %s `) covers the full :term:`CONUS`. This grid is meant to be run with the ``FV3_GFS_v16`` physics suite. The ``FV3_GFS_v16`` physics suite uses convective :term:`parameterizations`, whereas the other supported suites do not. Convective parameterizations are necessary for low-resolution grids because convection occurs on scales smaller than 25km and 13km. Predefined 25-km Grid ------------------------ @@ -106,9 +106,9 @@ Predefined 25-km Grid The final predefined :term:`CONUS` grid (:numref:`Fig. %s `) uses a 25-km resolution and is meant mostly for quick testing to ensure functionality prior to using a higher-resolution domain. -However, for users who would like to use this domain for research, the ``FV3_GFS_v16`` SDF is recommended for the reasons mentioned above. +However, for users who would like to use the 25-km domain for research, the ``FV3_GFS_v16`` :term:`SDF` is recommended for the reasons mentioned above. -Ultimately, the choice of grid is experiment-dependent and resource-dependent. For example, a user may wish to use the ``FV3_GFS_v16`` physics suite definition file (:term:`SDF`), which uses cumulus physics that are not configured to run at the 3-km resolution. In this case, the 13-km or 25-km domain options are better suited to the experiment. Users will also have fewer computational constraints when running with the 13-km and 25-km domains, so depending on the resources available to them, certain grids may be better options than others. +Ultimately, the choice of grid is experiment-dependent and resource-dependent. For example, a user may wish to use the ``FV3_GFS_v16`` physics suite, which uses cumulus physics that are not configured to run at the 3-km resolution. In this case, the 13-km or 25-km domain options are better suited to the experiment. Users will also have fewer computational constraints when running with the 13-km and 25-km domains, so depending on the resources available to them, certain grids may be better options than others. Creating User-Generated Grids =============================== @@ -116,39 +116,37 @@ While the four predefined grids available in this release are ideal for users ju out with the SRW App, more advanced users may wish to create their own grid for testing over a different region and/or with a different resolution. Creating a user-defined grid requires knowledge of how the SRW App workflow functions. In particular, it is important to understand the set of -scripts that handle the workflow and experiment generation. It is also important to note that -user-defined grids are not a supported feature of the current release; however, information is -being provided for the benefit of the FV3-LAM community. +scripts that handle the workflow and experiment generation (see :numref:`Figure %s ` and :numref:`Figure %s `). It is also important to note that user-defined grids are not a supported feature of the current release; however, information is being provided for the benefit of the FV3-LAM community. With those caveats in mind, this section provides instructions for adding a new grid to the FV3-LAM workflow that will be generated using the "ESGgrid" method (i.e., using the regional_esg_grid code -in the UFS_UTILS repository, where ESG stands for "Extended Schmidt Gnomonic"). We assume here -that the grid to be generated covers a domain that (1) does not contain either of the poles and -(2) does not cross the -180 deg --> +180 deg discontinuity in longitude near the international -date line. Instructions for domains that do not have these restrictions will be provided in a future release. +in the `UFS_UTILS `__ repository, where ESG stands for "Extended Schmidt Gnomonic"). We assume here that the grid to be generated covers a domain that (1) does not contain either of the poles and (2) does not cross the -180 deg --> +180 deg discontinuity in longitude near the international date line. Instructions for domains that do not have these restrictions will be provided in a future release. The steps to add such a grid to the workflow are as follows: -#. Decide on the name of the grid. For the purposes of this documentation, the grid will be called "NEW_GRID". +#. Choose the name of the grid. For the purposes of this documentation, the grid will be called "NEW_GRID". #. Add NEW_GRID to the array ``valid_vals_PREDEF_GRID_NAME`` in the ``ufs-srweather-app/regional_workflow/ush/valid_param_vals.sh`` file. -#. In the file ``ufs-srweather-app/regional_workflow/ush/set_predef_grid_params.sh``, add a stanza to - the case statement ``case ${PREDEF_GRID_NAME} in`` for NEW_GRID. An example of such a stanza - is given below along with comments describing the variables that need to be set. +#. In ``ufs-srweather-app/regional_workflow/ush/set_predef_grid_params.sh``, add a stanza to + the case statement ``case ${PREDEF_GRID_NAME} in`` for NEW_GRID. An example of such a stanza + is given :ref:`below ` along with comments describing the variables that need to be set. -To run a forecast experiment on NEW_GRID, start with a workflow configuration file for a successful -experiment (this file is named ``config.sh`` and is located in the directory -``ufs-srweather-app/regional_workflow/ush``) and change the line for ``PREDEF_GRID_NAME`` to the following: +To run a forecast experiment on NEW_GRID, start with a workflow configuration file for a successful experiment (e.g., ``config.sh``, located in the ``ufs-srweather-app/regional_workflow/ush`` subdirectory), and change the line for ``PREDEF_GRID_NAME`` to the following: .. code-block:: console PREDEF_GRID_NAME="NEW_GRID" -Then, generate a new experiment/workflow using ``generate_FV3LAM_wflow.sh`` in the usual way. +Then, generate a new experiment/workflow using ``generate_FV3LAM_wflow.sh`` in the :ref:`usual way `. -The following is an example of a stanza for "NEW_GRID" to be added to ``set_predef_grid_params.sh``: +Code Example +--------------- + +The following is an example of a code stanza for "NEW_GRID" to be added to ``set_predef_grid_params.sh``: + +.. _NewGridExample: .. code-block:: console From a707fc16c1f55ea3aa6d243a216a57d24b42c451 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 3 May 2022 17:20:28 -0400 Subject: [PATCH 122/158] add UPP Product tables ch 6 --- docs/UsersGuide/source/InputOutputFiles.rst | 6 +++++- docs/UsersGuide/source/_static/custom.css | 23 +++++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index cfda134b60..4b67321f5c 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -171,13 +171,17 @@ For the SRW Application, the weather model netCDF output files are written to th * ``BGRD3D_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgrd3df{fhr}.tmXX.grib2`` * ``BGDAWP_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgdawpf{fhr}.tmXX.grib2`` -The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by the user in the ``config.sh`` settings. +The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by the user in the ``config.sh`` settings. If you wish to modify the fields or levels that are output from the UPP, you will need to make modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. .. note:: 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 ` + Use the directions in the `UPP User's Guide `__ for details on how to make modifications to the ``fv3lam.xml`` file and for remaking the flat text file that the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default). Once you have created the new flat text file reflecting your changes, you will need to modify your diff --git a/docs/UsersGuide/source/_static/custom.css b/docs/UsersGuide/source/_static/custom.css index 25f207a223..118fc5d684 100644 --- a/docs/UsersGuide/source/_static/custom.css +++ b/docs/UsersGuide/source/_static/custom.css @@ -4,3 +4,26 @@ font-weight: bold; font-style: italic; } + +.underline { + text-decoration: underline; +} + +.bolditalic { + font-weight: bold; + font-style: italic; +} + +td { + word-break: break-all; +} + +table.align-default { + margin-left: 0px; + margin-right: auto; +} + +table.align-center { + margin-left: 0px; + margin-right: auto; +} From b48d495fe7478b130916d556eda43e746ec6def2 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 4 May 2022 12:26:55 -0400 Subject: [PATCH 123/158] I/O edits & glossary terms --- docs/UsersGuide/source/Glossary.rst | 10 ++ docs/UsersGuide/source/InputOutputFiles.rst | 100 ++++++++++---------- docs/UsersGuide/source/LAMGrids.rst | 2 +- docs/UsersGuide/source/_static/custom.css | 4 - 4 files changed, 61 insertions(+), 55 deletions(-) diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index a9fd13e5ba..d0fd69a620 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -6,6 +6,12 @@ Glossary .. glossary:: + advect + To transport substances in the atmostphere by :term:`advection`. + + advection + According to the American Meteorological Society (AMS) `definition `__, advection is "The process of transport of an atmospheric property solely by the mass motion (velocity field) of the atmosphere." In common parlance, advection is movement of atmospheric substances that are carried around by the wind. + CCPA Climatology-Calibrated Precipitation Analysis (CCPA) data. This data is required for use of the METplus verification suite within the SRW App. The most recent 8 days worth of data are publicly available and can be accessed `here `__. @@ -158,6 +164,10 @@ Glossary SDF Suite Definition File. An external file containing information about the construction of a physics suite. It describes the schemes that are called, in which order they are called, whether they are subcycled, and whether they are assembled into groups to be called together. + 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 The Unified Forecast System is a community-based, coupled comprehensive Earth modeling system consisting of several applications (apps). These apps span regional to global diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 4b67321f5c..2deed4f3ae 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -4,7 +4,7 @@ Input and Output Files ======================= This chapter provides an overview of the input and output files needed by the components -of the UFS SRW Application (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`). Links to more detailed documentation for each of the components are provided. For SRW App users who want to jump straight to downloading and staging the files, see :numref:`Section %s `. +of the UFS SRW Application. Links to more detailed documentation for each of the components (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`) are provided in the sections below. For SRW App users who want to jump straight to downloading and staging the files, see :numref:`Section %s `. .. _Input: @@ -16,21 +16,21 @@ conditions files, and model configuration files (such as namelists). Initial and Boundary Condition Files ------------------------------------ -The external model files needed for initializing the runs can be obtained in a number of -ways, including: pulled directly from `NOMADS `_; -limited data availability), pulled from the NOAA HPSS during the workflow execution (requires +The external model files needed for initializing an experiment can be obtained in a number of +ways, including: pulled directly from `NOMADS `_, +(limited data availability), pulled from the NOAA HPSS system during the workflow execution (requires user access), or obtained and staged by the user from a different source. The data format for these files can be :term:`GRIB2` or :term:`NEMSIO`. More information on downloading and setting up the external model data can be found in :numref:`Section %s `. Once the data is set up, the end-to-end application will run the system and write output files to disk. Pre-processing (UFS_UTILS) -------------------------- -When a user runs the SRW Application as described in the Quick Start Guide :numref:`Chapter %s `, :numref:`Step %s Generate the Forecast Experiment ` links the input data for the pre-processing utilities from a location on disk to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found `here `__. +When a user runs the SRW Application as described in the Quick Start Guide, :numref:`Step %s `, the workflow generation script links the input data for the pre-processing utilities from a location on disk to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found in the `UFS_UTILS Documentation `__. UFS Weather Model ----------------- -The input files for the weather model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix files -must be staged by the user unless you are running on a Level 1/pre-configured platform, in which case you can link to the existing copy of the data on that machine. See :numref:`Section %s ` for more information. The static, grid, and date-specific files are linked in the experiment directory by the workflow scripts. An extensive description of the input files for the weather model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow, as described in :numref:`Section %s `. +The input files for the Weather Model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix files +must be staged by the user unless the user is running on a `Level 1/pre-configured `__ platform, in which case users can link to the existing copy of the data on that machine. See :numref:`Section %s ` for more information. The workflow scripts link the static, grid, and date-specific files in the experiment directory. An extensive description of the input files for the weather model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow generation script, as described in :numref:`Section %s `. Unified Post Processor (UPP) ---------------------------- @@ -42,8 +42,7 @@ Documentation for the UPP input files can be found in the `UPP User's Guide Workflow -------- The SRW Application uses a series of template files, combined with user-selected settings, -to create the required namelists and parameter files needed by the Application. These -templates can be reviewed to see what defaults are being used and where configuration parameters from the ``config.sh`` file are assigned. +to create the required namelists and parameter files needed by the Application (see :numref:`Table %s `). These templates can be reviewed to see which defaults are used and where configuration parameters from the ``config.sh`` file are assigned. List of Template Files ^^^^^^^^^^^^^^^^^^^^^^ @@ -52,47 +51,48 @@ and are shown in :numref:`Table %s `. .. _TemplateFiles: -.. table:: Template Files for a Regional Workflow - - +-----------------------------+-------------------------------------------------------------+ - | **File Name** | **Description** | - +=============================+=============================================================+ - | data_table | Cycle-independent file that the forecast model reads in at | - | | the start of each forecast. It is an empty file. No need to | - | | change. | - +-----------------------------+-------------------------------------------------------------+ - | diag_table_[CCPP] | File specifying the output fields of the forecast model. | - | | A different diag_table may be configured for different | - | | CCPP suites. | - +-----------------------------+-------------------------------------------------------------+ - | field_table_[CCPP] | Cycle-independent file that the forecast model reads in at | - | | the start of each forecast. It specifies the tracers that | - | | the forecast model will 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 | - | | specified in this file update the corresponding values in | - | | the ``input.nml`` file. This file may be modified for the | - | | specific namelist options of your experiment. | - +-----------------------------+-------------------------------------------------------------+ - | FV3LAM_wflow.xml | Rocoto XML file to run the workflow. It is filled in using | - | | the ``fill_template.py`` python script that is called in | - | | the ``generate_FV3LAM_wflow.sh``. | - +-----------------------------+-------------------------------------------------------------+ - | input.nml.FV3 | Namelist file of the weather model. | - +-----------------------------+-------------------------------------------------------------+ - | model_configure | Settings and configurations for the NUOPC/ESMF main | - | | component. | - +-----------------------------+-------------------------------------------------------------+ - | nems.configure | NEMS (NOAA Environmental Modeling System) configuration | - | | file, no need to change because it is an atmosphere-only | - | | model in the SRW Application. | - +-----------------------------+-------------------------------------------------------------+ - | regional_grid.nml | Namelist settings for the code that generates an ESG grid. | - +-----------------------------+-------------------------------------------------------------+ - | README.xml_templating.md | Instruction of Rocoto XML templating with Jinja. | - +-----------------------------+-------------------------------------------------------------+ +.. table:: Template Files for the Regional Workflow + + +-----------------------------+--------------------------------------------------------------+ + | **File Name** | **Description** | + +=============================+==============================================================+ + | data_table | :term:`Cycle-independent` file that the forecast model | + | | reads in at the start of each forecast. It is an empty file. | + | | No need to change. | + +-----------------------------+--------------------------------------------------------------+ + | diag_table_[CCPP] | File specifying the output fields of the forecast model. | + | | A different ``diag_table`` may be configured for different | + | | CCPP suites. | + +-----------------------------+--------------------------------------------------------------+ + | 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. | + +-----------------------------+--------------------------------------------------------------+ + | FV3.input.yml | YAML configuration file containing the forecast model’s | + | | namelist settings for various physics suites. The values | + | | specified in this file update the corresponding values in | + | | the ``input.nml`` file. This file may be modified for the | + | | specific namelist options of your experiment. | + +-----------------------------+--------------------------------------------------------------+ + | FV3LAM_wflow.xml | Rocoto XML file to run the workflow. It is filled in using | + | | the ``fill_template.py`` python script that is called in | + | | the ``generate_FV3LAM_wflow.sh``. | + +-----------------------------+--------------------------------------------------------------+ + | input.nml.FV3 | Namelist file for the Weather Model. | + +-----------------------------+--------------------------------------------------------------+ + | model_configure | Settings and configurations for the NUOPC/ESMF main | + | | component. | + +-----------------------------+--------------------------------------------------------------+ + | nems.configure | NEMS (NOAA Environmental Modeling System) configuration | + | | file, no need to change because it is an atmosphere-only | + | | model in the SRW Application. | + +-----------------------------+--------------------------------------------------------------+ + | regional_grid.nml | Namelist settings for the code that generates an ESG grid. | + +-----------------------------+--------------------------------------------------------------+ + | README.xml_templating.md | Instructions for Rocoto XML templating with Jinja. | + +-----------------------------+--------------------------------------------------------------+ Additional information related to the ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``, ``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, while information on the ``regional_grid.nml`` can be found in the `UFS_UTILS User’s Guide diff --git a/docs/UsersGuide/source/LAMGrids.rst b/docs/UsersGuide/source/LAMGrids.rst index 2c81e6cc2f..39a30a1372 100644 --- a/docs/UsersGuide/source/LAMGrids.rst +++ b/docs/UsersGuide/source/LAMGrids.rst @@ -106,7 +106,7 @@ Predefined 25-km Grid The final predefined :term:`CONUS` grid (:numref:`Fig. %s `) uses a 25-km resolution and is meant mostly for quick testing to ensure functionality prior to using a higher-resolution domain. -However, for users who would like to use the 25-km domain for research, the ``FV3_GFS_v16`` :term:`SDF` is recommended for the reasons mentioned above. +However, for users who would like to use the 25-km domain for research, the ``FV3_GFS_v16`` :term:`SDF` is recommended for the reasons mentioned :ref:`above `. Ultimately, the choice of grid is experiment-dependent and resource-dependent. For example, a user may wish to use the ``FV3_GFS_v16`` physics suite, which uses cumulus physics that are not configured to run at the 3-km resolution. In this case, the 13-km or 25-km domain options are better suited to the experiment. Users will also have fewer computational constraints when running with the 13-km and 25-km domains, so depending on the resources available to them, certain grids may be better options than others. diff --git a/docs/UsersGuide/source/_static/custom.css b/docs/UsersGuide/source/_static/custom.css index 118fc5d684..c02df7fed2 100644 --- a/docs/UsersGuide/source/_static/custom.css +++ b/docs/UsersGuide/source/_static/custom.css @@ -14,10 +14,6 @@ font-style: italic; } -td { - word-break: break-all; -} - table.align-default { margin-left: 0px; margin-right: auto; From 2477527f0d8b8248b9d641dc2873dffc5293b357 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 4 May 2022 20:56:57 -0400 Subject: [PATCH 124/158] I/O Pt2 --- docs/UsersGuide/source/ConfigWorkflow.rst | 3 +- docs/UsersGuide/source/Glossary.rst | 9 +++ docs/UsersGuide/source/InputOutputFiles.rst | 67 +++++++++++---------- docs/UsersGuide/source/LAMGrids.rst | 3 +- 4 files changed, 48 insertions(+), 34 deletions(-) diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index 15754c1265..b4d006a695 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -819,7 +819,7 @@ Predefined Grid Parameters | "RRFS_CONUS_25km" | "RRFS_CONUS_13km" | "RRFS_CONUS_3km" - | "RRFS_SUBCONUS_3km" + | "SUBCONUS_Ind_3km" **Other valid values include:** @@ -837,6 +837,7 @@ Predefined Grid Parameters | "GSD_HRRR_AK_50km" | "RRFS_NA_13km" | "RRFS_NA_3km" + | "RRFS_SUBCONUS_3km" .. COMMENT: Are all of these now being supported or still just the three main ones? Am I missing any? diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index d0fd69a620..4274df7981 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -59,9 +59,15 @@ Glossary echo top The radar-indicated top of an area of precipitation. Specifically, it contains the height of the 18 dBZ reflectivity value. + EMC + The `Environmental Modeling Center `__. + EPIC EPIC stands for the `Earth Prediction Innovation Center `__. EPIC seeks to accelerate scientific research and modeling contributions through continuous and sustained community engagement to produce the most accurate and reliable operational modeling system in the world. + ESG + Extended Schmidt Gnomonic (ESG) grid. The ESG grid uses the map projection developed by Jim Purser of NOAA :term:`EMC` (:cite:t:`Purser_2020`). + ESMF `Earth System Modeling Framework `__. The ESMF defines itself as “a suite of software tools for developing high-performance, multi-component Earth science modeling applications.” @@ -142,6 +148,9 @@ Glossary NEMSIO A binary format for atmospheric model output from :term:`NCEP`'s Global Forecast System (GFS). + netCDF + NetCDF (Network Common Data Form) is a file format and community standard for storing multidimensional scientific data. It includes a set of software libraries and machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data (see https://www.unidata.ucar.edu/software/netcdf/). + NUOPC The `National Unified Operational Prediction Capability `__ Layer "defines conventions and a set of generic components for building coupled models using the Earth System Modeling Framework (:term:`ESMF`)." diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 2deed4f3ae..5199e3418c 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -4,7 +4,7 @@ Input and Output Files ======================= This chapter provides an overview of the input and output files needed by the components -of the UFS SRW Application. Links to more detailed documentation for each of the components (i.e., :term:`UFS_UTILS`, the UFS :term:`Weather Model`, and the :term:`UPP`) are provided in the sections below. For SRW App users who want to jump straight to downloading and staging the files, see :numref:`Section %s `. +of the UFS SRW Application. Links to more detailed documentation for each of the components (e.g., UFS_UTILS, the UFS Weather Model, and the UPP) are provided in the sections below. For SRW App users who want to jump straight to downloading and staging the files, see :numref:`Section %s `. .. _Input: @@ -17,20 +17,22 @@ conditions files, and model configuration files (such as namelists). Initial and Boundary Condition Files ------------------------------------ The external model files needed for initializing an experiment can be obtained in a number of -ways, including: pulled directly from `NOMADS `_, -(limited data availability), pulled from the NOAA HPSS system during the workflow execution (requires -user access), or obtained and staged by the user from a different source. The data format for -these files can be :term:`GRIB2` or :term:`NEMSIO`. More information on downloading and setting up -the external model data can be found in :numref:`Section %s `. Once the data is set up, the end-to-end application will run the system and write output files to disk. +ways, including: + + * pulled directly from `NOMADS `_ (limited data availability), + * pulled from the NOAA High Performance Storage System (HPSS) during the workflow execution (requires user access), or + * obtained and staged by the user from a different source. + +The data format for these files can be :term:`GRIB2` or :term:`NEMSIO`. More information on downloading and setting up the external model data can be found in :numref:`Section %s `. Once the data is set up, the end-to-end application will run the system and write output files to disk. Pre-processing (UFS_UTILS) -------------------------- -When a user runs the SRW Application as described in the Quick Start Guide, :numref:`Step %s `, the workflow generation script links the input data for the pre-processing utilities from a location on disk to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found in the `UFS_UTILS Documentation `__. +When a user generates the regional workflow, as described in :numref:`Step %s ` of the Quick Start Guide, the workflow generation script links the input data for the pre-processing utilities to the experiment directory. The pre-processing utilities use many different datasets to create grids and to generate model input datasets from the external model files. A detailed description of the input files for the pre-processing utilities can be found in the `UFS_UTILS Documentation `__. UFS Weather Model ----------------- The input files for the Weather Model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix files -must be staged by the user unless the user is running on a `Level 1/pre-configured `__ platform, in which case users can link to the existing copy of the data on that machine. See :numref:`Section %s ` for more information. The workflow scripts link the static, grid, and date-specific files in the experiment directory. An extensive description of the input files for the weather model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow generation script, as described in :numref:`Section %s `. +must be staged by the user unless the user is running on a `Level 1/pre-configured `__ platform, in which case users can link to the existing copy of the data on their machine. See :numref:`Section %s ` for instructions. The workflow scripts link the static, grid, and date-specific files in the experiment directory. An extensive description of the input files for the Weather Model can be found in the `UFS Weather Model User's Guide `__. The namelists and configuration files for the SRW Application are created from templates by the workflow generation script, as described in :numref:`Section %s `. Unified Post Processor (UPP) ---------------------------- @@ -42,7 +44,7 @@ Documentation for the UPP input files can be found in the `UPP User's Guide Workflow -------- The SRW Application uses a series of template files, combined with user-selected settings, -to create the required namelists and parameter files needed by the Application (see :numref:`Table %s `). These templates can be reviewed to see which defaults are used and where configuration parameters from the ``config.sh`` file are assigned. +to create the required namelists and parameter files needed by the Application workflow. (See :numref:`Figure %s ` for a visual summary of the workflow generation process, including template use.) These templates can be reviewed to see which defaults are used and where configuration parameters from the ``config.sh`` file are assigned. List of Template Files ^^^^^^^^^^^^^^^^^^^^^^ @@ -62,7 +64,7 @@ and are shown in :numref:`Table %s `. +-----------------------------+--------------------------------------------------------------+ | diag_table_[CCPP] | File specifying the output fields of the forecast model. | | | A different ``diag_table`` may be configured for different | - | | CCPP suites. | + | | :term:`CCPP` suites. | +-----------------------------+--------------------------------------------------------------+ | field_table_[CCPP] | :term:`Cycle-independent` file that the forecast model | | | reads in at the start of each forecast. It specifies the | @@ -78,44 +80,45 @@ and are shown in :numref:`Table %s `. +-----------------------------+--------------------------------------------------------------+ | FV3LAM_wflow.xml | Rocoto XML file to run the workflow. It is filled in using | | | the ``fill_template.py`` python script that is called in | - | | the ``generate_FV3LAM_wflow.sh``. | + | | ``generate_FV3LAM_wflow.sh``. | +-----------------------------+--------------------------------------------------------------+ | input.nml.FV3 | Namelist file for the Weather Model. | +-----------------------------+--------------------------------------------------------------+ - | model_configure | Settings and configurations for the NUOPC/ESMF main | - | | component. | + | model_configure | Settings and configurations for the | + | | :term:`NUOPC`/:term:`ESMF` main component. | +-----------------------------+--------------------------------------------------------------+ - | nems.configure | NEMS (NOAA Environmental Modeling System) configuration | - | | file, no need to change because it is an atmosphere-only | - | | model in the SRW Application. | + | nems.configure | :term:`NEMS` (NOAA Environmental Modeling System) | + | | configuration file. No need to change because it is an | + | | atmosphere-only model in the SRW Application. | +-----------------------------+--------------------------------------------------------------+ - | regional_grid.nml | Namelist settings for the code that generates an ESG grid. | + | regional_grid.nml | Namelist settings for the code that generates an :term:`ESG` | + | | grid. | +-----------------------------+--------------------------------------------------------------+ | README.xml_templating.md | Instructions for Rocoto XML templating with Jinja. | +-----------------------------+--------------------------------------------------------------+ -Additional information related to the ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``, ``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, -while information on the ``regional_grid.nml`` can be found in the `UFS_UTILS User’s Guide +Additional information related to ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``, ``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, +while information on ``regional_grid.nml`` can be found in the `UFS_UTILS User’s Guide `_. Migratory Route of the Input Files in the Workflow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:numref:`Figure %s ` shows how the case-specific input files in the -``ufs-srweather-app/regional_workflow/ush/templates/`` directory flow to the experiment directory. The value of ``CCPP_PHYS_SUITE`` is specified in the configuration file ``config.sh``. The template input files corresponding to ``CCPP_PHYS_SUITE``, such as ``field_table`` and ``nems_configure``, are copied to the experiment directory ``EXPTDIR``, and the namelist file of the weather model ``input.nml`` is created from the ``input.nml.FV3`` and ``FV3.input.yml`` files by running the script ``generate_FV3LAM_wflow.sh``. While running the task ``RUN_FCST`` in the regional workflow as shown in :numref:`Figure %s `, the ``field_table``, ``nems.configure``, and ``input.nml`` files, located in ``EXPTDIR``, are linked to the cycle directory ``CYCLE_DIR/``. Additionally, ``diag_table`` and ``model_configure`` are copied from the ``templates`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. +:numref:`Figure %s ` shows how the input files in the template directory (``ufs-srweather-app/regional_workflow/ush/templates/``) flow to the experiment directory. First, the CCPP physics suite is specified in the configuration file. The template input files corresponding to the selected physics suite, such as ``field_table_[CCPP]`` and ``nems.configure_[CCPP]``, are copied to the experiment directory (``$EXPTDIR``). Additionally, the namelist file of the Weather Model (``input.nml``) is created from the ``input.nml.FV3`` and ``FV3.input.yml`` files by running the workflow generation script. While running the ``RUN_FCST`` task in the regional workflow as shown in :numref:`Figure %s `, the ``field_table``, ``nems.configure``, and ``input.nml`` files, located in ``$EXPTDIR``, are linked to the cycle directory ``$CYCLE_DIR``. Additionally, ``diag_table`` and ``model_configure`` are copied from the ``templates`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. .. _MigratoryRoute: .. figure:: _static/FV3LAM_wflow_input_path.png + :alt: Flowchart showing how information on the physics suite travels from the config shell file to the setup shell file to the workflow generation script to the run forecast ex-script. As this information is fed from one script to the next, file paths and variables required for workflow execution are set. - *Migratory route of input files* + *Migratory route of input files* .. _OutputFiles: Output Files ============ -The location of the output files written to disk is defined by the experiment directory, -``EXPTDIR/YYYYMMDDHH``, as set in ``config.sh``. +The location of the output files written to disk is within a subdirectory of the experiment directory, +``EXPTDIR/YYYYMMDDHH``, named based on the settings in ``config.sh``. Initial and boundary condition files ------------------------------------ @@ -137,7 +140,7 @@ experiment run directory ``EXPTDIR/YYYYMMDDHH/INPUT`` and consist of the followi * ``oro_data.nc -> ../../orog/C403_oro_data.tile7.halo0.nc`` * ``sfc_data.nc -> sfc_data.tile7.halo0.nc`` -These output files are used as inputs for the UFS weather model, and are described in the `Users Guide +These output files are used as inputs for the UFS Weather Model, and are described in the `UFS Weather Model Users Guide `__. .. @@ -145,32 +148,32 @@ These output files are used as inputs for the UFS weather model, and are describ UFS Weather Model ----------------- -As mentioned previously, the workflow can be run in ‘community’ or ‘nco’ mode, which determines -the location and names of the output files. In addition to this option, output can also be in -netCDF or NEMSIO format. The output file format is set in the ``model_configure`` files using the -``output_file`` variable. At this time, due to limitations in the post-processing component, only netCDF format output is recommended for the SRW Application. +As stated in :numref:`Section %s `, the workflow can be run in ‘community’ or ‘nco’ mode, which determines the location and names of the output files. Weather Model output files can also be in :term:`netCDF` or :term:`NEMSIO` format. The output file format is set in the ``model_configure`` file (see :numref:`Table %s `) using the ``output_file`` variable. At this time, due to limitations in the post-processing component, only netCDF output is recommended for the SRW Application. .. note:: - In summary, the fully supported options for this release include running in ‘community’ mode with netCDF format output files. + The fully supported options for this release include running in ‘community’ mode with netCDF-formatted output files. In this case, the netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH`` directory. The bases of the file names are specified in the input file ``model_configure`` and are set to the following in the SRW Application: * ``dynfHHH.nc`` * ``phyfHHH.nc`` -Additional details may be found in the UFS Weather Model `Users Guide +Additional details may be found in the `UFS Weather Model User's Guide `__. Unified Post Processor (UPP) ---------------------------- -Documentation for the UPP output files can be found `here `__. +Documentation for the UPP output files can be found in the `UPP User's Guide `__. For the SRW Application, the weather model netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH/postprd`` directory and have the naming convention (file->linked to): * ``BGRD3D_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgrd3df{fhr}.tmXX.grib2`` * ``BGDAWP_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgdawpf{fhr}.tmXX.grib2`` +.. + Is this still accurate? Or have the directories changed to, e.g., NATLEV and PRSLEV? + The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by the user in the ``config.sh`` settings. If you wish to modify the fields or levels that are output from the UPP, you will need to make modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. diff --git a/docs/UsersGuide/source/LAMGrids.rst b/docs/UsersGuide/source/LAMGrids.rst index 39a30a1372..ddbdb0fa8b 100644 --- a/docs/UsersGuide/source/LAMGrids.rst +++ b/docs/UsersGuide/source/LAMGrids.rst @@ -78,7 +78,8 @@ Predefined SUBCONUS Grid Over Indianapolis .. _SUBCONUS_Ind_3km: -.. figure:: _static/SUBCONUS_Ind_3km.sphr.native_wrtcmp.png +.. figure:: _static/SUBCONUS_Ind_3km.png + :alt: Map of Indiana and portions of the surrounding states. The map shows the boundaries of the continental United States sub-grid centered over Indianapolis. The computational grid boundaries appear in red and the write-component grid appears just inside it in blue. *The boundary of the SUBCONUS_Ind_3km computational grid (red) and corresponding write-component grid (blue).* From 7ca1e52fdb162eda4065b769f62e4a39f0b4d0d6 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 5 May 2022 11:16:41 -0400 Subject: [PATCH 125/158] I/O changes --- docs/UsersGuide/source/InputOutputFiles.rst | 38 ++++++++++----------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 5199e3418c..0a8077943c 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -168,15 +168,12 @@ Documentation for the UPP output files can be found in the `UPP User's Guide linked to): -* ``BGRD3D_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgrd3df{fhr}.tmXX.grib2`` -* ``BGDAWP_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.bgdawpf{fhr}.tmXX.grib2`` - -.. - Is this still accurate? Or have the directories changed to, e.g., NATLEV and PRSLEV? +* ``NATLEV_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.natlevf{fhr}.tmXX.grib2`` +* ``PRSLEV_{YY}{JJJ}{hh}{mm}f{fhr}00 -> {domain}.t{cyc}z.prslevf{fhr}.tmXX.grib2`` The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by the user in the ``config.sh`` settings. -If you wish to modify the fields or levels that are output from the UPP, you will need to make modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. +If users wish to modify the fields or levels that are output from the UPP, they will need to make modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. .. note:: This process requires advanced knowledge of which fields can be output for the UFS Weather Model. @@ -197,7 +194,7 @@ Once you have created the new flat text file reflecting your changes, you will n which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If this is set to true and the file path is not found, then an error will occur when trying to generate the SRW Application workflow. -You may then start your case workflow as usual and the UPP will use the new flat ``*.txt`` file. +Users may then start their experiment workflow as usual and the UPP will use the new flat ``*.txt`` file. .. _DownloadingStagingInput: @@ -210,26 +207,29 @@ A set of input files, including static (fix) data and raw initial and lateral bo Static Files ------------ The environment variables ``FIXgsm``, ``TOPO_DIR``, and ``SFC_CLIMO_INPUT_DIR`` indicate the path to -the directories where the static files are located. If you are on a pre-configured or configurable platform (i.e., a Level 1 or 2 platform), there is no need to stage the fixed files manually because they have been prestaged, and the paths are set in ``regional_workflow/ush/setup.sh``. On Level 3 & 4 systems, the static files can be downloaded individually or as a full tar file from the `FTP data repository `__ or from `Amazon Web Services (AWS) cloud storage `__ using the ``wget`` command. Then ``tar -xf `` will extract the compressed file: +the directories where the static files are located. If users are on a pre-configured or configurable platform (i.e., a Level 1 or 2 platform), there is no need to stage the fixed files manually because they have been prestaged, and the paths are set in ``regional_workflow/ush/setup.sh``. On Level 3 & 4 systems, the static files can be downloaded individually or as a full tar file from the `FTP data repository `__ or from `Amazon Web Services (AWS) cloud storage `__ using the ``wget`` command. Then the ``tar`` command will extract the compressed file: .. code-block:: console wget https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/fix/fix_files.tar.gz tar -xf fix_files.tar.gz -The paths to the staged files must then be set in ``config.sh``. Add the following code or alter the variable paths if they are already listed in the ``config.sh`` file: +The paths to the files must then be set in ``config.sh``. Add the following code or alter the variable paths if they are already listed in the ``config.sh`` file: -* ``FIXgsm=/path-to/fix/fix_am`` -* ``TOPO_DIR=/path-to/fix/fix_am/fix_orog`` -* ``SFC_CLIMO_INPUT_DIR=/path-to/fix_am/fix/sfc_climo/`` +* ``FIXgsm="/path-to/fix/fix_am"`` +* ``TOPO_DIR="/path-to/fix/fix_am/fix_orog"`` +* ``SFC_CLIMO_INPUT_DIR="/path-to/fix_am/fix/sfc_climo/"`` .. _InitialConditions: Initial Condition Formats and Source ------------------------------------ -The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, netCDF, or :term:`GRIB2`. The SRW Application currently only supports the use of NEMSIO and netCDF input files from the GFS. +The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. However, the SRW Application currently only supports the use of NEMSIO and netCDF input files from the GFS. -The data required to run the "out-of-the-box" SRW App case described in :numref:`Chapter %s ` is already preinstalled on `Level 1 `__ systems. Users on other systems can find the required IC/LBC data in the `FTP data repository `__ or on `AWS cloud storage `_. +.. + COMMENT: So in reality, does this mean that only 2 formats are supported? + +The data required to run the "out-of-the-box" SRW App case described in Chapters :numref:`%s ` and :numref:`%s ` is already preinstalled on `Level 1 `__ systems. Users on Level 3 & 4 systems can find the required IC/LBC data in the `FTP data repository `__ or on `AWS cloud storage `_. To add this data to your system, run the following commands from the ``ufs-srweather-app`` directory: @@ -251,18 +251,18 @@ Then, in ``config.sh``, set the following environment variables: .. code-block:: console - USE_USER_STAGED_EXTRN_FILES=TRUE - EXTRN_MDL_SOURCE_BASEDIR_ICS= - EXTRN_MDL_SOURCE_BASEDIR_LBCS= + USE_USER_STAGED_EXTRN_FILES="TRUE" + EXTRN_MDL_SOURCE_BASEDIR_ICS="" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="" -These environment variables describe what :term:`IC/LBC` files to use (pre-staged files or files to be automatically pulled from the NOAA HPSS) and the location of the IC/LBC files. ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` is the directory where the initial conditions are located, and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` is the directory where the lateral boundary conditions are located. +These environment variables describe which :term:`IC/LBC` files to use (pre-staged files or files to be automatically pulled from NOAA HPSS) and the location of the IC/LBC files. ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` is the directory where the initial conditions are located, and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` is the directory where the lateral boundary conditions are located. Initial and Lateral Boundary Condition Organization --------------------------------------------------- The suggested directory structure and naming convention for the raw input files is described below. While there is flexibility to modify these settings, this will provide the most reusability for multiple dates when using the SRW Application workflow. -For ease of reusing the ``config.sh`` for multiple dates and cycles, it is recommended to set up your raw :term:`IC/LBC` files such that it includes the model name (e.g., FV3GFS, NAM, RAP, HRRR) and ``YYYYMMDDHH``, for example: ``/path-to/model_data/FV3GFS/2019061518``. Since both initial and lateral boundary condition files are necessary, you can also include an ICS and LBCS directory. The sample IC/LBC's available at the FTP data repository are structured as follows: +For ease of reusing the ``config.sh`` for multiple dates and cycles, it is recommended to set up the raw :term:`IC/LBC` files such that they includes the model name (e.g., FV3GFS, NAM, RAP, HRRR) and ``YYYYMMDDHH``, for example: ``/path-to/model_data/FV3GFS/2019061518``. Since both initial and lateral boundary condition files are necessary, you can also include an ICS and LBCS directory. The sample IC/LBC's available at the FTP data repository are structured as follows: * ``/path-to/model_data/MODEL/YYYYMMDDHH/ICS`` * ``/path-to/model_data/MODEL/YYYYMMDDHH/LBCS`` From 271bb1a041b679015a6f53c18aa53f765452d44c Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 5 May 2022 22:10:49 -0400 Subject: [PATCH 126/158] include updated images --- docs/UsersGuide/source/SRW_NATLEV_table.csv | 210 ++++++++++++++ docs/UsersGuide/source/SRW_NATLEV_table.rst | 11 + docs/UsersGuide/source/SRW_PRSLEV_table.csv | 257 ++++++++++++++++++ docs/UsersGuide/source/SRW_PRSLEV_table.rst | 11 + .../_static/FV3LAM_wflow_flowchart_v2.png | Bin 0 -> 561715 bytes 5 files changed, 489 insertions(+) create mode 100644 docs/UsersGuide/source/SRW_NATLEV_table.csv create mode 100644 docs/UsersGuide/source/SRW_NATLEV_table.rst create mode 100644 docs/UsersGuide/source/SRW_PRSLEV_table.csv create mode 100644 docs/UsersGuide/source/SRW_PRSLEV_table.rst create mode 100644 docs/UsersGuide/source/_static/FV3LAM_wflow_flowchart_v2.png diff --git a/docs/UsersGuide/source/SRW_NATLEV_table.csv b/docs/UsersGuide/source/SRW_NATLEV_table.csv new file mode 100644 index 0000000000..ba82e4e3d6 --- /dev/null +++ b/docs/UsersGuide/source/SRW_NATLEV_table.csv @@ -0,0 +1,210 @@ +No.,Field Description,Level Type,Short Name,nlvl +1,Height on pressure surface,isobaric,HGT,4 +2,Temperature on pressure surface,isobaric,TMP,5 +3,Relative humidity on pressure surface,isobaric,RH,4 +4,U component of wind on pressure surface,isobaric,UGRD,4 +5,V component of wind on pressure surface,isobaric,VGRD,4 +6,Omega on pressure surface,isobaric,VVEL,4 +7,Specific humidity on pressure surface,isobaric,SPFH,4 +8,Absolute vorticity on pressure surface,isobaric,ABSV,4 +9,Pressure on model surface,hybrid,PRES,64 +10,Height on model surface,hybrid,HGT,64 +11,Temperature on model surface,hybrid,TMP,64 +12,Specific humidity on model surface,hybrid,SPFH,64 +13,U component of wind on model surface,hybrid,UGRD,64 +14,V component of wind on model surface,hybrid,VGRD,64 +15,Omega on model surface,hybrid,VVEL,64 +16,Vertical velocity on model surface,hybrid,DZDT,64 +17,Turbulent kinetic energy on model surface,hybrid,TKE,64 +18,Temperature tendency from grid scale latent heat release (time-averaged),hybrid,LRGHR,64 +19,Mesinger (Membrane) sea level pressure,mean sea level,MSLET,1 +20,Shuell sea level pressure,mean sea level,PRES,1 +21,Temperature at 2m,height agl,TMP,1 +22,Specific humidity at 2m,height agl,SPFH,1 +23,Dew point temperature at 2m,height agl,DPT,1 +24,Relative humidity at 2m,height agl,RH,1 +25,U component of wind at 10m,height agl,UGRD,1 +26,V component of wind at 10m,height agl,VGRD,1 +27,Potential temperature at 10m,height agl,POT,1 +28,Specific humidity at 10m,height agl,SPFH,1 +29,Surface Pressure,surface,PRES,1 +30,Terrain height,surface,HGT,1 +31,Skin potential temperature,surface,POT,1 +32,Skin specific humidity,surface,SPFH,1 +33,Skin temperature,surface,TMP,1 +34,Maximum updraft vertical velocity (100-1000 hPa),isobaric,MAXUVV,1 +35,Maximum downdraft vertical velocity (100-1000 hPa),isobaric,MAXDVV,1 +36,Maximum updraft helicity (0-3 km),height agl,MXUPHL,1 +37,Maximum updraft helicity (2-5 km),height agl,MXUPHL,1 +38,Minimum updraft helicity (2-5 km),height agl,MNUPHL,1 +39,Minimum updraft helicity (0-3 km),height agl,MNUPHL,1 +40,Maximum relative vertical vorticity (0-1 km),height agl,RELV,1 +41,Maximum relative vertical vorticity at hybrid level 1,hybrid,RELV,1 +42,Maximum relative vertical vorticity (0-2 km),height agl,RELV,1 +43,Maximum U-component wind at 10m,height agl,MAXUW,1 +44,Maximum V-component wind at 10m,height agl,MAXVW,1 +45,Maximum derived radar reflectivity at 1 km,height agl,MAXREF,1 +46,Maximum derived radar reflectivity at -10 C,isothermal,MAXREF,1 +47,Radar reflectivity at -10 C,isothermal,REFD,1 +48,Maximum 2m temperature,height agl,TMAX,1 +49,Minimum 2m temperature,height agl,TMIN,1 +50,Maximum 2m RH,height agl,MAXRH,1 +51,Minimum 2m RH,height agl,MINRH,1 +52,Soil temperature in between each soil layer,depth below land surface,TSOIL,4 +53,Soil moisture in between each soil layer,depth below land surface,SOILW,4 +54,Total soil moisture,depth below land surface,SOILM,1 +55,Heat exchange coeff at surface,surface,SFEXC,1 +56,Vegetation cover,surface,VEG,1 +57,Soil moisture availability,depth below land surface,MSTAV,1 +58,Soil temperature at 3m,depth below land surface,TSOIL,1 +59,Ground heat flux (instantaneous),surface,GFLUX,1 +60,Plant canopy surface water,surface,CNWAT,1 +61,Snow water equivalent,surface,WEASD,1 +62,Lifted index—best,pressure above ground,4LFTX,1 +63,Column integrated precipitable water,entire atmosphere,PWAT,1 +64,Accumulated total precipitation,surface,APCP,1 +65,Accumulated grid-scale precipitation,surface,NCPCP,1 +66,Continuous accumulated total precipitation,surface,APCP,1 +67,Continuous accumulated grid-scale precipitation,surface,NCPCP,1 +68,Accumulated total snow melt,surface,SNOM,1 +69,Accumulated storm surface runoff,surface,SSRUN,1 +70,Accumulated base flow runoff,surface,BGRUN,1 +71,Categorical rain (instantaneous),surface,CRAIN,1 +72,Categorical snow (instantaneous),surface,CSNOW,1 +73,Categorical ice pellets (instantaneous),surface,CICEP,1 +74,Categorical freezing rain (instantaneous),surface,CFRZR,1 +75,Precipitation rate (instantaneous),surface,PRATE,1 +76,Fraction of frozen precipitation,surface,CPOFP,1 +77,Cloud water mixing ratio on model surface,hybrid,CLMR,64 +78,Cloud ice mixing ratio on model surface,hybrid,ICMR,64 +79,Graupel mixing ratio on mmodel surface,hybrid,GRLE,64 +80,Cloud fraction on model surface,hybrid,TCDC,64 +81,Rain mixing ratio on model surface,hybrid,RWMR,64 +82,Snow mixing ratio on model surface,hybrid,SNMR,64 +83,Rimming factor for Ferrier scheme on model surface,hybrid,RIME,64 +84,Total condensate for Ferrier scheme on mode surface,hybrid,TCOND,64 +85,Model level fraction of rain for Ferrier scheme,hybrid,FRAIN,64 +86,Model level fraction of ice for Ferrier scheme,hybrid,FICE,64 +87,Low level cloud fraction,low cloud layer,LCDC,1 +88,Mid level cloud fraction,mid cloud layer,MCDC,1 +89,High level cloud fraction,high cloud layer,HCDC,1 +90,Total cloud fraction,entire atmosphere,TCDC,1 +91,Total cloud fraction (time-averaged),entire atmosphere,TCDC,1 +92,stratospheric cloud fraction (time-averaged),entire atmosphere,CDLYR,1 +93,Outgoing surface shortwave radiation (instantaneous),surface,USWRF,1 +94,Outgoing surface longwave radiation (instantaneous),surface,ULWRF,1 +95,Incoming surface shortwave radiation (time-averaged),surface,DSWRF,1 +96,Incoming surface longwave radiation (time-averaged),surface,DLWRF,1 +97,Outgoing surface shortwave radiation (time-averaged),surface,USWRF,1 +98,Outgoing surface longwave radiation (time-averaged),surface,ULWRF,1 +99,Outgoing model top shortwave radiation (time-averaged),top of atmosphere,USWRF,1 +100,Outgoing model top longwave radiation (time-averaged),top of atmosphere,ULWRF,1 +101,Incoming surface shortwave radiation (instantaneous),surface,DSWRF,1 +102,Incoming surface longwave radiation (instantaneous),surface,DLWRF,1 +103,Clear sky incoming surface shortwave (instantaneous),surface,CSDSF,1 +104,Roughness length,surface,SFCR,1 +105,Friction velocity,surface,FRICV,1 +106,Surface drag coefficient,surface,CD,1 +107,Surface u wind stress,surface,UFLX,1 +108,Surface v wind stress,surface,VFLX,1 +109,Surface sensible heat flux (time-averaged),surface,SHTFL,1 +110,Ground heat flux (time-averaged),surface,GFLUX,1 +111,Snow phase change heat flux (time-averaged),surface,SNOHF,1 +112,Surface latent heat flux (time-averaged),surface,LHTFL,1 +113,Accumulated surface evaporation,surface,EVP,1 +114,Accumulated potential evaporation,surface,PEVAP,1 +115,Surface sensible heat flux (instantaneous),surface,SHTFL,1 +116,Surface latent heat flux (instantaneous),surface,LHTFL,1 +117,Latitude,surface,NLAT,1 +118,Longitude,surface,ELON,1 +119,Land sea mask (land=1 sea=0),surface,LAND,1 +120,Sea ice mask,surface,ICEC,1 +121,Mass point at eta surface mask,surface,LMH,1 +122,Velocity point at eta surface mask,surface,LMV,1 +123,Surface albedo,surface,ALBDO,1 +124,Sea surface temperature,surface,WTMP,1 +125,Pressure in boundary layer (30 mb means),pressure agl,PRES,6 +126,Temperature in boundary layer (30 mb means),pressure agl,TMP,6 +127,Potential temperature in boundary layer (30 mb means),pressure agl,POT,1 +128,Dew point temperature in boundary layer (30 mb means),pressure agl,DPT,1 +129,Specific humidity in boundary layer (30 mb means),pressure agl,SPFH,6 +130,RH in boundary layer (30 mb means),pressure agl,RH,6 +131,Moisture convergence in boundary layer (30 mb means),pressure agl,MCONV,1 +132,Precipitable water in boundary layer (30 mb means),pressure agl,PWAT,1 +133,U wind in boundary layer (30 mb means),pressure agl,UGRD,6 +134,V wind in boundary layer (30 mb means),pressure agl,VGRD,6 +135,Accumulated land surface model precipitation,surface,LSPA,1 +136,Model top pressure,top of atmosphere,PRES,1 +137,Pressure thickness,hybrid,PRES,1 +138,Sigma pressure thickness,hybrid,PRES,1 +139,Plant canopy surface water,surface,CNWAT,1 +140,Ground heat flux (instantaneous),surface,GFLUX,1 +141,Lifted index—surface based (500-1000 hPa),isobaric,LFTX,1 +142,Convective available potential energy,surface,CAPE,1 +143,Best cape,pressure above ground,CAPE,1 +144,Mixed layer cape,pressure above ground,CAPE,1 +145,Unstable cape,pressure above ground,CAPE,1 +146,Convective inhibition,surface,CIN,1 +147,Best cin,pressure above ground,CIN,1 +148,Mixed layer cin,pressure above ground,CIN,1 +149,Unstable cin,pressure above ground,CIN,1 +150,LCL level pressure,pressure layer agl,PLPL,1 +151,Helicity,height agl,HLCY,2 +152,U component storm motion,height agl,USTM,1 +153,V component storm motion,height agl,VSTM,1 +154,Cloud bottom pressure,cloud base,PRES,1 +155,Cloud top pressure,cloud top,PRES,1 +156,Cloud top temperature,cloud top,TMP,1 +157,Pressure at tropopause,tropopause,PRES,1 +158,Height at tropopause,tropopause,HGT,1 +159,Temperature at tropopause,tropopause,TMP,1 +160,U component of wind at tropopause,tropopause,UGRD,1 +161,V component of wind at tropopause,tropopause,VGRD,1 +162,Wind shear at tropopause,tropopause,VWSH,1 +163,Temperature at flight levels,height msl,TMP,10 +164,U component of wind at flight levels,height msl,UGRD,10 +165,V component of wind at flight levels,height msl,VGRD,10 +166,Freezing level height,0 degree isotherm,HGT,1 +167,Freezing level relative humidity,0 degree isotherm,RH,1 +168,Highest freezing level height,highest tropospheric frz lvl,HGT,1 +169,Maximum wind pressure level,max wind,PRES,1 +170,Maximum wind height,max wind,HGT,1 +171,U-component of maximum wind,max wind,UGRD,1 +172,V-component of maximum wind,max wind,VGRD,1 +173,Maximum wind speed at 10m,height agl,WIND,1 +174,Cloud bottom height (above MSL),cloud base,HGT,1 +175,Cloud top height (above MSL),cloud top,HGT,1 +176,GSD visibility,surface,VIS,1 +177,Composite radar reflectivity,entire atmosphere,REFC,1 +178,Grid scale cloud bottom pressure,grid scale cloud bottom,PRES,1 +179,Grid scale cloud top pressure,grid scale cloud top,PRES,1 +180,Column integrated cloud water,entire atmosphere,TCOLW,1 +181,Column integrated cloud ice,entire atmosphere,TCOLI,1 +182,Column integrated rain,entire atmosphere,TCOLR,1 +183,Column integrated snow,entire atmosphere,TCOLS,1 +184,Column integrated total condensate,entire atmosphere,TCOLC,1 +185,Column integrated graupel,entire atmosphere,TCOLG,1 +186,Vegetation type,surface,VGTYP,1 +187,Soil type,surface,SOTYP,1 +188,Canopy conductance,surface,CCOND,1 +189,Planetary boundary layer height,surface,HPBL,1 +190,Snow depth,surface,SNOD,1 +191,Snow sublimation,surface,SBSNO,1 +192,Air dry soil moisture,surface,SMDRY,1 +193,Soil moist porosity,surface,POROS,1 +194,Minimum stomatal resistance,surface,RSMIN,1 +195,Number of root layers,surface,RLYRS,1 +196,Soil moist wilting point,surface,WILT,1 +197,Soil moist reference,surface,SMREF,1 +198,Canopy conductance - solar component,surface,RCS,1 +199,Canopy conductance - temperature component,surface,RCT,1 +200,Canopy conductance - humidity component,surface,RCQ,1 +201,Canopy conductance - soil component,surface,RCSOL,1 +202,Potential evaporation,surface,PEVPR,1 +203,Surface wind gust,surface,GUST,1 +204,Lowest wet bulb zero height,lowest lvl wet bulb zero,HGT,1 +205,Leaf area index,surface,LAI,1 +206,Clear sky incoming surface shortwave (instantaneous),surface,CSDSF,1 +207,Richardson number planetary boundary layer height,planetary boundary layer,HGT,1 +208,Mixing height,surface,MIXHT,1 +209,Time-averaged percentage snow cover,surface,SNOWC,1 \ No newline at end of file diff --git a/docs/UsersGuide/source/SRW_NATLEV_table.rst b/docs/UsersGuide/source/SRW_NATLEV_table.rst new file mode 100644 index 0000000000..436927355e --- /dev/null +++ b/docs/UsersGuide/source/SRW_NATLEV_table.rst @@ -0,0 +1,11 @@ +************************************************************ +Fields Requested in the UPP Parameter Table for SRW NATLEV +************************************************************ + +Field description (column 1), level type as defined by WMO (column 2), abbreviated names +as they appear in the Grib2 output file (column 3), and number of levels output (column 4). + +.. csv-table:: + :file: SRW_NATLEV_table.csv + :widths: 9, 40, 30, 15, 10 + :header-rows: 1 diff --git a/docs/UsersGuide/source/SRW_PRSLEV_table.csv b/docs/UsersGuide/source/SRW_PRSLEV_table.csv new file mode 100644 index 0000000000..581a43a5e4 --- /dev/null +++ b/docs/UsersGuide/source/SRW_PRSLEV_table.csv @@ -0,0 +1,257 @@ +No.,Field Description,Level Type,Short Name,nlvl +1,Pressure on model surface,hybrid,PRES,2 +2,Height on model surface,hybrid,HGT,2 +3,Temperature on model surface,hybrid,TMP,2 +4,Potential temperature on model surface,hybrid,POT,2 +5,Dew point temperature on model surface,hybrid,DPT,2 +6,Specific humidity on model surface,hybrid,SPFH,1 +7,Relative humidity on model surface,hybrid,RH,1 +8,U component of wind on model surface,hybrid,UGRD,2 +9,V component of wind on model surface,hybrid,VGRD,2 +10,Omega on model surface,hybrid,VVEL,1 +11,Vertical velocity on model surface,hybrid,DZDT,1 +12,Turbulent kinetic energy on model surface,hybrid,TKE,2 +13,Rain mixing ratio on model surface,hybrid,RWMR,2 +14,Snow mixing ratio on model surface,hybrid,SNMR,2 +15,Rimming factor for Ferrier scheme on model surface,hybrid,RIME,2 +16,Total condensate for Ferrier scheme on mode surface,hybrid,TCOND,2 +17,Radar reflectivity on model surface,hybrid,REFD,2 +18,Master length scale on model surface,hybrid,BMIXL,1 +19,Height on pressure surface,isobaric,HGT,45 +20,Temperature on pressure surface,isobaric,TMP,45 +21,Dew point temperature on pressure surface,isobaric,DPT,45 +22,Specific humidity on pressure surface,isobaric,SPFH,45 +23,Relative humidity on pressure surface,isobaric,RH,45 +24,Moisture convergence on pressure surface,isobaric,MCONV,2 +25,U component of wind on pressure surface,isobaric,UGRD,45 +26,V component of wind on pressure surface,isobaric,VGRD,45 +27,Vertical velocity on pressure surface,isobaric,DZDT,45 +28,Omega on pressure surface,isobaric,VVEL,45 +29,Absolute vorticity on pressure surface,isobaric,ABSV,10 +30,Geostrophic streamfunction on pressure surface,isobaric,STRM,2 +31,Turbulent kinetic energy on pressure surface,isobaric,TKE,45 +32,Cloud ice mixing ratio on pressure surface,isobaric,ICMR,45 +33,Cloud water mixing ratio on pressure surface,isobaric,CLMR,45 +34,Rain mixing ratio on pressure surface,isobaric,RWMR,45 +35,Graupel mixing ratio on pressure surface,isobaric,GRLE,45 +36,Snow mixing ratio on pressure surface,isobaric,SNMR,45 +37,Rimming factor for Ferrier scheme on pressure surface,isobaric,RIME,45 +38,Mesinger (Membrane) sea level pressure,mean sea level,MSLET,1 +39,Shuell sea level pressure,mean sea level,PRES,1 +40,Temperature at 2m,height agl,TMP,1 +41,Specific humidity at 2m,height agl,SPFH,1 +42,Dew point temperature at 2m,height agl,DPT,1 +43,Relative humidity at 2m,height agl,RH,1 +44,U component of wind at 10m,height agl,UGRD,1 +45,V component of wind at 10m,height agl,VGRD,1 +46,Surface wind gust,surface,GUST,1 +47,LCL level pressure,pressure layer agl,PLPL,1 +48,Potential temperature at 10m,height agl,POT,1 +49,Specific humidity at 10m,height agl,SPFH,1 +50,Surface Pressure,surface,PRES,1 +51,Terrain height,surface,HGT,1 +52,Skin potential temperature,surface,POT,1 +53,Skin specific humidity,surface,SPFH,1 +54,Skin temperature,surface,TMP,1 +55,Soil temperature at 3m,depth below land surface,TSOIL,1 +56,Soil temperature in between each soil layer,depth below land surface,TSOIL,4 +57,Soil moisture in between each soil layer,depth below land surface,SOILW,4 +58,Liquid soil moisture in between each soil layer,depth below land surface,SOILL,4 +59,Total soil moisture,depth below land surface,SOILM,1 +60,Plant canopy surface water,surface,CNWAT,1 +61,Snow water equivalent,surface,WEASD,1 +62,Snow cover in percentage,surface,SNOWC,1 +63,Heat exchange coeff at surface,surface,SFEXC,1 +64,Vegetation cover,surface,VEG,1 +65,Vegetation type,surface,VGTYP,1 +66,Soil type,surface,SOTYP,1 +67,Snow free albedo,surface,SNFALB,1 +68,Maximum snow albedo,surface,MXSALB,1 +69,Canopy conductance,surface,CCOND,1 +70,Canopy conductance - solar component,surface,RCS,1 +71,Canopy conductance - temperature component,surface,RCT,1 +72,Canopy conductance - humidity component,surface,RCQ,1 +73,Canopy conductance - soil component,surface,RCSOL,1 +74,Soil moist reference,surface,SMREF,1 +75,Soil moist porosity,surface,POROS,1 +76,Number of root layers,surface,RLYRS,1 +77,Minimum stomatal resistance,surface,RSMIN,1 +78,Snow depth,surface,SNOD,1 +79,Air dry soil moisture,surface,SMDRY,1 +80,Soil moist wilting point,surface,WILT,1 +81,Soil moisture availability,depth below land surface,MSTAV,1 +82,Ground heat flux (instantaneous),surface,GFLUX,1 +83,Lifted index—surface based (500-1000 hPa),isobaric,LFTX,1 +84,Lifted index—best,pressure above ground,4LFTX,1 +85,Lifted index—parcel,pressure above ground,PLI,1 +86,Convective available potential energy,surface,CAPE,1 +87,Best cape,pressure above ground,CAPE,1 +88,Mixed layer cape,pressure above ground,CAPE,1 +89,Unstable cape,pressure above ground,CAPE,1 +90,Convective inhibition,surface,CIN,1 +91,Best cin,pressure above ground,CIN,1 +92,Mixed layer cin,pressure above ground,CIN,1 +93,Unstable cin,pressure above ground,CIN,1 +94,Column integrated precipitable water,entire atmosphere,PWAT,1 +95,Helicity,height agl,HLCY,2 +96,U component storm motion,height agl,USTM,1 +97,V component storm motion,height agl,VSTM,1 +98,Accumulated total precipitation,surface,APCP,1 +99,Accumulated grid-scale precipitation,surface,NCPCP,1 +100,Continuous accumulated total precipitation,surface,APCP,1 +101,Continuous accumulated grid-scale precipitation,surface,NCPCP,1 +102,Accumulated total snow melt,surface,SNOM,1 +103,Accumulated storm surface runoff,surface,SSRUN,1 +104,Accumulated base flow runoff,surface,BGRUN,1 +105,Average water runoff,surface,WATR,1 +106,Categorical rain (instantaneous),surface,CRAIN,1 +107,Categorical snow (instantaneous),surface,CSNOW,1 +108,Categorical ice pellets (instantaneous),surface,CICEP,1 +109,Categorical freezing rain (instantaneous),surface,CFRZR,1 +110,Precipitation rate (instantaneous),surface,PRATE,1 +111,Fraction of frozen precipitation,surface,CPOFP,1 +112,Cloud water mixing ratio on model surface,hybrid,CLMR,2 +113,Cloud ice mixing ratio on model surface,hybrid,ICMR,2 +114,Graupel mixing ratio on model surface,hybrid,GRLE,1 +115,Cloud fraction on model surface,hybrid,TCDC,2 +116,Low level cloud fraction,low cloud layer,LCDC,1 +117,Mid level cloud fraction,mid cloud layer,MCDC,1 +118,High level cloud fraction,high cloud layer,HCDC,1 +119,Total cloud fraction,entire atmosphere,TCDC,1 +120,Total cloud fraction (time-averaged),entire atmosphere,TCDC,1 +121,stratospheric cloud fraction (time-averaged),entire atmosphere,CDLYR,1 +122,GSD visibility,cloud top,VIS,1 +123,Above-ground height of LCL,adiabatic condensation from surface,HGT,1 +124,Pressure of LCL,adiabatic condensation from surface,PRES,1 +125,Outgoing surface shortwave radiation (instantaneous),surface,USWRF,1 +126,Outgoing surface longwave radiation (instantaneous),surface,ULWRF,1 +127,Incoming surface shortwave radiation (time-averaged),surface,DSWRF,1 +128,Incoming surface longwave radiation (time-averaged),surface,DLWRF,1 +129,Outgoing surface shortwave radiation (time-averaged),surface,USWRF,1 +130,Outgoing surface longwave radiation (time-averaged),surface,ULWRF,1 +131,Outgoing model top shortwave radiation (time-averaged),top of atmosphere,USWRF,1 +132,Outgoing model top longwave radiation (time-averaged),top of atmosphere,ULWRF,1 +133,Outgoing longwave at top of atmosphere (instantaneous),top of atmosphere,ULWRF,1 +134,Total spectrum brightness temperature,top of atmosphere,BRTMP,1 +135,Incoming surface shortwave radiation (instantaneous),surface,DSWRF,1 +136,Incoming surface longwave radiation (instantaneous),surface,DLWRF,1 +137,Clear sky incoming surface shortwave (instantaneous),surface,CSDSF,1 +138,Roughness length,surface,SFCR,1 +139,Friction velocity,surface,FRICV,1 +140,Surface drag coefficient,surface,CD,1 +141,Surface u wind stress,surface,UFLX,1 +142,Surface v wind stress,surface,VFLX,1 +143,Surface sensible heat flux (time-averaged),surface,SHTFL,1 +144,Ground heat flux (time-averaged),surface,GFLUX,1 +145,Snow phase change heat flux (time-averaged),surface,SNOHF,1 +146,Surface latent heat flux (time-averaged),surface,LHTFL,1 +147,Accumulated surface evaporation,surface,EVP,1 +148,Accumulated potential evaporation,surface,PEVAP,1 +149,Surface sensible heat flux (instantaneous),surface,SHTFL,1 +150,Surface latent heat flux (instantaneous),surface,LHTFL,1 +151,Latitude,surface,NLAT,1 +152,Longitude,surface,ELON,1 +153,Land sea mask (land=1 sea=0),surface,LAND,1 +154,Sea ice mask,surface,ICEC,1 +155,Surface albedo,surface,ALBDO,1 +156,Sea surface temperature,surface,WTMP,1 +157,Pressure at tropopause,tropopause,PRES,1 +158,Height at tropopause,tropopause,HGT,1 +159,Temperature at tropopause,tropopause,TMP,1 +160,Potential temperature at tropopause,tropopause,POT,1 +161,U component of wind at tropopause,tropopause,UGRD,1 +162,V component of wind at tropopause,tropopause,VGRD,1 +163,Wind shear at tropopause,tropopause,VWSH,1 +164,U component of 0-1km level wind shear,height agl,VUCSH,1 +165,V-component of 0-1km level wind shear,height agl,VVCSH,1 +166,U component of 0-6km level wind shear,height agl,VUCSH,1 +167,V-component of 0-6km level wind shear,height agl,VVCSH,1 +168,Temperature at flight levels,height msl,TMP,10 +169,Temperature at flight levels,height agl,TMP,4 +170,U component of wind at flight levels,height msl,UGRD,10 +171,U component of wind at flight levels,height agl,UGRD,4 +172,V component of wind at flight levels,height msl,VGRD,10 +173,V component of wind at flight levels,height agl,VGRD,4 +174,Specific humidity at flight levels,height msl,SPFH,1 +175,Specific humidity at flight levels,height agl,SPFH,4 +176,Pressure at flight levels,height agl,PRES,4 +177,Freezing level height,0 degree isotherm,HGT,1 +178,Freezing level relative humidity,0 degree isotherm,RH,1 +179,Highest freezing level height,highest tropospheric frz lvl,HGT,1 +180,Lowest wet bulb zero height,lowest lvl wet bulb zero,HGT,1 +181,Pressure in boundary layer (30 mb means),pressure agl,PRES,6 +182,Temperature in boundary layer (30 mb means),pressure agl,TMP,6 +183,Potential temperature in boundary layer (30 mb means),pressure agl,POT,1 +184,Dew point temperature in boundary layer (30 mb means),pressure agl,DPT,1 +185,Specific humidity in boundary layer (30 mb means),pressure agl,SPFH,6 +186,RH in boundary layer (30 mb means),pressure agl,RH,6 +187,Moisture convergence in boundary layer (30 mb means),pressure agl,MCONV,1 +188,Precipitable water in boundary layer (30 mb means),pressure agl,PWAT,1 +189,U wind in boundary layer (30 mb means),pressure agl,UGRD,6 +190,V wind in boundary layer (30 mb means),pressure agl,VGRD,6 +191,Omega in boundary layer (30 mb means),pressure agl,VVEL,3 +192,Cloud bottom pressure,cloud base,PRES,1 +193,Cloud top pressure,cloud top,PRES,1 +194,Cloud top temperature,cloud top,TMP,1 +195,Cloud bottom height (above MSL),cloud base,HGT,1 +196,Cloud top height (above MSL),cloud top,HGT,1 +197,Maximum wind pressure level,max wind,PRES,1 +198,Maximum wind height,max wind,HGT,1 +199,U-component of maximum wind,max wind,UGRD,1 +200,V-component of maximum wind,max wind,VGRD,1 +201,Composite radar reflectivity,entire atmosphere,REFC,1 +202,Composite rain radar reflectivity,entire atmosphere,REFZR,1 +203,Composite ice radar reflectivity,entire atmosphere,REFZI,1 +204,Radar reflectivity at certain above ground heights,height agl,REFD,2 +205,Radar reflectivity from rain,height agl,REFZR,2 +206,Radar reflectivity from ice,height agl,REFZI,2 +207,Planetary boundary layer height,surface,HPBL,1 +208,Grid scale cloud bottom pressure,grid scale cloud bottom,PRES,1 +209,Grid scale cloud top pressure,grid scale cloud top,PRES,1 +210,Column integrated cloud water,entire atmosphere,TCOLW,1 +211,Column integrated cloud ice,entire atmosphere,TCOLI,1 +212,Column integrated rain,entire atmosphere,TCOLR,1 +213,Column integrated snow,entire atmosphere,TCOLS,1 +214,Column integrated total condensate,entire atmosphere,TCOLC,1 +215,Column integrated graupel,entire atmosphere,TCOLG,1 +216,Column integrated super cool liquid water,entire atmosphere,TCLSW,1 +217,Column integrated melting ice,entire atmosphere,TCOLM,1 +218,Height of lowest level super cool liquid water,lwst bot lvl of supercooled liq wtr,HGT,1 +219,Height of highest level super cool liquid water,hghst top lvl of supercooled liq wtr,HGT,1 +220,Ceiling height,cloud ceiling,HGT,1 +221,Accumulated land surface model precipitation,surface,LSPA,1 +222,Model top pressure,top of atmosphere,PRES,1 +223,Total column shortwave temperature tendency,entire atmosphere,SWHR,1 +224,Total column longwave temperature tendency,entire atmosphere,LWHR,1 +225,Total column gridded temperature tendency,entire atmosphere,LRGHR,1 +226,Column integrated moisture convergence,entire atmosphere,MCONV,1 +227,Planetary boundary layer regime,surface,PBLREG,1 +228,Transport wind u component,planetary boundary layer,UGRD,1 +229,Transport wind v component,planetary boundary layer,VGRD,1 +230,Richardson number planetary boundary layer height,planetary boundary layer,HGT,1 +231,Mixing height,surface,MIXHT,1 +232,Radar echo top,entire atmosphere,RETOP,1 +233,Ventilation rate,planetary boundary layer,VRATE,1 +234,Haines index,surface,HINDEX,1 +235,Maximum 2m temperature,height agl,TMAX,1 +236,Minimum 2m temperature,height agl,TMIN,1 +237,Maximum 2m RH,height agl,MAXRH,1 +238,Minimum 2m RH,height agl,MINRH,1 +239,Maximum U-component wind at 10m,height agl,MAXUW,1 +240,Maximum V-component wind at 10m,height agl,MAXVW,1 +241,Maximum wind speed at 10m,height agl,WIND,1 +242,Maximum 1km reflectivity,height agl,MAXREF,1 +243,Maximum updraft vertical velocity 100-1000 hPa,isobaric layer,MAXUVV,1 +244,Maximum downdraft vertical velocity 100-1000 hPa,isobaric layer,MAXDVV,1 +245,Lightning,surface,LTNG,1 +246,Radar derived vertically integrated liquid,entire atmosphere,VIL,1 +247,Updraft helicity (2-5 km),height agl,UPHL,1 +248,Maximum updraft helicity (2-5 km),height agl,MXUPHL,1 +249,Minimum updraft helicity (2-5 km),height agl,MNUPHL,1 +250,Minimum updraft helicity (0-3 km),height agl,MNUPHL,1 +251,Maximum updraft helicity (0-3 km),height agl,MXUPHL,1 +252,Maximum relative vertical vorticity (0-1 km),height agl,RELV,1 +253,Maximum relative vertical vorticity at hybrid level 1,hybrid,RELV,1 +254,Maximum relative vertical vorticity (0-2 km),height agl,RELV,1 +255,Maximum derived radar reflectivity at -10 C,isothermal,MAXREF,1 +256,Radar reflectivity at -10 C,isothermal,REFD,1 \ No newline at end of file diff --git a/docs/UsersGuide/source/SRW_PRSLEV_table.rst b/docs/UsersGuide/source/SRW_PRSLEV_table.rst new file mode 100644 index 0000000000..30048e2715 --- /dev/null +++ b/docs/UsersGuide/source/SRW_PRSLEV_table.rst @@ -0,0 +1,11 @@ +********************************************************** +Fields Requested in the UPP Parameter Table for SRW PRSLEV +********************************************************** + +Field description (column 1), level type as defined by WMO (column 2), abbreviated names +as they appear in the Grib2 output file (column 3), and number of levels output (column 4). + +.. csv-table:: + :file: SRW_PRSLEV_table.csv + :widths: 9, 40, 30, 15, 10 + :header-rows: 1 diff --git a/docs/UsersGuide/source/_static/FV3LAM_wflow_flowchart_v2.png b/docs/UsersGuide/source/_static/FV3LAM_wflow_flowchart_v2.png new file mode 100644 index 0000000000000000000000000000000000000000..545a8db938d2745e5fd854b9e721f02a05a5888d GIT binary patch literal 561715 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
@RSsl^6^`Z7Q-2zv?2 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

BiwkAn#x^> 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 z%0ABwlNgzZRb)EK82%_ADuF4T)4m*_7Zox2XDQdy+&pkws$!O27`)*Y>otd6WA(PNzJJudOnqiV>p=)L`wGqpl&# zO4CxArGw2GGU6fcJ!gsOE>-ppb6BY)gd;06aL7?!xl09(zh?KuH*|8JVcZEX@N40= z)=tC?k{MA@I+tsD3W_^uDz|%~f6>$__BL&OL5%#5cszfD$2%AuJ5O%tkUERzCP3yS z#v#^4X7dTlL?$vcf<{eQRw&a&?X)pBSpVjnM|d=?Mjyp@4j42^)IE9Ogo1eaYJqWO zFO+O;u2OzHB}Up|vwtH7rF(?MPa^|S-kt_R=$e|sa7|0TccPg!X%TA=$5!sU;A~b8 zU78SIahDIcHyGMc>s>~p_V_sP+-4vEel0$DEsi+8r@!t<<6bo3W3O$`&`WsfwDfsG^8AyE07pNRW7=@$(kz;gvf{6< zbI8O)ymj`R6Q$hvS(9_)iX|0bggULIb^=edqs`+dHfy0of+aLQVzxrqfi;<1Eij)v^=xUP_ zJp&Eh#F|u@Wb1NBggA5yrs)`cGo7dNad-zVl{>#e4j8a!kn;xfeTi3X^>vaCK0+-p zf%#nZTGcOEYT(&-UMa442oKr~-WlW>M9Fxc^lW8hFiO?uq>*z;(E?#|yV1~T&I1eu9X^bAxYwq~6=VOK* zX>PMlv4w~Udxi7+iB~U1LV5coC27TJC1;FG&8eAny!SJuJ_QF?OoGUqxBSO7?2;+9 z0ENMQ=oxJH)eNO2gS+4!VN{jf#~n|(kDx&xa8r)lo)e*L>p6M5Y-;4rbl#Oi$kx7i_8eAldf7D`H_$c^vhxwY$dO+Xlx=y~s zuXNx&_+Bb}|2+~hGc^uV+` z6Uu;cE={V&Kkl@b-NAFWlMVIu;-P03t0Jh1CcFpnwI7J_o|^dT!a|jA$m5wMbESO} z$*fr?gx-wrMjsR2z^Yh=sH9sSEPz>es6G!*t8k`^JUf7ZJfFCWpT$-DWk`!ZcT^1t z>e*e9mbe$Lf80fkj3TrUe9!lpBtx_7pu#KF+j1Ly$@cus-tD2U6oDci=1KhIgQorb z43imn?hIFXSzuilu6A_KDmUxtlu@-`oA{sgT%eI5DbV>~&;GBUS1YM>3;(THiG7hW zod|0j(~2lO+{}X79;3_qo|bF(*LXUy?v!pn*$K?r`xdf7X9>#srod+{%RBgE(VxapB!j~3swE~7B4A8cd_lnBQeyvYTyRwLyW)%hMv3l%dMk`ljfSQ;Y zJ_8~sEIyuj(5%H95fi$2dT3KDdXcnl#}@{LPH`qmk7K73OH*eez)gt%Gqgd{RY#Jo!KG6mk)%*Lzw%m^0>&qIdLP& zF7DnUd(J2)man7I>S{{`#5@q0R~hFK_}w~YP>*w(+sy4QPQej<#+;pN@vF-faCTzb z+d)Tal@Iy*3=?_;jR^1@!_rTY6Vq!>ranEV4{^OXjT72l?k7DrI9oNGsEDp8A7+aT zSK*L-=>11+%!^ML0ZBwjNa&~O)?$I+G3L>-Ih;tD9({3~$RL0Jy?4v&%%+!qD~+EY za2(Rk4gwY6=h-0l6-EcgvB`n*OtOQ%@QLMc4qI4|^UW4|+pR>!UXBf%e;;}#MP4k=UK3o?nHc7p`c z(P*c9rqKF{PEty^ggrWx4q>Kn;geVvi3Q2SlQ1QYsogZH6bSu(=_K95H*-nJW|xiY zd%PW9IFnK|>2KQW`e7Z}chXZt*SHaND#hXN_e)btNF>gq)3$Uyhe`GMb6w~a3*n-d@!67w=Z{_89l4H{_1)EbekBBIIW68bi%$R5+YV+`J_#| z(H`(MMAUuN#}Y^x5NaG!reB_|hKYHGDNcwrX^~x7*)^th1_!);lj2`Ys6tn>YN3>< zEVcA7YL~XuBjRg6<;#njC$jX=0+r>h>^nf8f}#l?b838yV3*XGI}!AAN0EZI(&oFX^HnXtt-SW<{c{U2~JJWe#U&P!w*3YZ6-Xe6| zVXSqJ_0l8!v;Jl&klN%~U>5oD<=vl~#XzIWXkraMSOIx`5x%G)eJ4C;YIN~5f?cQy z=h-z6=ko}-Ummfjt zyNff>5e0e=dhDXlp7cX?AtGm&C2sSyG-Pcyz@X6<_b%HVtv4P@---oIcry$(mc1{T zLX912(+Ll)ARkWS4da?cTS42Jqu{HB$cJilujn6s9!;BP&L_G~@k+=LJnS|aSaQ*t zF$Nzi9;_5NiN8pPv>L8-H)I+7dCT`ZLT*9jYCmK=`M%>-I|L0g56l_Vt%?DDLIfpX zHg6Z#L+WD!poQCL*dmBw_WJ3Sl@0rx`BH~anWK3CZqgRbWfM5H=d`>Lo>WjYWZe|I z*;T&5l0SB-v{59dBgd(y`)P#0@|aQ##r%@`#jRP41R>xg0s3~*yswl@fhZ8s7Ct@n zJ1wuZ%J^o58f>>?wmFg=*5RoIBvre>byv=V1u8h0O2deBVXsAkXIXBpM%X0w;lDjfKNcevDe zka>~HqCj)=?D<3*$!2Q)mk4bC?9KJSBM} z)f=Gt9?_Dc@p;R2 zFeOuE!$kG9_Sa~x7i;b&M#w^23Be6}U(blrDSmC@U*zq=d8Emcp!tK1Zy}wb(&0Rr zN3rY|y0~1MkWM;3R2i9Qq!}x`%{KA^wYxHK-e~=VW^HKx*3&h3*9v6R!JB=~*m(_c zFf5}WwN-}-PM-U~RX$oK!s9;kLchOvR>QP#^#ptT*u1<;cD-}di~@&Rp5Ya7!9(0V zbJAi|x2=dC^kDS{tvemB)CE!rHjcRoPai~hr|2*DkA#sI51EKzu38vkfRu{68qT%e z^mp&7uUeEJxDd)by46tP29Ley>hH~T&K&R{YljP%ywiRm78?;MK}pZSp~_GJG)^Sd zP=2SS+9WlkEkA3eYtcp-sXzZ2Fx2`bjv8F-5bw$1{m}pc5*2S?+)NSoyKV%%Ev*~S zaRG9W>vU0U!BQ}QDye~I<-br5wyGg_oiuv?rBryBH#d%rl|4f?D&c#cuYr=?=6FdJ z@+Mfih?<;Z^8_yhR*XUyw^AFi$oJN6St~%lSdK=8k{15P$W02JxAnXelE*B*E@D5h z96e~_-MN+Szyg)?kWzi)VKUe=Fix@7{^H9#X${nD(tKgwT_@BBQbt7IC|e|(u)<<~ z$s@7vIM55}>ha`X0zGrKwDpSe=Den4>DI4r27juYl;SH;@2N+>Y6wJsPEo{~8(8Q3 zu(NJ^MrpH+i_^?q!#r2AeQ~7jqr&b?hAJ0B?MetQc{-(oWGZB1cZlqd?8B!8=s|fH zMA6?RNcR@@4&v7VZA?)3LEWCSN}~GKx4aU$!svA>cndvzm`_&`v~!ln{AuS&rER?8 zwqE_L+EDItYOp%O%Z5l_UPfnR;ke0-2#7Q~M1+VU1rgsdwr-@MUgFWCC6F3xv=zzrb%3Kr&E88IB%*9;r`Jh=jm4dvxU-tDk? zsGLZpH?BwK1WEbAp}6(#7=Vmd54+n?ekwKp(tM!G_jh=a{svA(in;40l8Jc0*VE@B zhEL7m*L_XitTfueDW}fz#SxzUz&Cn5#`V_hwx$_DN=lgvQ6QIhn#85+am;lLcJ8+o zaFd=fd&sk2y#Q#YEwfeL2zXQ~zd8Ral(eyUaDEntA-2C>wz9nK?SuFS?*{ws5`q#C zjZos1)V+te7-T=y%WF~L4H1Of7ff zOYOCfK7}a3tv^xRE1xljsk9lD(cW*n?o?+H zxj=s$i31mO%zKD3|Gg3&)rUYcdt`D&g>1!Tp!+#qJBm`)2-e;FN6O9krg*K9UprCtFl6PE8Rd6LHVl}qIF-dJTT3`aCW zrXUk_&zQPw%O@q9W%{L7g!|8lEoUHZFBT*`rI~)=<-e|u3S_`1JhAYC3H8SNt_hHsWktk18o~x&l--fIQRurb(X_)^ z&K~!-S{NoH23_0(xrt|#omC`wq+|A2_xH`;vtkg=Xquw1YCb%vCwH!*z%D}D@2Jjp zurrLP@5H~O=>$4=&9JDieHeO|>fr?*^=KuK==?s;o3P=fDy0T34DO25Wxmfb_%Xs8 z{E6>Tt#KTznOBS?mY6BhuWj_J@}28pPQR3#h4ApMppNQ@inK+R({B0TZ12H_WF0!6 zBlXo)Nlw($rr-wST6g+SvjNElv163XVb2FQ1}_2w;@u48-Bw_oeJafZE2 z;{ao*d;j`}11w%*Zb@t-zjHQ>WjIyXxlv>< zrR?SeD96_b3m_+A37(!;e0#0CAJ*dCI|) z6y}dtnXK2irVz_h;xXAWM=S)Ikn)Ld)?~S<{c@8v&|M*Xs69o=5rne zj(Jol1&)*I7JMwbKn0uQ)ys!1D*Xd9{)*~M3mb~CZ-h0F64z%hZhKO0ycGQ|3?1GrmINUd(ev&1 zpms=2`L9vF{dGjfjv1{Fb>fZk^eGWQ$p&RCCZ!7yJ!=mWGzm3*8H#Ke662Xnd~TYZ z#qd@4qA7i#!CY}dzh1a@TXIdn(xpl7ON~|U&NpAaa#YO^zMzVi_cUYW1&p z7zpY)`h|ToJ6XQ3#T%VELfj=fI-ZTdgN__=&%Y*Ho~nRq~? zZIAi&Hn{7icEF7J94ZmYhNszw%x>!crCL`?*fH5Kr6*gzV@Ml`k5I3aCCYDJ)- zM}NGW0YqkE1K?=c`0Y>ZzE8H3kr*cY;=*e`@&PXcs^NoI(gdY`StwmP=pF0|E7zgS zJDz)|cn;J0$?)gloleyu^6%uI)$73+hd*_PD>ryYBVxFaIVWwOSsEhDG#dBwT&sZZ z&iWmAx#67eO`gsrosS0JEy4Nnn1Hp2;famW7cS*Kz!4ORJnmosoH}K)e~TLFf~!Q+ z*v3n?2;M3Yq4E)`HPF$sB3QmXXpA^eA9v3{eWMp z<`)qCD+YfHzzhFNLCeVc4CfygAYVJSlQ!A4`1RO2>lXXP7Zv zE-kL__VhVJiK&|r{p#BKhJ=VoAF5m6r{$YZBw2JjyK7{E2-asM|-E%wp1NXD`o&j;f|BtWU@Bs1=-~ayc_YJ4kqn;dU zFbZWUzJtGBqw3^D)VnW+qbeUjHW=EpAM4=oP9bKx@Gfu1JxerpOsphOqKBM8Gu?}; zki{V6Na4WIr8>n*tK58J6XiW=mRLphgQ0vn7)e_LSszwLP^N0j=h>y>$~MvgRA{B* zsnVMA+DjJJio~vz`?=q|dh*GxTr{thGpWM^H$>b3*Wf!93sL_56>B33u$xFSM3ect z?ZsaC)Fe&oN9C)eV~kvRUAs-fsZ5vuSNsRCZenyOs}5-2Aq*rn#~$JVp{@!Fqg?ho z^l+*QTGY*zsER{(qI^ONF3$TH7~V!i1Ncb&^%O&9QhzIB5@Tl%$oBk z+I?{viCSeP&nc}Xa+va*{~#~G4^76IAC*dk=_DwJEH zy3Q++*Euub;CZ%19*tpmY+WNGsUp#IlrLVDD{nihc0^JNN=FUuS{DAZhxQgyyhO|O zoc}L$mnDLlD_zKTVl5j~#U#dxT}L*ge?(eS>%8_$xE`T{c*sL7bDl#u*&KQ& zMInh7CRa?9zt}r~1#2d}y)?~J=J-hr|G3e|;aXlQ3ML_Lmr9GM*M z7FI;PMau5P@sR5<@xmEJfOG82>~qs@GNwEr0{qQES3cOgc}O`*IhOUEa=8AoSIO7X z;Fe>&Owg-kbDW6?yOWWQE2~CLyLTfPgKmRn5uOQg<`%uX?(=qP{Jq}M)iJmeNguqK z|GztBfDqwIl=JRSk%CU35f{>UoOt9hKTAIw-1E$pArO8s&1k$F)jy^_uFSoRQZN%> zl&X<@7c^xXxM=VOrE?yoVPwpfrlNWgWIwoE%5i^ju%cYBzp=G{d~j9w0yEUsMv;Zz zkbfjEl2@^FK7zyvQtzCN11AJ4ei71%z5WEKo^@<0-;^62!)UhYxRtFD-4A&((v^Zv z?O#>JphqRO)et1^Yc_+ZaLS_>U!&}{b^XOte2CfP(BhEnsFLv<*Xg>Ot7T6vS52V)GBCu!a$hz4MwtLw{!l6?5td?`3^@l$2 z2cWO;;*-HROU3vJjn&w%Byr9w4m5EnP7)|8)N;k)qh2f`q=qL(EGyH`1?tr?c?$|h zDe~vSUZP*iU+EDzCoLagKK9rF#gqKSHbngT+gv$Rf5j|Kjo;Z*c4iWUq#yX@jMmhk z6IRMg7i8oaoSATL!Mb8|*~HJZf93%p-IS85d37CJQ5)zsvzs$Ay1DTU6n_-KkfWzx zox7Pem_fK6MZ12km%&{A`h$${-W6GjxAgNL>;0Ea3m`@+3F`evBUl4#*x!j=7ua$b z-@88eBm(l_&F8?pP2D&d2};GU1FcF?xtSeLD{;3Y%6g5RZ2pQQ$?;%ZC|K?Do+YDjn43CRIEh9V)HDraRN{0n_%(pD;HQ?oZYtF zxIGw7uda&@LKX9uo?{-f--q?7tFi^zYj4FYV{5mwMa@^51mj|i(T&hT8kFNmBBdEr za-dxBM@!(B6*7LIFV-4f`Cd#JJ+_ol;WQC9m%yAV7$J^2xV?tj$^YeWEFo_Z?hnok zz$5f8CDHkSIsON7e)rz<;h+I$AXLMA?>mGd`g)OcxK_t0Wj1E~A9ZgT5M}m0fGQ%T zf^-Q6HHbSo_#64H$$izr<~mvoOv=YR@0v_p(E(%qf+#a(yVUHA9D_v8IGyu9(8 zr|X>OR?d^Vfj816cRp1WWjn|-$)`t^Mip|1(K8c#QBxwx;lz%ufyL&3Kg{g#!nWR# z8u6ldls9VK>RC>N9jy5A03=e}y(@$mjp8*udmP;D#xqkVB3QrYuHpj|BR?#ZCohuJ z2zWJNO|^gI$xOfC)r;0-6LU_wL22+XXT#{=#CD0OAoaOAJ0bd*2;N}_jf$oPp(3|- z6MBah*7oUB9QU^c^GP}Xgj2a_kG_SFRzsttLCGK?`#AAO*P-x$}ual+(rppQ3)0`OUi3ZqM}SW zHxyz?-}5SR87XhSc)bfscgY_;ofu;~Hz5gPPMe2u%6y?n)19K| z8%Dx1=o`XxN--wd%l*vythe{y4i?Nh!*1>20nz6ZcHJCa-6#i{iJaDhp&f)-0sc;7 zMFaPf?MhCVZa1>ypa$tW8B~^`T3d#H*YO&BT0JWr<|Jh&O)+=u5F`wRt$@x?pWagF z1>q=QFTZ$c!URL|sri4mJ#N7FVCm82gYZms+b$4CL%*v>BRQc)O>uG18O;KGXYmn; zL|`7oP~K)v{5YS&c5*({8_XIzq;$Aty>{Yf1c@QXs>4E z(m#$`<6eJqJj5xq9;j=jR`nD$T*D1f5PoY z2}D+6;&}=`jex}i!qW1xa*b{=0V4yScSqxWpRQ3hHws;2b%JQj8s^`}Z3VJ5pvv=? z750VkVXjT#yT%>u*1$a8Oj`7t-D!opqu>bY{}gGQ%K^iG|K1bt{in9d_%=#>yPVfB z95=9EhUm}X))Ew=N|)u{r!U-_c_iY)F#QR_25x*cKcRLU+bsLLMfwGsEYe-l^?^s- z&t5@ed@xeC>zP%^Nml(jO>^UDBeH5J@deueD0I8~kt3MckJ-uxLaD@QgyIL8$C8M# zWIQvOqWaxq{u`71L7E5Gfx)#ZQ%m@NP#XLcwG@$#RJc|BGRVE3zy9V~Uu*Lv#@I`p zdCCEdy}oa*D`8wGc$BgG(Ap3Vb*fkSm?YZ_V;PFphMZFL8b+P9FSi8|Hbld+ZPK~{+DzDIL|1;3?<JC-+(kvfdya8|L*(!LKy%nymOzPwutu|%HThU zSP>`w(6gbE458-_5WU8I*lR#1Q;qYiSR82|5ZQTJ9{ zg-_{q?f;Z%-rT| z97G}rH0bHB?u=EPFT-O!UpK|~{#O^y&rbu5`6yYsw^P=CUby^f-yKx6-h{;4kPpSG z!I2$|FDd>HY;Y%DgCcA>jgziYNSyEf;wWVyNnTsZ)tCR9;TP`%6mW$H{=FWO|2V_a z!Xf8T?c74uGfj@_IHzQiJ3liP|9;62xQQ+esHHxg%%z3OD96AJDRLWnNyGwh0vIe| z9N?XHXtt4IHbO?BKlfV3Quz6D=vy1pz+$&J|8s~Eg@O5!<%jK}Ew+nQ+mPbZu3MiR zh8??|ix^ahu44Qb#E!ho!6uKa!1}n-5-TNurOv9Y;F%m(QqE=@4&SM zo+}l3)}KXeUGF%h#ML=ybQEQo=C}K@GM!#0SAQbz#OUICi%39wS4z}s(q^MNHlF9N zrR(Qav%6DTUPQ)@e>y~$iyy^MOn5&S3KXjgBdKBE_M6`l_-=;ibWesmk6B!h>=SAd zIw_PrsW~_{vU8Ia3XkIWKX7|~X{9b~KVw{#ZI4W4VrH4`Dqf3T5E)r zd)FVpg!9=wGSSLR3MM7hNrk>=m#nkq2>eGY+MnO?0^A2J9G>MrzkG@APng07yUq(% zwz+iu{i@mh8fJx-|9 z(|jn989R@0Wi7w@xeQn-&BodMtL*|{Y}(D{)~wt;+SaU(3|0&I5!52Bqt${_Z7d%f z8W4JZJIChuss5=egGjyw`*M$^J-X*^y<>jDSGnS!`tou)ya4wMwuSs{r@6XnDn5!hAl1#=YKNPb)X&!*mB*s zYUEe%Gk84pmdN2;xkatlOiBK$ig$^yM+-@{=+wwud57k<(0kBzZA#^A)3#yrVx}fgIvmtKklk_ozZh5Wl5x?w3;)Kr z$r!={GhyZ2>6V?{@-I|7Z!a&^DhrAE`fAsjyz?<0h)is?!%ler^dXU3kX!JvM{N}Z znXI@Wk|{~_;i^Xag=G;}x?CtGLEzQ<`g~C*#(4@o6!Ex73a#?{s|AcRjo$LrJU^0< zf8_FNQc;l2>+!<{(Qd^ovIt%;+S_)%pJTX0w&a3o>yM&ezYmiMbyP+fD|gEp!a)8&f*1T8}MOgIkw?aV1@H%Z+( zXu;E^sZ|{HE7*B{gvame6MtgMCknU5$}9UanE@9@6Oce2JhrgE8AWG|F|X--_uUKW z2;1Q|A+0-5F;CkI6|H||Lh90++mfdH5h4gBgcO1WaToK_74K6-DHiL_Rv5hmaU=zZ z_U!z?gydKKOkMe@wU5qucp>nMqzTJ1{&Id6fe%Y(eb=wvbcw}^Ti`~XNaHBfwRl*}-nxHm@Lr zAZaMfEhOn_!d7{1rOKy&P=m5B9F^Acwhj2UnEfSSp7)H;;33p&m$JAh4&dB%O4{_x z)rYKT!9qP_TWi_hynV`#>G84r6C9_tBe;uvM}DRu{xnHd)Q);)n*Fo&Ow;X`l>|x^ z0O6j9Y?jMUk;xc428G3c|GRo%q1^nauyJYur&$onj>L`oQeJPOo}!i_y7onQ^!Ep^ zLbHg0LT3}}AWso94{6ZY3Pf<-zl`}Z5>cP{C&|ZG{fGes0Mw71qHz38oOaQ{-WQuo za6JnCtwYIZ(p2Y*1%rbXJM!*YrKGk-7w}kgoYyLxc%*xvoXQOB9aNm`h#-`b&`bMl4Yt{_8se zHL7y>y;;&5_*(R|V!c@`BY#;vGTEt>cvz}_ENS}f;iUvK)!sYsMZ*~N z(Ta+OtP{~bdms3O>NVo={Py4DKp+|Tz^{Bz&r9{7^YpbU|3cCO zK5u5&zSUpZ5f?(R8obMF)*PKierrem9lrksO7p?LvTPClNh5t;G}%x3aDHEnc*Q;6=WlyLFI>S;wC2PE*kr~eD07(o>O^ZbL`j_rG=XnQ%@EmRF~|Q$d_0O$n|6( zUHx{fG@jL_2PY=!_WfJh)^(aiT6N*}4pj2jOUviWBg5ynQ)X9=*b3BkQmP`gV}z0F z&BYr<=s71elkE<2<7SX=C*_r?yK3+Qbtt#|w&fBd90^Nd$?r@FJZ&XnBNYck5$V%=eA0aI)j!9U z#$VZ%!yo2Rvgi8YRAkzF=O%n58%A|Hj%2i*^WYuGK5eWCp6#`quq{aXd>L>lH~YVB z{)feQj5+4BzsXlU;XjQj68JIdD~gujE%~h!OgcNBf{tn2zXWMq#drZW1|5ILJJ6%% zubI+nIiL34&?<#`g%MS1d6Z}eu7N&vs(+j`OBw5B=dRVjuH|_rRmh66djUU( zPaaa>vRv1Mk1mHDDqo#5t3R(3YxpQEE-kjO%nA8*&mDptGvxZ{lMhABm@m=M)AiQa zEiG#m>&9Y92H3`AR`v`HdZ25amdS?qcDwq}$Y%I(R16#R$9U&9JSL z-&10OPUacgg%!7qHs4Tge!`1f&?M>M$Jx6A+lCRJM0FuOre`nMV_^=b!}~nF9}+tp zBPV*Z{mt-}cTNn2HAjqyhZaJ}yyjez4ZZC{@V>y29a}!yru)ZQ_9aE`EZvys-GHVY zm&}Nws2KnF((_WS|D|EfF%;8|=AnDnN{23%c>@(rYQi|3`=GuZ5|d&TZVp9GPP1wMu*5Ae|ixXGA76^ zT-E*OJ5M5F8v+LK%NtX@qgyBH!3MOcG!Q+Kd9Cy6Y@k2Go^e>##VK!B1b*;1jwLfx zfhNAFZRD)ZS1IN&hnt@>k?&DcMG<60xo*-Tm9Or6wE!&g$k(8-!v3h~n?#+K;L{FW z1+fxgX!SWc2`z-Hx~y^5xat7H^iABbsBNaV7P-}#1F{|0Wz^`@Eu6k=YysC|nz4L# zj{kh)iYW(DT5>2Cr+e5AxZbzuhD44`wpLe^$LHVHt!VsJfpOsjXTHk9?#B(XrOQX! zCfT$=37F`Ovm9*@T(hD#L5+{#!hf$3MCl_BJaDp8U(nn#cyFgFKD8b+Y{b& zZT@NyO|jh8Rqxh73g;JZa-}+twiQiHQ3qv*Um%V=3tVb7#Kd8ex=s2I=Nc2DU^%A` zvMn6d%ALQlf>Id;_^EMnLwAJ=ch=+@@#c0c-InAG z1(0{mkI#EXb$QZSc{W$FFN&U_R2Jv(a4V<*TdpbZO|iAzShC^Lx$2M&$WN6dI;1p+ zKWn*hD^RlJLR_>&mHCju{Yv8i(9kIp3KOoKEhnK3Ko1*q9&-W{50~IttQoWGLnlZ? zZ5>|Wux!VnO>C3#YIW(@SLip ze{4`zj_4sg)!X*AOe;3#ME@#~V6MY}-?trndLCLEmOw_m0FOpyFxw(msuIyo=@@wV zdY90jK8T)FOsXZ1U#ep%7cEgcYv}rNnmSe4K6XkJI^5>;S|V|wlR)oaBkDqM=_XtP zydpO$w`6&IzTN@Qj2t~t_uX7&-0QXI%ix?nfr5`djl`tz7=@ z-SA{lqTY{J{9tx;aIe9ZBj=i{$QPDlu-S}uU(dt9Sq-nfG!!l@K3b+bz9K|Ir!v62 z+b?FT;prgO5hrk)(7T&}>(bmpTGkxBwe8J!2c6$X&q=jY8?lTq%IS-X`ebgh?=9f) z#*F{vl)^oj`z$}@^uc7v=~SJew>(~Bz?WQvJ;D<>$K^3Yg|;KZo@cc3N87397&bY- ze1}r(%@-qJ0qi=AHEV&>bZgRlP8e>zj1%(t{M}o@NsnMpOBp;@DPrOxC+Lon1Swf9 zWZ}b$I~?dtYpkARuIbos_#ZDrB=vN{*Q6{XvD=;Nw_y)iXav}&%Mk=LlNU^K=%6Oi zcf%W7F6HAn@Wg-sDuP(v*ma1Bg~bjkQIoq)j8E^O-?+4w6jpZ&NmJWgF&Q)&S=yQH zIFZ&4N1Tf?n3m|fcihfm`QYQ9%7phQYfA($f-mzA6guTYKt>Sqctjkw%?E!x_@v0Y zBQ98zONNWf-VhJ0Og-Y z0^OrmOk4IB_ijWZ?9Ww7T=I9k8kiQ+u-kmp^QxRE9nqORL3G&^Y3Y=*Gc(}sP8B&? zsS~Pl6x8 zq9mOigDEuIS67^r!^}wOCNmje6tB`B2I7>Tz4xxrgbHMQl3<0!*~hU)16!=c(KbwC ztF)b7!1Qv2HiRy6!zZMvxpyuyXPaME2pG55TMHP&g=FTQF%?ER$P#-=G?mbl`#fO; z(Re?mTaZr%sl=reWZi&tH5%4y;`w&7#)5Wy3>TUr+~N?XYEE%$I)ZTi^Q_(r6*Bi& z($yJncDIX@`tOgejTkDPITe!$*3+MPch8w3P~j=v({9!ZOXNULiRyfO&P5FQ2Gioy z2M$D>I&)u_t&D(e^-5JR+6f>0y3xB-X4#yKd~K-EcfwJYwG*2C!g|}eNyRz|FFnR# zTR{OmU4`Ss0j6Ql!DxK}^>Btuw4j&BmgU5Os})LI%||Jo!b` z{%KN0wDcXWy0z=SnLe*}k+^YeZ>D71~)fcT(PeZtlno8Jnke=f>ghL|&2=E_$oVs#%()X1fb$a?E^akyjO z+d4g9@754n zc2p%x$%bh3*J0bX5nsmqDUE6~^40Osr99d*`Z{iM9d0mSM`Cpgk@@QDf&>M-G>=u( znWt#fU0CBOqWzVRC-nth$QIT5@N?eY_)UFejXGMS6HhOh@#Z!2O1vGRW-9#IdD|_= zV#&`7$dgo(E$;wTnQIQ-~r;N`#ThL;DjVzyT7(t@# z$XrInLVx%`t=MFI9-^#&QYPgVyxRD4x?ANZS3U6?$3+zuUdFx)gJ{x~UgK|XSC;6n z*l-s~%gj>dS>N;Tn&UxCT1KEJ#spNvoS!eT+3tBHHOB1|$Q}cs>`208KFH?f2^kf8R%*Yn4j7q~{GF>Evi5 zIc*0}JvSEE9XL4%eWN3)Y9V&Blx}dOJL*+g&~T24hU<2i`Xkp}{?q1B36_xDQ&HDz zL+4;<+^iMeKI@Y~-J;shDApfP6cNswOnZ`g)GpkSZpMow! zeAEhYap$}qWV7c#Pw)wm_Z*FhLeqJ3C^&4s?=27c=B<-2l-+ku*}frVNxf!}^>Jn1 zq*Jzoce!Jy?#`fbn;b>h?ZS}^dL6sHx(7t|dbPWwwyZk`?N6OOZQTzIZ`sKTG?5DG z#oEt#jJUGc-Lt6!LWScH@l|wl|FA&6pRxOo7z2z=$-bBR@$K=#7rqa#3w0KiJS~rL z-9kE0e*3EcIRKjKe2_~`)#fh`9XhG<3sQns3eG(Qau>Yep=%Rwpeda~D1q7x84j-) zQyyrmd-+;dzqz=3R5-rIP`ti%qy?&cQdD~=;c7LAiu{aHcuvAQAnp|=XMmnCc;9TE zmOQq>S-}dj9^>M9LH14J-e7|J-Cz!b(xeWaIM0XbevY4!@KW7x?dJhQAzI3QxgD(? ztQzKLy1{d<X*pT4!oHcF*1a=FiKpf%6PicN6T}#vLQBh z?_0J@NL5(U7m6!ghS3%jTrUsxxxZLNA$w!d0>SRD@ewh zmDX~?rz6kg0)vz#{J~!lS_TM3C_;><)+Mh#Mj}vQSFe}|$A;<#gG~^2qX|xcxHCpE zsr7#U_8GAM#);)V+_C;V;(OV+5vUah0k@=qi58|PX<7`0OU*4qwkHs8Z?M{wX*(ae zn>p%zS+JCw2&C&YkuWDisJt`hVOto96hsOl_CHF?fU^)D8QR%2IaXy}IiG*6|Fh?&z#EH3CJTq{7#sLJB~OIwa@*){|0$M~s%g!OEa-GAEW6*$R6oe8 zFAhJhm${R4CfDH8jpiH@gV(bqy*ID3Ykb!V4J^$??CPjV#rqf%1e&mW)M=>Qc0j#R z6>Z)hyX9Ii2&OHW-+nXCuSHA?>1x5pCht5xNpO3&35VSrZ*!wAa^Ex*tBxBA=bqYtik$4e4EOV0JW{7x2`-GUbR$u*e&3zq zT!0gP_hs`nN>!EEoome>e?KMaXD|;0B=#aN>UDPgp(>c2xLzT7D#F$~-^BQXq^}-@ zV|K5`YBVs0L&z>Zlx(ZqY;1ES8i(!Fi?e2d_oj4eHe)>_y$!s$u=Xef{y=`CODWo* zEuy#AZyqtUy@4eUnUEIjJ(@{v`F>2=RO?BE@6BW}AsRJ{qd5YE~RXKRIDk$$lq*!N@&1N}v!DNMw#U zD_f5xQifT!PSj~`9LMkwK})EzMY2!IvG$JQkz3Gc_XwM~%2AIb9+k_?JJ3G!EmQOw z2m9~J<_n~`21z?NLLT-5Gva#pYqYb7g?(i8KIWPEZsuyrw13W;c)rLNqlR;cXF`aY zq(r$NA9QP=AV6xlQb&tp$iBFdYc}-eWNe3EelyNH*b}FUMM4t)@>&mqeCD0e2RtckG3k% zf-@24lzrI9wYy5EGl;h9*Dl-+R*-Iy6K6rm8RC(v5w3KEl6o{}o_ailQ2{YY&kQHo zVyj}B9{S1{$fhqa``eES-T;$^0#`6X4e!`XFrc%tJc)VA;^)C~Lf*~lroXx!jr zYA$bB`l{2BUE&&k2p?UbU{TXmV02`DTEXwsCCz*1~>=C`;bV0X4dOtJ@tBX+PMj4cCIFL-sS) zL&DZTvjZU|P$?y*BuKLUdy(c(2l5&U3#H@N@FH3%EUZ`2!EXcJ4QZ%qejiVBB^)RZ z>?yyIg%y|#%nZFHb8JW;E%Jm3*Ifa~oh*ycS>Cn61Ybydy}kMVaWK#9_R5y>n+nGu zAMEyrhd<8(z;?q(PfeknM9*eWXDS}l7tNDrAyn+D@AFZ0>g(>K?5)QWc{omgrs<__ z^ICxYVa1*#;Oq%j5EIt?=q%&ZJ?r1x2)y49nzac{|97cy@qdhUu757r~dSW9TnQ#Kc z_`28_n}kJ`C7PSQQ6D271N^fM)ELv}DCrrq5r#`{_4e5I=e4tBnTUCD1{m=gRrHPg z55<6y8sZ;m6=UFxRQXcpk&u!xTch(1wDhFTV(WP#4AMm<0?)0btij7MO0 zn;MgwSbtA4U*VOzgpsH{7hRd~n(so?rmruAiG)lfKMVwqSX*z3#iV`29C>IHFYqdp z^E%$CD$A%_)A7wU?zxPB4(%?VO7*!qR<)E$@6YWR!G+iaIZ2XJ6j9m>kd2pb#Mt7E zSSr1NtxgXbD8u4TH~F~H6Y1&AuJZ;b1o+AW=9?dd|+kQRa3Yv0fU@#L#R#f1#3za}+`6}@A5*xrhWWT%4I z@72XD*RiOW3dwkWiaOI39^o5IH!33-dEfUn)1^KvPr5&s1i(fATBNPDy22p40IY7M(GaQ0gGNO2@HM1Onu00Px) z@GSK~m%!U&OqrP85)4<&?e6Qj-ulhfVZM;q6*mN?oEtGJN+i%zKWlt32)OVnV+7@tMFBP>zq@P z^KK~=KiwNWIp~q^I;+v4O@Un5)6(v}1?;G<2Xo#$(;GNQk|oQ(1tSQ^si!QzzeDAJW4pzOiG*?Re7acZ{C z%GaC?{R8nIu)g?bS2#s(aPZ${I`gcNTe5xSq-@XV3pnGWgEp)>vb68>d?q~S@s{oZ z^+5b3;GoeZA9#!O2?#qwSHEM_M+rNOyY8hApPZibHlkD{c601wrQV9I)AKrGvGhs2 zrHhd5Bj-qS62=)X>smRmV^h?l8YjxWQsmmrZaY3}8ME-oxQ!j)ls!O)alZb_yACIY zb3}dRw>r>a zF3gmow)9|^_u)Pl(b&;G>txB2-Z0Y1C{oJp_b#t+NAH2wKZB{ubSTdZ{lsRmyRW16 zOXeZ`RGTzEr&kwg=?ky#WG@jtNH97d%)tSXD2#$W<&4v8NKTWU^*crIdzd%OqXqYEgcT=OVySDB#%q~%eq|0Gt zgrP~p!z$m13mH`>f1U~=B0VK(wzcd6ayFlj9r)6b)eBSsPO7m+B8wYz8=!?fE1IS9 z=p#`|J1WTPAmVMfVNut`jc8G{uPmyAHq9Kr6l1k|<@lC4Xo)QMrk4s-&|1%}So5KV{)1if`}Y`m}0 z9i=zi^P)KNN0UQGJ_RnT1J`fmwQ?SRJ#gPUOPbBds}P`{ez=s5=ttZ~+cVIaysMZh6dX%Kgqrho##Wnn#TmulJHf(n7yaU6v90bWzSbuU)o?0Ls{k z<+8EY#x7|0j|;!EHpYOoaZ38vXO|5y1SLY;OHWPDvSo$1@Vuxu`eH|}FK4DI%gY$# zPUYQZTE;UBe2SCJi8Zi1q^u;pCO4xqySG1)A}lgfrK=|gVWVyZ4u}@vR1oM)!;jg5 z?;>H5p-Fc|ud(QbDPmMaHb36m<5^O)mXm?)doSdJ=Fx|jGU(&QEu- ziyh?qKM*g{U6d~$6h#MUNjhhwKeb4Nb!x|WsoxAPa8^#1%@~I!Zv-@E3sFx}S?`2P zW49eijtsj`bhy$Xd`D}$tnJ|7^u3Y5f?&4Au}QT6bQ?OW_aB~s5vE5}>p#4rD_(&MGg!wfh`PE|Ds!DTgh+881q%?Va()dNo8G~Bzva4y@Tz(*&2Q=(gyeIUQHVMkGv*X^^T zl5Jxl36o7;K-3KBX-mL%;XAeW=@=6A3WGF z`w%{hlndN(dxS#N?A2RQ=N^I|iqnJ%01=t<~p zVaekt&9(A+v4T}mgeyWe$EH|pUc0*nWIp2Slk*}jyrj;49ZJr7ZiHPAs=jPA7$paJ z*!eK8tqO_Bw#!FHbnChgxG0p6`;lkdV1O|gu$^h^$`uY7s!O1o8pak*?T5!=D;yPy zG=gsWj(?n*bn%78aO@l;wm;D2YS&=faSYAA%*SynW{gni+;M+=l45^=x%8<3yXzgoJ>UjSg9QamSmcM*hvuYospC3R!x>XM5`w8+ zruIww+oBFGJ}Rfond<)YBgLBqDW5@46AeLMWi}D zV0Ksy)x`{2a-HpMGleagq$bS45mkV3>0DQ9qoCg45umiG z*o|-sJl;M%Iyi2G4)iZLQx1MtAMz5__3S28$?D=Mt{YNEe!3K)E{P1sGx@}jsnu6{ zYes`&bX}~ym_LH`+m682n9gJH8EeA55L`6=hq*X^CB&|QdnlV7PI_vT$3;Ofe22|K z5^9kEULua!+8I)eJ(IGr@_d_@xD>$IkVe&ta7j+L&kDynUu!8e@hltNR^p!4OYG6V zv>BnQrpqGVyr^<$3LD?jkbf3Q5e}ri%i&!U_u#DYliKf$U5966%q~RyKl7i58<9za z24#((X^lS7m2tWj;l8{nWr3d1K(7={9^0{&_HNbey0x|S8*VKp%C`}f2`k>hO$%hF zv%Dr}f`nF{@C%M{Q`ZcceM`AS*C&ShV|xz~94&;Wo4#BH`hAbtNsQ((2+ zU+EY+V|uY{kk_9ofXD-2q&^P(k>=4Z^_ohX$-&*`Vd4D;Z`=7`+y-9C+rAnlMksR6MUhtEfECR42Rgw%8Bl{F#0>ekpi*DPy z7rhg{&7EoxUs5q=h5Lf$+67ZU%%QmN6HSfPch%BmCR{f}42sntqvcLz&sOmX zJK3}>-}2|+dr#S8;`^Blyn^RATSRtrwBHY8woxl=43E2Q2{(b@pPaequm8|?vLF!7&I#z*&1f%!H2}zG-*^e*t>}ie*4xGXQp8d-)_=aA}kz-62oT8)(+(H zVadfR^*T>JW=Y4jMwfTU_jOPRt!!!98m={R`y2W^dMQppu(&w0(7QzS^3VBHSAL0S zVOCh9MOH1=JHIx+P!(ReFJ0PrQMJ6cJdie%IO$Yghr<#n45_nK;teG$OvKD2yR}c& z9$)J|aTa`nn2oqqWl9CiHey#X9`p=xj!#Rj*Bp5zV!Iua`Meh$G@7b?W!lt$^2^Wp zBf|);UkpP6V57d-Gm-_HgM;chtOqC+b!bu$5DO%LeM zsx>ZWBI4rLXe5ix@f-yXx#GAHc?PlD)qMCDbyVFir#ve6T)!v& zbI{b4DP&e^V2+dG1wm#^P&tQm+5LB!d+I$dH{6#DZ;VUmj0PO2mQm-9;&})1#%UAy zubQ|=gpA=L$3%RDHQ+-l9wZDTIYGMycc&)&ty-rvMZM0<`3yHUjijs63xnQ?4H*$)FX@3X zHSX4r3C~DuQa%xo+WLefe{F;cIU-1I*=JqOrK5j3rCvE^bgyo*wDj2NL5k>CQ7YUE z4b>zK_6D!t(p(|6|`R=MMh0?f=HYz8JQPL z+WmJX-B@#(EU_5o<-z&%n1!n311T~)7uILEpwQ(ZMU}OkjcB6~?w5B)CfoyrCe$02 z(5hi`L-rSa(o$nze3IjiRu|4yYSQd|(!BRtq4ino$%C8=@V5Y4J79JVfmt|~1zWMT zu&1@w{41u{8Bd-aOyE6%^#mC;^t8`7Hc|mFyN?MlUc&qmn6ox*`xhhq?bj`=&~ax2 zg1ym)93-)gyw=KF2$$_abKm_28)!4R0d#U^BrZAUw<6^^z-R5Ohlx$WQI1 zdA@Q(KtgA|GS{M6(AXaFbhU1leIzVl^904|`Q=>E4!rl?t3AOYc(M%psuc_%mWYDy z4tV}r-$K=5=kY!AdOr2iJVhSmla@}P_&}FgdbWNbb{-gn#uNYQ<}YU80dz}Xy6c+u z?l)2qY8`w{{I{ykLOm>>zs9YPbqi@&iV(ZD-{x~mXA?l4#d@zn3WnA#V<3+P<3Zl- z2QGEBp5@ck2Gt~U`>BpnMvtcS?}=yFqr`a#Fc1_iJM*=AVJQR~NS3|-n8wfu_0ZX> zGbx-VZ*2^2a`hj=tadCL{$#KI%@yiew$XjFQWWEi@3(7{MXzga-$nrdTTBMVGVXP+ z^gR8QZrwG%?#(i>+QaKU_1Jq&t>&>8WISb9>f>lpN!XaA{St)FdA+G#y`ETL3o&3< z()6rrg2}on|I<8mPOD1Iuz}RLpN`1ja$fh*!Op6ieJp9d zPvTzRGiPBv*(2E#f_u)5+{d^0 z#=c+@#FdlS{YzCF`vG*BKQO+e(G}hCyFv%c;J+CIRMsMo2k4cJ#$vy;Z7-3dJ#YT! zY}K18)K0f*C766G?Nz-em`P;*k7Ta8s(@0&{q?ZU~;- zaZ`H^EgJ1<{c4ePR^Z$u)w)*2BErEKo@dZ)`{Mf&|DwCa zr4SH7iA{eovGT4JH~34~xGfcOh~rzUGF&<8e&$$`Gg_jzso{C6Cp@ax6EaQ&FFcB? zw;Wp^AxMH2RzMD=Xe7qx^sDa|#opfg-X%2Ff^5U^P z#YJwe?l}jHR6CVf1O&&T&Q06x)tdF*mBdsnFb!FScrBSvt{A?U2~yI?93)-}tDtdX zTkaj@NfUUhT23oGB~x4a>g4^se@m3r3jndYrzp-||K^u#C`1_gO})XT>Cp)z0FmtW zy&8J+k=Qg+bArA8ah}CrN~YRw8+-~&%AU=O&}+WA3DRzJBC2V}9PhCZ^G!G6*< zO<_3M=I@Mt2}njSV8sS4*+l669M{TS+>Av$93EWt8Dnx_dpy|vzUxyqY}FuM(@#!s z!%bN(be`dm7qO%+8~V)j9N-t;4s-e^ zVzJjMk5h8pgsP)2Qp&Xl(^Gk8Vwr&D`38i;8VtkuT3fw%CPvql4ww#-!U;WtW! zHk(-Wk{o~XxNCd9t$xAky*rqdBC^jW4{-2WJ1BYH+xo_4`h(lzHqA{vbzYQByR_c= zW6??C2gL;X-tEiQ$y@~+o_OgedNxK>bR#08uYRE#C{pt z79n0X4E?~!tB}yGI!K>G+&L@oO&~R&{gVSDNGVudqdIN+cI!^C$s~?KowxS0cKTS{ zoNnikZfuJ+3XSI?)p3_@Qw9_R@S)q*%V8wdy+rn>?`?0T?KdGCGm%3%z4Mxm3-@{3 zN)@;yShOS+lCDbPPu&;Gpt>9o%~_u#aK)zMVKVERu_>%ll<+sm)jRR}Ylrc%eF&g2 z*V3r!>scXKG^ViA)88@#^Hz?TabW~T!=C3p+QEiYpjN4lsxQ|mSPwk5TlG@bT-BUQ zSd*yjCN_tgiec{ZD7wapYgs>iEJU7PQ-r|&h64zYl?Pa3*J~o|VE9P^GGH%vVoe`+ zg-h48=|u!l-D?sa29YDU;WL8Tqk}|ffRna~_st0dK=F}sja&)re!3(Oz%*zjl6e0W zOzozSMhfo3Lc{miq|1I2;_{Py2A6NO=sHdsIYe5s4B~l}M0fM<{r2(xn6^f7$$K5z zV;aqc>Stt^t04y~h*rPRtGF0qwV@EE!|bptdQ7kIq#G}p{wq^zRCLZ5H`HyyW~}6M zew7KVccD^+wRP+NA?>f@nri>Yar~B00To3iB7(&vMyRA9A*BpyMt3&?0!j?0qBlc8 zkdW>gF-A9t4y1F$C?zCDNR5W?!Pl+s&iCi{`2Ba-;aun0d0o##14TuTk3U9!eHlGo z!6u#>Ipz+I$$$NWNhFL@VFC=D?F1D4L%Dtu-IZO-EDo9^bSwYub7<>r_p zcc_$cE+2QqKJZ&8M42*UgODkp2>o!bmg`zBEkxTUFxmP>Ry*DP;+avVefOsY zM)c7Mt7W{EH4OtNZpz<{C{tU=UJb<)Q8jm)kYQ6-P)0hc=vNtn3L#+elNy^?mJo2GMe`1Hb`$8e@~khGORTIQr8E6HUDY;=xku ztwr1$kS_5H&_~-l~XLK zRZuxSqd+Fe2mWj1fOvW6(Xa5*Jpbi!?;qclZ84J185(~{Ep`G&u;%0yTn!sTuUi&= zi#4WU43{R`^VV{USnKA+w9yrv(%9ux)oQ`g^loL49V?S|GdkI;4%0Ul6Tq0KsFXhl zCmQ6lW|~^OyfCoQX&GNYQOC>9qRtwycY-T6=M(o(F%4LDOVL4-BSy^jiXU_Ep^4-# zsVn>PL7>izpQ%R>`cgN?Djzf{k(OXy6v9+EMCaIha_Q($Z1T>==H@BzU5C#=QN;?~ zKv;|(XQ`Mou^Kug-``~XBu8i0n-o(Ol6$RZ%kBl}aSBFh;R+vx?dM#-X&XlD=xBJm zw0(|ySEx4heTG;W^VfAVdB`*e7sl?A)6iXA^gYvFf03ZLS|j`G*Sx;%`qv`XLn*kD z@_ZAga#4khiOoI__oIoJ{u}YB->fbTO1Z%?ueQ|pny(UAWkE+wfoc^$QgVaZ6Bci2 z(#p?dJK7{0?T<1uiE&;sTIH-xi$VuJN?H6|GmFVb{tb)c`~^=B@NeW;AZEYf@|jAq z>0?ShzBoTaat7-QIoqCzeU`IL1+P`C_H)Ghvlbn&QwVaMmHu?ZHdppM4lY6a$l6~h zBGaNtIBbP7qMIjT;2bAgcDFCcFw;PHq!9nvDAJ8Aa0q5~_b>{KmNtI9sAIM<+8cPu z{WX*5yaMI15g6>&qxX5!j<1LNTqC7vSY`b*GJk>eGc&oM`;;-|!uHAy;a>_CTbH)I zTYU94Q*br)k_t8o=@QUZQW##^L(r{N3yByW7vQxKSi4Z|E!8WtZrpS~z*CGlXZ=`p zMUJMH);)J`i6;$~w+i|<#ZnVBu73k9SfbNbTNY6HQJ)HUcqv4RmO|U|+^vk6V25h7 zMDv=lAk)sslu2>BC@vuRJy2Y+v~I3GhvqIByUUP%Y9+)!xJ>a?ZMIM3eFyc$mjgEG zABXLh$7kF(KFh#qBkb;b{RI6mF#8@BC%&h=|JwE&&Bt%Qk}yw-(e4B@5K$Lnep?L^ z&MN0;8BihV)AqpKaB2mK_hmrSdhG>)WpuXg-@N;U&2;cKT+5^hs&h^O&zPYt(mA`K zA;h7g44WnMO6Nb>)*jwnlrxvbksA!#Ge8Pkh~f^>*`sKn)x)|qLZ8|evSz;L2@+H_ zRlj;$Xj!*P7(Wm==s+bj_Y&yq+>xziXl#V;z81eUY*=(FK6gSQ)A@n3^9H?;LPAQO zXV#1(|4%0U!r`>FE#L^Ew^wdH{)wtG)c|2__haTsSZVcm$t~6hwIT8qQ1i^{o%PjONh3kgS8WZlS^A0UmD_x8bew1* zc_n@q=m|ri)4NOW+IH7V#+kmyPAU>WiNkP6JZ452eAh-WQ#*l27pNkAt_fxy_6YCUFo|>5S(k9D5PPUtKEw)bRFA5QaVpAV09Vv9z zPNm0FU%Nd;Y`0-`wGwa3$IPy|rOQj_OFXm3XC%d7Q&igZgY^glM-78qOUHs&J01`& z|2kg5Yj`MimrYp3H^`V3X9-=^~y>YvMS8z zi51nhE$wrkwGc|_S?xi5eEET>6^fGkHv9TeA59#wy8NCApXQcD8K=8eY~E(zI5Xv; zN6A$CEWU7%Ic@`lzmA3(bN*#Ec}{MARIzXsl{6R^SKoI&;VvY(7h9vStLFPh6J&3k(?1^_m!IcaFNv_EArQ(lLacITe)VZ`=V>gv~ zcK3`u^#iG=k^xjzsjKChm{JczqDZwGkRO7~;J1xH25<`yK@fsNAohAfV;$A?V%*I@ zPL~w&phJyz(G}Z%VcbR<)rwmoZi6z+x?#HWpnHNe1FzB+I};a_1}^H%lQq4F1<@wU=9IsR*LP2< z68coEh_pfn42qg@zBgA(J8Gt7-^<*eljsy?;Kg^dIdt1zF7r7()>3&EEf^uWo-?jN zd7vV99MBr}dv$avw|FoyX+kR_6XT0x<#~^NH@>hbTX<7c{DZqWJ@bKV_tF=i&2iVc zAD&+FEzl5H+RxA)WvT^IhC<%7aJ0?y16uOyS?!id%>@_fX6C7JI&_-459} zbA2x_vAe4dy3Z!RHNfHuHq?_KF?(rmGfkLvvC{-eYqeRJ|~Di^f5r&b!uf zndXJZidM=@_sr8GXf-w7o_8xDjwyaoUdH&%DQVGr?nMh~Y2@*mp$||FVsBqHpV!q< zl%}$bn=^67dReS%7))3dRaQ4FMPKPDX{0;A0V`aS}5e^WIVpAqtmdm zV{2Dp6h{KZh%|Cn3r7iur;q(AaG zeMBaRvjw$+M&^P9TfP@~*{>Rxm-Kva07^Fz4;eYmaQ4}&6j~}dr{rODSU7$N4=EzY z*N{&SI718>DUQkhGFOQY5Nx>ph&u6mN9S_p2#9ToY#st5Kqm#o zv0-PW5JVMTo7p`YAd{tZnO`Alz0A{XM6?P{np~H19I%Iy9uQ{_*E(pM(dw6?GF9?@v$1TQPmuH;toOcUO z-|gQ!BV+Phmc0C^6wThY#&){h=7zuMywb79lJ*COokri5F|MjvL7T-MD9%HjtihT37 zKMY3?gc4?%1KDdAvIcTgBQ9Dc5a*iAG3)D~U{;9EVSVWwy|z9~`dm)>VKeWq*7`TZ zQF?2;x|=syN$x?Av;C|Tt;r)+ z$*mmt#x6!@A0Wkdyc}3?+qs4Y#n}YZ^W5x()VlqMc^tZqs3tV{Bm<0%&2X@b#GhIC zdiL>MJKi=eJ}V0*p8=1QuI6G6a@!)tJhhkdKfUVTv!t}cLPzx3++PH_p#B+t($3b{ z`W`CJ!1Zj>C{&E*-Kujlb{x0`P$oKcE(1TCUKa$M1A)-Puj(Xnz>Xk* z{<9|TcQm{A{fW6#uRXpk?{L=d`&M>nw)>Vk>^R zo^-NWyR;yPdE4o|ho|#{ix+;8`!83BR!XS@tH)oDB}tPo-Io1f*7m+|=Ya>ATV(d) zh@_7IY{+)Hn2dQ>OhpTdbG79McXnF7zHt7K2o?*E-dzoQYEfvIQ{1X8hB{g{n$P4VLT5*q75UvhYdqE%f=tdR$k4O!GC+=2hQ8m!=%?Yvmtj+80pzQ zk;e)mv+4U5U6G~-KBXA^1CcfVtB;(eRNId+&TPX z{iLHDLx!q8#g-ff{ngtoBI6&Bo%1R!sC_ByEK(ln1wwP2)6^#G6`@w}r1lBk$sWZI zp0Fv29N=F%_P{Pl`I`mpEbE_@H;T0g{rs)Tg1hw$aNSd)F|rxc4=>83Icu(7FYeO zjaPXK1k2;qnc5F5**SZmGlM>Zb6!_dZM0uWLft;KOrYz%mu^Y_xggjhwz(FaD%HSJ zwOE~Yr6Q65;VVy03 z7w1-WSFGZr1w9B=ezZk19VaZBARZldYU|yDb0+EiEo{0Q!FG!AM7&PStf4^?%ymfF zWO|7~RI7I2ggWhJI4Dm~ZRi?kQ7>R5epy7IWxA?DO|xy`9?}gorarK7O@i?D+;glY zRZOa|8m3~L6+1*-I{?`s!t4`;4OEe1jkZ>W(mtA)n0m{SWD=$NVF3Q1duIVzmtrlA zxJJ~{3lH&j*;QEn|9qI_6~yw=3zmV7A+ycUUBjr1_jF{(x!Ch#QTD{k3QF4v$-{&0 z=eorOQ`BCK8_0su7xiRzax?RHaC%4~`lNy)&PX-j0B=6)yGVK+h8RrK0})UmJsM)) zkf@>~7cO{Rp$6mbzCU$NltI*kFCRV+Y|vgS4)wG6)LJuS2bqsPrS`6nQ7`$eADB#c zMGtI2xlj~Rzg?m&W#S{AmjCfKq4L|3wZM0Ku?h^u-`Nt@p7lXIcKI@9(RF&?w{^4@ z`ueXd#8F(Bs%?ZcITyT=J6F#X+IsXs%)<|1_MH%<`di#n1JAt^CJT;xfg& z(R1~`{r&@hzu!Pa&;c<;8V?)W^MBRezumYlX-YpvPJ-Cq*Zq@^u)d85iV(e~be#0p zXr0U5pEop5b{NmM-?lb)ha)qo&H>3Tjqj`19Nby@i0Pg_8G|9>LfD-U#-Mee%(2}XAL&vBu; z7X6tpT#gWd#4{6@=s~XKR+$$f4J}GxGdj)2+LonVa;+_wVc+y zsrLW=47(~o0J zsc!Mlz#+aKrZi9TK-d1=BmPAZenZd!IU(m6q~-qs4GGCR?*K9*&{1rf`v3lnN-{uz z|6i3RG3Ck2=KnE9SI&4>v`6o&zVMm3pRyzHE>t3Q3C1BIgE3Oa! z@0a{oEz=LctXL&Y`TzZq8Q9?mjwN>7Q9I31|NjXZ-k64B+>&>_5xg zFARQNAtKHKCX(Aj{`M7sD2YcX#vcbBJx?k9eTB^2x}s+ztCfkDX_@{*=Mss)OL3#` zt{sBsqip=KZq{ch^|smJg27Z5ef7Sa{pxYoQSuouKfnNfp7N0 znb}`W0l-*$sYw1g&DMoIJ@{&agJiGT+I?}I=p}Usb!TUy5LrWU5!o#C#ib)2BWG9R|~5rG0O&Dt|KKzjXNm;4o2L zW=13kMQdE<8k^c>?N~clT~uG$1+?Sc*0^Ilsz=<`CIj5}h0CkEr@m9%$9U(q z61qKrEbfM$#&3R{KY&Z@qBIp68v`@>l)XOO-1JKzJ7Z3yCv|!phK{2B(R?IM)>!;V zjDT&a@|b6|ovUw@le8mPjZD3Gyt-ZJ(ndV&|jARB=b~j)}sDC8wvOL z(Ih-djgy^BKGlCNu9z^RC%EKUNth{e-`XZ&&qTmVI7b2$XQ*Xc7*Q zBi)Xmt5RnfsD|t=3RU8E(W7_Jf-_kc(~`g*OaUV#2ppM-$-IY6R9ZX1P-4Scpr(l z^6&nna}t1DV2jdxlLR1h4i&Uc$~$h(mTWmAlHY$4?2q401F1A;suVMcQ2J;m_7%$A z)YG`M@8bNk<@k5!-g}sBh?u&vlTbDK?jO(cdDEOfJoff4JZs}UOgoIE+ethzP^`B7 zj;{qgYv#YgNHu^~P(%_**&9*ArILM!E{fMTTiAmHpucG390Yi;Pxb8!B%mo?d$XRS z+IkMh9~qDM4>HpMWG?<_G094@<|o6;gzseDv6Bh@S8R`8esj3Zzv84G$)hu?WIAmZ zu=c7x``HwKr|wV6xiJ6^V{!5#2}OVme`t>r69MN(`DEaCQrK|qhY)+eBEjQt&j}q`?vrjoBnDRUEtQ7I zcTpbnvn(S4<|mf_`>p8Bp*w$c^EQZtg|=Xo*&J2Xc{sk%Dfg&c?Y}<`6m5~f0vtCq zNFw&brsGsQ&?J{_8?@SoYm+$M{|O(Wl_I&-GdabR`r!zwpQk^6n1~C0!%}eibA?6H z{Y%H!4tLCNZ!$dXx%W$26EzSnR)K)MRI{*oMM@z6I!PU}=e^rhST5O8)0g8HDbp~N zWsW$b1ecR74n}*&XRpv4$-$(@7@07tSY z&vnfRsh-fx>F>4bj(u*V`oU1ED}-tPH=o5Yy{{?G-`^AS|Mz=rC`)jkj5O|KmMJcm zjl0Wckk<4ir4J94s6;-0Pr|&;O){+IAvqdqU%n=hR6vk2r9K~Ds7x)b1uHmA<1i$3 z21zsxuo5Bi=@HVE^#54tYeoF)bAJQ|bL=-PKP5ZPkH+*Z|9+ABa85=Vkx!M;w6IKK?p-7vbu_ROb94;nBpay}m%^ifU2p z@lIeH`d zmdhUu%Y0k+$=}yQ)jKE1J=M;x7Uv+c3j#yqvSqS5DsM8aXZNrRp8%My5?CjOh_gaD z+9t;T42=LO^Moa)Xa%>w|Bi>Q`uD7S^`kK4aCt;(U7+*)(XqYBoFfUXb4A<1J09)P z1-J@{N7AEPCI!qb-y!C{mLJ_dS-#b7xfz<>QQ8i)m%^^!@UC}TO!(mLwy)4RT7x{DgjwdA_H6^AEJI;SbiIySb@zx@_P zH81pqN5~z`97`x`m+j&d+mmyo0^etz#M1|G-}w;8RWhk@X4KY z=Ye}8s;{;IrxHFC@6nasZ?y9q8C`dr7r$2tk*KXFbIAIujr$F8XdLgJ<0O$Y$wd0Y z=oF87?pYr}vf09d`b5IFXM}xYFNVs>o{iTcVVBo+`up5V>@Ix^wG53OZ=e-@A2?)| zyXNx`2d%20!An1+@4Fmofa@Np!j>^VkBEOB{=_u)DAL=Jp<3K2hb~cE>z&NtOvsRu zLy4>Efsx(ytYdKmmW;u)hKes|S$L{=_0G(I5Q=WSarA;igD%uwJj*Y~VOVlx3_Twx zEzA%1XV4Y_Bw+`(>Np|=ysTr#GCZKSTvNul;?OIt8Q7gQ;Sa3$cH zd640tLQoIAJ5MPmlv@X%%IvD@plyV?%M;O^5m##P{2oY|-F`R86y54|v*@l{HfNv8 zn!0ytXZ0ta#LQGKbX;rC_Qh0fU6V$*7{kWQ>M6i<8188;|6X6yxWu8GMPFE&kUIj>W1p|=&3%`bpO8kN zci*E4#}+xKno47#)H{YlZiNZ6cA&ITtzLfZ3kwy4d#+-#zJ7bH_>QmYNEZdMMbW9C ztTT9D==1!gl#!kVt2Jgn#-WbsTKe!|-=ZNhY)y6y`}|`f-wLL_rc{~JQDeX-DHb@O zFu(6Oc9LeN+CqW`%`snNU;B1`!=V~l-B_5W)Cy-n=jD4z^=&x0$phQ}HBaXs{6@O_ z3@|Yunj7jG*hlj}9d7Gc;k9krk@A?Og$TVZx+%MhH=LwH(msXC;ODPQb3j8q8)TQY z`*C7@3!<|;IIJwul8>yIZbqYVOvPIPqZ{&E`_`vHChxzwz1$VMRUZ3n~ zp9O>~;OY*xwgcyszPT5@!bRLLZ&KfKd2^0OeL#8@LO;a5yJ7~rm?S(l_C^~Wt~h>L zEP!Zykby*Vave$Qc1d)v8XkJ$kUJ#3o7%CUduhHHQe?Y>FFv0;AQdvNkWCY|0b5nZ zav-Mxk&^1~B90j?U&G3kgsRPZ880*|-Z6mgc*{CxnwkNFA;!iMAWB-=YTAX7rbJ@( z9i0$&-*-t44D9gC#|j}_5tpB!#_#)qrCuPx#oqEa#fvbK1}TQ669Qk2I7O;3PUv+G zLj&t#_3+{{wpT$od$&sKI-=L-9?GMR@^ZB*v8suRNs19CENUm_4Nb=|Mcrv9Bj`8J zV&iNAUDk;s67tTm$-a3!YhAfeLeHXGgt>0E+S2lT?pchNWzvpa+QyPDV;3)QU@}=! zz?X3mYvOACC%;S*6<{fXDx4y`jO*`0t+u6QtQ`{#( zigss@rw`@_Rx?N+Q2VlxhN47@Jt~!9Q1~R`jL7|hEFuW2v>ha!Psz8_&CJON6zu!r zcL5BXSlQY^GJtB;=sm5`z)7mWb$-9L%f&sz_^$@{3rh#19`BwYow0UN}wIwgG7G8>^@O);Z(nqNNpPgmCZ zz%eS$q%#x2ZX=kzmVHiWQL-W0<2B3J$Y=5Dk9N>E6`u^sJH#DZONjYV&m?mxUS>`- zA)zcax&>VteqzRo5Q(mrLgY;MvK><-eQIn?xL?qnTGHGDZ^_AuFCd68WH_?OOUz>D zG)`Hww^`0$Bg|)g`VuJOe5fpk5LM#9O(Cu4L-c;3E!68K^1nqqe59EqM_Iz1?I6S< z2eO`UDv-&?fEQhh@OuwbXRF;67re^rg9dG}bg|bVFC&~y6V!&NsCQTv)5~BcO{dc6 zy^eZTjEjQ#9eW9a56mRkEOu)(_C9b7t>C1KZs@2Ic7jfIX;>u6?KojgEQ0Xxe*MgR zigYz3Sl%!vpEbv&MX30L5SeIhvPk7UE`|ZkOq4p)!ZZg#tz(%h_x-`WW$Z1bYn{i*uCc|=H7ul1 z1e8e3I6n+Os1vx5DSpaz!2x;qlC5Btof~puxRn;|p5pkp^o&yE&7v1i+cMXbvEzus zEg3gj_C?r7WFRPpV;5k^_EoGdGMFBYNxc@sJwxX7T5J}^!$A?Y`y|qcJ;pBharpY`)#;OUt1CgS-?vynOZ|Dw% zDRq|cf!r@aA%Txa+&hgA@{Y$v#&v9TD_z%ex?Wtv#=t1`!LcMYS;e%g5mmZ0kj*g! z8+rR+{h7G0F@&;tx_BXjvSeuKa%KOZTS3B>%AjUAoNgu!MY9+GL}mRzwJJTI_2WrU zC1+^)Z^X)5hdk6a&Gs`YsPNs{D*z7OabfB!LYnpUyxzqY}42&@Xv1^QO2dxDWJXm&%+`@Wc$NNKHw>bbUpiFme0W&E*!(P#vjSfm~3{ye2bHN zCj|uz67Qs3Pc-A)C@9rRqqY{N5eDS>msbp^wA4M~8>Vzzxnvxq5Q@>^?`~Gb8~cmGw~9HBUgum$ zS}UhM__D%}i%ZTd(v||w&zShjs?(d%M_3y-ojA~BRStbUW)MR@g~Hr`b4(WvZNg#>Ak9_PI1`EAA-wQBH;&iFH< z?QBz@+5*2m-rjQiw0Ai-tP0DtZpthtCaXl{1{$e(tKQ`9?}XnAf}K!(0XM>nrKs4X z5=ttL+R8tR;F^f!gQ-H*G{lxf_s_>T_=Fzawej;|TirM!`bv~O;&{|Skd8skiSBy% zR(M^8kAyUz+DPU$GrbT*Ty3&NRJTkL6JJl4R{_%8HFFZr@T`&G?T;QY8{e{>&Z)`^ zRtIIXm%v`odB6;uXWN#0$M+3xQUI+m$qAYwf&J5rS4e9Izf#r9ov$c?kuJ{(bDH(i z_Q3a1IK zp<)L%$Y_h!q__6@@6_J`yK4?4E8SiOK8|< zZKl=NL^c)3yMRmexk5Ul2X8L57I&%ouYzn5o@qYa*RPh26WD(9kS1Js;D?hMUbYK z0aYQzAkXD3ASdu@C zDSbP}p(-1=B#p z?5}R_uPFQQ>XVFd??<-boIGZOi$gi&^b{9ljYUtgt{h!O_Br&uRci^8{LuM)%Dhmy z$dtBt&(sWatTUqbR_BnlymsRgx2c@?w;+)?&#-WPzW zU&Pn7Y1V34o9qKp;pl`0(u;sC3sX$o}R=>^BmKFx~I+Z$bu2VlQF6jr5vdF z(M?KOE&mke$Zp4C$!hR}EiBw9Zdyw--*L>L_5=(Yx!Wv~+wXNJ(DNYgtk5eUakQn_ z-LTdAul}+**cgoozzcb(7S*s^L!*1&uH)A6&37@!R=-nes7{iFx)+4;C(Kf{eD&{bcz!*X0bEv=?VzV9^Qx%JPH1rBL zAZ$&oBKeH-_SeJP?7^zgt-Q&Y+6+nsHTJZD6H;I2MDsE$N};ofuLX(CJhhKDL5eko zL3;`aS06DI22_DLgI#58sq>RuiA5Z&G8*evXx<(GN;r8UeK?h!kbEdXZ(@??m;+Z* zZpnG(;_*Ho4t64ao$`64_e-X=F%o6(HuI0;g#b~S;YMVxQh=p>%BQ~(2a2?yIWjM-KN#NT zKjv@_(fOJ&q5ty%tbvM)(b{gWghPt2mNh0JF}xZ?+|HDm(sXzbXm54hwIIYXeS4Wg>^J`>$Z=LNb^x*@uONT5LkQ}STfq9U|=tGSS^@P5`Wa0HIgfsxAQMuCcH*q-;!lx%Hsy_>@3&fD>Kb^G^Fix075AVE=_15!6q zjw#r;CTYh5qh-78lYbZrUNx@mBq>#qR5}kGNim(UUGTo+REeAZFs8;XKw$N4+iz+4 z{XT)`6XG+^ct|WJL*pkbA6<3cW!q@49CIg+j15r@e$*39My{^Z5(=CUio=&D)LZ(n zYmD|bH~|}6!;5aIGX<&jigu;O3n~+K#Z}j|CIi5Fv5A|qHT66CFan#WTgkRcVqP?- zL{#0jXHESnBdYmQ%S4`RPQKit6Wu}AKq>U1oOsYwn0L3v?VTd%kPhN3$Mm#Nk#Ay) zF)T&DlkB?&6q2Mx;qhUc z{6=KG7oyLyMt%wNY9CoWgg zTtEpMed&ldSrlR~;Ig9>$>vwBYnYBys!cuuOmw{Ieb2<7I_&Ei>r?_!6f=@tmhqql zkd@|(y6Qr{Y&W($U%$L^pdw|JSQ(0%XDO?$rz5-q4Vb0q$EdGAc`=SBbI2a-wVufO zsy_f2VqI;Z%XhA(ES9uoMj|NYTsP$S;6)47=>%(|F*m)Hx1ou#;&GNwk;7`P!RNqd z6TkMg*PcFhP<&7&SXjy8!R)qQ`*33Og3z`70?~)b)h~a4Cdoloo?5FG9WmTs>9tjC z>hABAljSbBqpCXyV~T(c*!j-s%sH%@#l8QhWVgoo8wyn>n!GBYn6L zpFQ7c@jByxS{Wz5ok|M$(w@wTKEpbT25r@k5xIGRvGL4J5xfGeVX}=7ubd;|o zSTxJZ(xp_OJ^Qd9tlGs4qedcecij0N#gDlH$ug`D&M#M2-pO?#lIrUu=flyynk0Bn z#T_jssV1Q6q5#}=bv;|$hLchmc&@}P2G00ZnA4Cka9_T zJ(Wi8kZ`JZT{FB*I4r{ZTXcy*+GAA{zE9f8hVX_c@}fJ?yR*!Q(Hh6GE*q!Zfj-ea zToF9WR9TjtqtkA*P4H{>CBoE(WzJkY7cPzbEff&P^hyr(Oq5QbIhmdh?pppI}y*llp9%5 z;ga}89Z@lwiPtzLcKe~R!qe?^(;QPv<4Ty$N_@h3nC;aE&`6C)_Riz|ZI(?t&&J`{ zTcc&%vs1^A>ebstI6$Gg8#96A@Q-6YIZlEQn)AGKpl}k3J4Yz-QS<*`RC9*jN{>#H%A;X*nT$$$LcLZpXp&5 z;E3dxtZLc9bpJKgg4NqMcr9U9fNoTKDExiaDL%KzLVuXHupzwO-q~B#w^g_zhF>z5d2K;67K|Qb%L~< zS5IapA@m7L-sj=qK!7-ZGW4>Nzehan;|68`v)qz%B?gZqKD<|se6qBv4$CV9q22qPE^@ zPrv?rY5Ot}&{Aj5JhR66M&>&Y!p*;PYxO{Cv2CBcPuW zJmSEdPujyy?kgU_43ehoue3$7kft^0+J^l`{o?W>c6h=7xhOjguPA~0>(GVmhPC)Y z#isAm22fWwFNQT0hCel@9TvL3kb*xM5?V$b9&(na*D~OV#e8SAn`1(pmg=I~ovyZ- zedOW1*{MZ&FA6d;kE3(*h*fLs0cD8=thiD{76HgvGoSWVWu-xGLV2z8g2KHSUp`rC_*lQMRsx9e|qawU+_6rD~ zEL5;$ib1LRBm5AD`?``ZV=iF!@7`<~iqOxU_F;Q6Y^iH__ql*VjKCvzDslGkrh*J=7^5o=IAVqnu zfBfaYYzm66)A3sKfNbnM3*cXUYxxxat(tbYXCz?8#(3t^g4a$&1-^XJ(>7Y%Og=R# zT3^G*RAYX$_x7DpzE$GACj#?i+XrO=oCSBt9X3D+(NDesL;8R`6vPhzIZyCk0B>O2l?SLv%Lj- zC+0JMKf7M64HWyq65tkKK!7kq>8z`zi&ZSfl}3j6ASi z#eloU3?U85_2lg|%>q(};yh0Hq*j5U5JIlfkyvOi!9;Y$BxmFo_bmw6M3}$TjPHHv zIrg@vq5IRim(4@>;5+)N>|L#SSWD{KN#Fj>b@y5?1Czq**8{-pduq#?1-J6;eVd9| zI}g-%Wu2cTchhaNktHp8)f`L}JuEX7@C*E~IK;rYw*B=1w0xpzGV#%2gZD7y_NM*i zOGvL0ODX1$$a|XB>+w|#bMAHY&)^B8)*z4kFvyGbFbQ8)?lF;AgM zxo3@9LhSw=T#CxT73iV%Jx|NAw9<8-a?C zcKDK8MOh#BmFeHGA4W@xaK*(Yne{9ejbi)muV-+~zjr7Y5U$C)-yX&K*yY`@X=%zIEMD=ar?uTulwjSR{4r<}|^{ zN{k61SLH}_-J80TX;7%LFI0QvBgGs=<0o(jw#B>R*dD~an50L9!9lU`yhMnbsTB4oFtn^P*OD5 zSH2-=dm8lj)znx%=$==OKEm18dL=}!v0BLNHZTE)c-rQ@DY}43VxCcqX2Xh6C*L7W z0BdN$U>A|`$ybnhh#(n1BmXqIaL>6Pw_fJ;gxIqf(+^jhRY5L#40c+W6F(#`e6>5> zm^ZZ7&<5XT6`JdcT6Hj`M9fq0XljkA=8U_QC-p69?n*ibj&lJ0=K}l0@D5Hn_LuBA z1JYImJ`Jvr$$`3;G%zdLxII&O3R;fsCrtD2S1A0zmwO9Tqe_-%aJit& zjqLe-H$=UC{Hl;ewwT>Wfeb(1ERzOO)A4l+^{Nk!jMQY!I7oc28cImdzIEoAF6(i}Z2Q@&vzUxxM$)a)RtJA04 zenQP#m(6q(OLCWPayObj5@M*rl_IPkLR_`kXp*WG-A`R$V~@~c4FH#nWo<^)!-aI! zMkTS=kzbG>KnqCkC!)299aHp7lYIy29cMvS5U#t;`-ahnjeSPyAvT@)jV1CX?Ban5Twx}uJp#Y}ND(B1>nwJ-rjN2OXXUmj zKka`0Mc-XjyotRzio1J^rTzsAwB6>kT}hfXqMvulz5VkwYHJxQyoskj7%q>V7wrvfPpBlT+DoTAI?jTPc3|UmG%FIuti79TS>tnCx?flf=wrD^!VElS>&|?~k)kM-( zIh5!EozTyniaNz%a(e;#AGcc%xCI{FD%6c%8k|V%C>K9DCiI!mDUcp2<}D41E3zhD`v) zaTw_Az2q1Q#Sv8om5~Jtg5l}#aP|*Ri95S6AC!x>NA|995Xekg_QC?h7C=&ch5mXEIBV^Rpq?*mNlV*z%k|$ zs}CT`b|0dVB{Jj+or%4Mi6Q71pJS)AhBNY)?iCEo-;Fr$`mo>@MjxR0_#4H-$0#{l z-wa*x8{<+N>5jz`4{mbjCm31uH|z)5HKm6~w44>KNw?Uk9*EB@l&v%x^7wE7A1E;g zrcA@1J#?uAd;1~5vgF3h{KRIIm%9ASX%UJOvZrMzL0Jg)XQ>F8H1;{j zWoimT86Vk`%oH}%P+sWG`_xCy*dSgc^Jg99psIdB2fbfjF1mD3Uhc(r`*xwv#^T~$ z94)Qr;pa8@#s(`(Ti^2GSd>4%`ToU&G+-Li-^LyOh=h;RJUE}HL#zZGe5A@Homc}A2$}_xHhRk&XgsUh$qvU`K=Hbs)a}nGZnH@rkc0r z^W5cBaiSt;I6C(hCP?0;js0kDF}*VDxqdc<^IKA3Ye=3-8<$_TCSK0K{SNZRh=4Vlp-xcmS{7wOG0)L zvae&`W#6*zG!G8+7z|_IxfL$5uVXDs7-MJb{615+n%k}Wef|C$<};sXIp;ag zdCqgr`)xwBu*}d{aLF}*V;mlcH8=yhVzF1)IirkRPUfYrSN9f5UHBXZ!370Uj3DCv zOso|WG`~(M7JGO4f&C~)zWr#QWX{b{o%-C78QIVx)c|jDmF8C}!PVyvL@zNzm`koJ zUv?i|>2CkCgAmpz1LhumyW_R5f1)$N<=xARMOP{BO=aeqY^B&ZOicJ5WLd$Pr#O@s-Hqc2D{Ib6|7&Jd7;p*ly* zgT(zjr77IFJu2S^#*npTawztP_7`e{4-Dw3B0;=#h?gfu!oj?Z#j6ocm|<XpDKI3enq-0;iM7YHA z%&kqYG5YSIa~fJ}rfb|bbpyTrfxS{uIZ$h#C9R1u6{xR6ZSMWy&E*k(ExB_=1?+ol zsQX+Rj?YbeC1E}(t+eFL%=-o1%HH)$Uf`ikK}}=PHnZl`MzdB^;Mg@82CZzfb+u1G z+pBB!MEaKHrTqnFyKbE@3DFA?D31;D?JS%wz$lHIyVl%T^#1FfUG9Jfw6=q$^-gAF z=dzhVDsWXECvmN6A))VlF@pPwKpBny>Kr=h3t?>Wd#R#AhTg4&gvp=xMDdRJiJK zmzUB!XNj8{x87uE#vi?7rp|s*+%4=i?uWxN={^3PS9yXaR@X_e8^uvb1RGl`zGl0?L^l~ksm?K>J&-q08dv9Fe~D`+GinP_^ntS{$RBqH8i_B_Rv zyq27IT$6m>kYrd(JSVapDS(|HU%lG38w&N2xr7?i=zZG;^+Q2B1`{^~+H;HhWq0#( z580S)TmdJaj0kgJ9K=>kexCUbR26XbOSXbS9G;{ptX91p=L?{e(<|&;z78d&a1+MV zKH?tGB70DzH96r$TzzVp6{A%tTR9t@yDV$V>h6Q}G&XJ=Kfmn8MsX+#98zM92Ny{L zeCaOhpf{^x=XIbW#Ct$tNbZ}h^f-5)Lok{fwYv}sWT&-_6WO?*+fb+-9@H$-y3uux zcu$ANa4)aCKveE!X=go<=w}&YgmfHo1fIPXpf61uMz?UiF&8Qx?91ybiwt-xBDg4Q zv%DHhEVo;<(y0da3=Xk75l~xi&OEL`t_tT$GASq)?QjyUKRDEK;63iw%)AS2Qgc3H zyRxVnUz4Wllz<`f`jM#m!<7O)-F?erRe6S$dTmnmrel14YDC7AG~vaeCZQ_ofU zgtU$tFvlB191{>#l91gJmg*h5GnCPh5o~V7!s;yZ>(FyXDj}*%_t@`G&fGa=-Xe5_ zdF3;v^>jSXCxmRIO}PAlCRm%z-G|rom1It40uXRD;NvcR9^)jNDdOHrEm65gxi?<4 zOncPs*!8Lm)v3~dsNLG6lC%5*i+Xe>nlg$lIsq*IR0BKIPo;z$tD1VTWQ;X zG!D-19&{~od*)D=_KXw*h*)vz4dI3dYiWkBEyk8E?*J)$ZT0Jz<{zMO#|hCoKybaP zPU!5pZyPyYpfshKWZ(5YFQR`j{^671hbYBF|G@=$kJgy|NRn>zs8+C!4lB2*dY<$R z$w#CwRo}feJb(@2sMd2M5hZDI# zq8#^0%xh^slq5yiZWRB3QeW9j%_7z#+vHMS4Tlz9)m@4=P^5r1@DKft+K)G}T@fcS z7o8-qRCDJlW}c}BMqA2(B6&Pnc2CeZ*E)j!Mt7_3}^v-7O?I zZ#k{&l`g8VfCVC5n#%= zN9cIh!X|MsYe^m~aF1y~V?)I!qe6f6<&AtFRoXJe5v>Qc{Gu8U_N;mHpPM08DNM|l zYbyb>RON_CQYm4DgE3{>Wxz4smE4Bq6f-3=V7`uuMiAY0P}QS=t*YU{x-ve+=VNz~ zfHM@T#DbA(xeKIPe=!1L9FW|)I}N0B)j2kHDEW3?@Y`T|$RL+mFC&Lr1bC}`V=PK* z8oq5&^Vg<({P~H7N@i}gW}{*u$)MzFldZ#^Vo?;EvR!8d%0X!MoM#1l=~Z5GjtkYr zW_8olfk?lymy;3tBh!~g-@p$ORJN(CfV!Q{8;=W4t(|bVjTM}nff}+hve1J+Xbg2O zVZBQZ=u3kpb)hp9ex3>x(mPRke6OAybX3H=^?Q*kS*cCL{CSzWlSF{Rn(4IeUQ9sn45XCBT(a+j=A6+GK4IV36IuYH+XY9`um zKsT!DlL;Ev64wxpbYgc-l*loUey~*tQLY1%myRlM7Js19q8(Fu=T*Oy~QU z{XsLdw{k&p;!4O1oA{6!-^M5?Hw7o_7o5mW$_lsl!-xX1B%R1(6oR1p%*R`;go~1O zZ&bf7sc>O)&DSYX2eR9uPh~hD{)#r}&O+Z3=4vf9{CKC^mBYGwYMHX*vFRaJN-|XL zmNDeaJ8AS{(MWj6s(kH>bC1&*C(1KIK{%gLuEDQ!M02$i5eFi9R;p$Dw3lF!Tjx)U z+6y!#ulg$3uOl=X$Da}Pp^dI&>z?#*aAg%G`cjm{BncQ2)xII3?{?%G>xwV?bKual zCl&xQ9r~aW#>}FPP_eL*QE^MCrI=xq^6eCmWj;y=h`!Rjh;}(PW}T~py#VA~Xc5Pe z&5;~4_Qj%XRB4~e)yB87u3A!}Gg_YoZF9^I`d7~-uBI4-sqIUsSaU7hq^MWdQq|*X zw0B9)FZA_?S3G#F!FGLxL6WO{LQ{S3COOvAi0|=H&KEqQcJ|wTB)%NysVBX(2_ngo zi_R$1aZ~(JbMhM&fS9D5NOtvFQWa&79&h(48*(Drp__AzpLPipIRbl5(5I0lU+kBtV1w(e9k+Ugnr0q$&Kww@qelfHZ?UE6~~ zl<|4+(DGVj6UASNF8Vv`I;m^=J*J7oE93B9l6Qq);)gvaiECHG$4}r@>UkA4IC(0L z(-*i$PNoPgLQ(r>JcoKobZpGI2}L1p9h)zbE)LuKZ|tQcJc~pYwD*{{82TYmPd*6d zXMm8IrJb6|ErTg%$~52F>hcefLLHb9tbe{Ax8Y-P<1n6>=E$`KN~d(>98H`gW{VDT zmE=-bO119v`w;{1ClrrFfm$a+$f|eVlGi4`2KP3b-@g78I~W7VH*8Mc1KsM4)?r%G z!>G7jlD7LOr4$!cWtyR#uBUEpqQ0L+|0!E~Jg49<18%SWv&!kWYGG4>5k;y*?*rjy zHmIGRBQ`JSzuww>G=8gdgj9&SPphs{?DAGC3290d>%b5PS)RQ!%U36q03SgJ?ots4YL zxqAfcw)D3jujIAX^=}k`wyl@sHhnID_bRIfk9`nQHunF3kn~h1Li$I^GwU^&D|?G^ z<*w+DT3heAOV&LSt3Jdw%g8CVZV}C2g@+u`?>e&Ya-76R zjl?E>06)8*16x;_H%ydzRCV!VEtoInDdfwhO3q>=dJG>63zj7&>UwC`SV?j3FQd)X zQsRw>T#`NN9o4$#k6fW)@)% zkY_wKvJ6t%;V(dbKuq*S}N8`>GsKnIEvoKd zsCmdn#v84j=ooLHqypq*a6d4+l(8Q_6FvQCYOU=id`PkTGeDC8x-i;D9bMrXZsOiJ z^<~HJswJ4((rGR&^HY_Ph-akt%_f9}E|190d^luEP3QF5~kpvCHmZefJz!isVY zOw_OFny7neXEYaKgU-8BgT&f33Hto_hPNKea-Vs1HH%?p?oK<#ET{z^*zN0e3GB&} zBk5gY7n#f70=CBpg!MkECLV1GKWi@qRBUvi|8nuLQpkayoqzoNXDVHoGXL$aP9=c7 z7351cfAcBm?;IW30EeUx-Sqt~cB+Q`N6~4^!xG3J(#V zp#cx?-HlD4u(ohrC&%)ba4Ts$P4bZ+sW1fl`f|kN&FPhGfq`Uh2WvhDJ1p#wSnvzF zEUd1<(|f~pq0AODX%JsY2_l#5Hs{b7ntFOe)L03q*64K;UG zTZw(-uy&fY7d7{em0d~7-Q0#ZBNKx;ugUxK24j9sgPx-Vs(h;g5}$n!*C?>Bq;%Np z27vq-+OF#`-{P`=X}&8%DR;I~%Q#5?W;kt0O??_=kcw!x zBWC}=gwH{mnR1&}tAONqeEz%zv?J$XRnsFwTHYx&gh`8^?+H=>k>30X3j;Gt<({q% zQu@K6_^OK2v*_~G0lR+t4-H+~d@7M3*h>y$RX z1Xt(-h%A|yQI((Lb3wS`?;yjbK2sOQM44%b9cHl$YzeQYqD}# z7w(o#={}VO&`9rNsp^{}qSyvAp9mXta8}yy>W(b4itmkOd&PtDduC?DUSLJaV<+fO z+ot16m6;Si_FQbMrr3m4YYgtp33`LycQ<)0PMs=UMuhfS^ewzGmI1hSS&&WPxh0%& zpLD!Atu9u(^Rz^m`#N>Hd^i@>jZu0%EOfX^0t5@4!nIRf0-|_A4Ry2TU z>XWHTE77)DFXkl^Mp&%(6bfoV)_T+ZQPtL_r4OPXA*XM~gIIJC-A{oBL(y!hXe=O@ zT7x{lvU3}*mFSMs0KJbt!8@J|KZvpLMOd2#N}b^lV_DXYtwd46mGd0rFzXXXdpRBS zH+M|G@I$N+Qd%Dwr5*ZjQ@q(37Y_VPTm`V-tP8%L@P&4^{Qw^KLHew}MKX*i`RN z7Q0G1|DmBUNo_0#vrHUzKBLpDImJeL&DRNf&+K-<+q~rs3XSQqr!q%Ur9k3)OmQxZr_F z6ej4j`kbxRqQQHj57trui?H_XpyU#X`)*EuEX>pDs({gvweA5D=l>2Rh^aQ%a~NdZ zW7f`@@uiSvv1N?&Y0L`PHcsijO5i%9ZkLlNy6CzB894gfUut#W6_A`zQjR{SHZ+B8 zWtZsx(}5uIgL)!ebJko+AAp`iGoDN?LGVsU!L`!9#^KUXGu%Kvr$D{5Hv6jj&?~SX zbtbNmwR@o)%8%P}Hy$2uBlWBCvY=mh?OiE5!d|SG{5r0k86BS+D`IvT-R;}SavV*4 zne})p{hu*b$)7&YZSL{;y>T|={nha9M&a_i@Ik3kmIx7DFGDp;7^Mc3+9os-;$d>S zC6CVfH|1!myQ>YK0}YJ4Qu2$1LA%mjFpgd?yh36IcON#E8u%h}X)RyWGwmn$0#qLr zZ?k4$E?iS!=v?2@%Ok`~Z2QoLnm`WMcu+oUQwa#cV>0FnR@zR&EBXpH1~j(@igSyL zNWfmc@&`#N_qa0s_o{>y9Wy4y8&S|fa=;y!Qz5VcZ`s}~kKS9SXRSD4k6iX{i{?U% zDZEPRpH|26+gfEUGaZ*L7BP!RzPs0Z10-5WYk^j)@Z2?>D zc_^r9*1s;A(S`f7nCVvb>*kyY7MGJEwPU>Py|1Ih?v~ht0LQfylzy5n2?^Sby42Rv zsNE99!k!HGW9M3UdF4Qt>?0R&!ySFi6*{SaTeV)##iA~ye|RjmV7_})@ANpdAEQJv z>cjVLkuQ_x%sc*b?Tp`+-S-srj?B%Q-?v9@y57PUiN;$PULy}5rOyWZ`ve!Zz@UYc>boaE&nUw;sY9_58yBsVW zM;Vf{oilh;r&Ery8ed1-mDW#s1MC#10NC@QDa@t0Yj z`Pyk@DQi=~O6oL~eJ%`XkRJi4 zsr=x3Ws{=~eiO=LEC#@aHu@RZ&;<18wBE`T)xe{y0OCHgcW$YcFIxEtg)dA<%aGE(hd0xYKJ;(&oD-Ohc_Hr%)eIYPf$ z#xOZx zcSf%j-Tn@EmBM_Iqg#6?NQIZA{Ty^Yi2JZ6da>KFrAV1I2E@uzXj?pjp`Wt=^&i|; zHnfathnWUlpJ8xJ%sy~e8_JVtDN565Vy(+qxnv!_sD(HWiKPi__cL#?m#DdJ2Xn2i zI|K%-MZv;rsxBO9!E-v^s+}yIE$A_SfMKW#pox-)rv`u^7d7Fjc?PzxpeuMQ=!@;` zs|U8CP5%(8?^S|bYy|%OLHmk7Q<2*Zu+11}sccWvOYfx7JysZC0`eJ&@f0XWZ;HE2zeePj zsjc=1Z@uPD!lpvKlu&$Nq94tD`DBe_c2cP1r~1CvKOy8GWg3zf$Ywg_Jt6{>C)ZTT z<^__aBb1wIqb?*5iXh)|V(-<;lFJDo>&%G+Ms!?f3DG%lPRKZoq9tR%tXiN|F(jbX z7(U8Ul1jTU(2ta;*X)>Y;&S{Q>ISe@1qj9c8v?%v9)WG!npiKtW0vULW80J^o&MUZ zFwSgi!NvU`F`~hfXyTkA>5MU2%Wa+No`R*wuX<9i1`O;8mWaCPlx zX1~+4iiMFE#y&dK`53D?#pOkGD)b-_y>zbcvW}}lN-F3rh8Ex|LQ^h!XtZ`*&hd+g zv{QF4c%mOeq87Na73q~L!fh7cPKG@nAdEo1xg#IKj%poe&1Nc+@s79N5pFynmix?_ zm6zX?y7ed?ZTIT`*E5RK!it^E9uFyi`&HjQ)EluE0HJ1B9&4#y0o~=3Ze`LR!9_#z zqUTQu=oz?9QSjcpkSRiF>vk(X(F*<+5oTzwDT&zHq8Rqetyi0^60UO$oV+HPiz7lQ ztbQAgwg>1X3X8;EC;HmzvKM4*r%f^jl8gn%$_F8)f=FaQfb3p07kGJdZ!r6QZFxUb-Q6fe8Q+id)yN5s=Xdg0{b3 zS7=O!Qq-Ii&EH%nC-UCh(I{7WhTNe!SyqpzavCET)5vQjdsklujd>O_g^#N)mqM^6hjb|7r5j^ zjuaXB%eEf23vUk>vL55vvqNR@dfv6Oefal#>` zZU~-R`V91nK`tZefa2CI);7H|1|WJ}#nIJyUY!r@s9>b4(~lT7QjtXx<{w2DnUZ3W z54eI&p#0?FR6Kf%Y_iO}+$eYQfSOqYwdw+v!z?X@i!9M|?#dR=%U+QsMcCgMd4StYC2XaUP8z%V^AX92Al3gS4j?$Umt3sYG&)*^w~1)56;^&^@y^q-{E+%6@2Q}I)%N9n!-S$m@qS%Z zId*9KAARzm#RIJz=Mrjw7=t{b!aPiI^gfrIN{|V+K!`?(yPI3NK|X?PhRXF$Eg4-m z5njVTy71*w)CC}7MD_)k@9%Gvp-+IzGx>X|sv*sDb_FLkNr343D;AZ{@Jn)`Yi;Im zt>%KfhTYfbsT?uU6JU!lev&8)i72zaeD$WfsL@i@Sqgz<*^RNRh*~XV(A)4sD0`>n z3wDZIOc-Ac*&SuU#IzxCF81y}iFC@EnH80XY&9|?1xtEoDQ2UKxc9!#&`%u&P}$f4 zX9NzC`;LYv)_LL0Ok!5M_%8jnO}{$elDj~OY*#h`QQMEJ7 zGIcB2gTvAc8I+vA@_CY414_#=Q3Q`?hmD1uxu#tNB3I6vjH zil&+FLUQQ9pZ<*v>2yXu?vm^=t)gaF)OKCb10W_Aci)IK@p*fRX^V^l6Ev|qs~)Q@ z-7U8Yq)gjG*-wWDo?#*0BO-{lT!W|eG@9Gqi5Q3S27ulTfBBxsNzDBiGXV{7)VABqn z_IB4t!#K!rzW->5qSlx38{+|BwZOMI8D6v%nY(d*M`}6a+zxtV& z8m?+cJtiXJ_jdYU!n|~i3%Ygu_bcyPcfK`vH&Lu0>u2^AYxWECPrR8m5Zw@m0mt#2 zZsZpX#ou-ME)16i;`ND&7q4AchTE#9v0Cp|_3};Wl;2G`es|{o)o0*jCw81ZbMVRK zkn8v$gBAqw{T@QBecK*aewDWK?L9Qgz|McF#_}wl0}K(k^hRxJbt7l>zlmG!rW_0F zv1tfy`U7tt0B*c=d6KHhSqF^t0P+=W(*Hre@;9IJUn}_UH~}0o-XUCXp9}omw0*HT z!10@@mV=n`n-2ca#@~HP(FRU;*3qmjp1(I*KQ}2B14u}pobCVdi(*_sHk)Sn`fm-! zzrKKQ;BI#CLka(SbckEghE-m5mNfNxy{;yxK;Q+PU zqNauZAL=icqB%(RcO!kWMm-7Ir2^#maNghS!q4xViv?QS{IJlWjWaT1?1lH;&p(;M zGdRD~sJrDjBeAs5hWZgb`d=fviA&{s9g`UG9T5NL?))frX8)N(E$3@~V1`LA$TEZjt`2wCW?#7EH2LwkeLaoa# zP5b;ucTzs#dh*UtT=5rg{<+)V9`OMb#^)jsCi(V{|7hULBmZm#CIPuOUU*Kr@sBUR zV_{v%tCBnLOv*4U!O{9n2WOTrLnSO;hn-^ zd=gKTjWlp${2z9Q0=MqO|8T)$PZLujdwC;B)}KVtks!oOJNe>CWd<4mG6 zAP;>0qZP3zLK+V3d1oTSp=w#m|L{0~L?Ij)dW4~oA|CGpB(K5Vba~ui@9L51BF0O* zz%jwO33k%v9Gl=7o9vrQ;~q1|s}cYPDfetN$@yV!k+Pf#kse6}*R(9U+39lX-!b(PdBQ?EyoAdsUr_^jBREY!(<)cM2FE;~S1_4m#nAie3!MoqANsgm#d1^A&>gaYP9 z(6InF@m4(n*kEgI_M*$s*n;cUnWc@XYCb*R(wU`R7`7B?DFv4kFt0!_K^%R4KduXw zIH}NJd${oVo@6g+Q8i~ba~KH8sZW>9_m~PMUU; z4p|m$$af72PCKZXVslwsx?2zm#(x!_V7}TXOMrocCGHg+-oPz=AUT)M`bsFht8Ngz z1d?6^Ugc3-Ky3r(mybm|`7Iu)L#mk`8Re=tgCAWI)? z_Mc6X1M-tqF};fSP~81%#UIaR^7+<$$a!GDFaX<*#UB>|M6iPnn-zSg?E{Tjc9t|IpQiMEIffUT zWcnOYr_v7#n_d>Bv;eaiWX{q4t)H>V9nsH3gX%xe!~p}TL+F?<&#W@ zz8z{W)3}~#TwQ5EyqH)GN?0VIbr(j5y7JD|zP)QELq|STlfmMosVHnQmj|L?!!u3) zXyuEJ&H&yVIO!@rQhL`40m;ZDcVh7DXa3hplC`@+B@09I-YzA*&dW}vhJN>#E$4>3 z%fj>~UPO_X+9Ar~e5_SQ-ny9ww+6iD#nS^kX?@XDCR{~BTFVfgg9`af_6A#>XwKTs zyp^XSFvA4Zu(opKTNH2`=IpCmQ1QGT@}a@+McD&(cgfefH%rEHtI)svfc*S460aa2`^57OTyLEt`ovxlsTzHz-thMQgZ5gb> z?mAE&@$4T|JU@1~ub;@-flaFW5e9EM#n#Wr*ILevaD@74?r{en`pho7dDmf^XI}pN zV>~wuU}^@O$vukC`*>5uq@H4T=wLc4!dBvmTAZw?6}A_w#Q4qqr;~CTIQmeCrQ%YG z{x%AbB&NsBJMYGW^n48RJA^~W`qet=clGi^n;pMB^5fy}pHeJv-hDBG&jN2}5L1Ly zu8tO4-?51VXhqr{DYo)c{W7`X`_RlzZ?Kpey5SXy0HKac6-StYy6Od$-j0y8xeAu# zVVa(ny#*D)C1Fw!i3iSqni)`vLP{3Po#}dIwR?lj(KV-;H_HEwKadl zGxxBXhPOLQd430@7df0*)$6uG>A4qU%OZ07_{M%LICZ54d-8u?<3Y?RKDs9{))WcJ z7M$T^$;S6x_z8NC3a7li62|#wHeTBpZu&0j&o1rCBY189(|WYxtcTuxEIu*FnUlj) zWyP*K%bK71?ktjwD8j|-UGTV2ez;8EKCuBOls?rfdEciNP^Twn&T7+HGsbzCvxkBOB}nVH&|eeWog{gfs)AofEL1ttvf z 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 literal 0 HcmV?d00001 From bcf8de79f8f8f692855f605223f5bf27a27a71a6 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 6 May 2022 13:29:47 -0400 Subject: [PATCH 127/158] update docs to reflect changes in PR #238 --- docs/UsersGuide/source/BuildRunSRW.rst | 145 ++++++++++-------- docs/UsersGuide/source/InputOutputFiles.rst | 2 +- .../source/_static/SUBCONUS_Ind_3km.png | Bin 0 -> 81808 bytes hpc-stack-mod | 2 +- 4 files changed, 85 insertions(+), 64 deletions(-) create mode 100644 docs/UsersGuide/source/_static/SUBCONUS_Ind_3km.png diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 8d2f324ada..a5725843cd 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -20,8 +20,7 @@ The overall procedure for generating an experiment is shown in :numref:`Figure % * :ref:`Install prerequisites ` * :ref:`Clone the SRW App from GitHub ` * :ref:`Check out the external repositories ` - * :ref:`Set up the build environment ` - * :ref:`Build the executables ` + * :ref:`Set up the build environment and build the executables ` * :ref:`Download and stage data ` * :ref:`Optional: Configure a new grid ` * :ref:`Generate a regional workflow experiment ` @@ -124,81 +123,36 @@ Run the executable that pulls in SRW App components from external repositories: ./manage_externals/checkout_externals -Build with ``devbuild.sh`` -========================== - -On Level-1 systems, for which a modulefile is provided under ``modulefiles`` directory, we can build SRW App binaries with: - -.. code-block:: console - - ./devbuild.sh --platform=hera - -If compiler auto-detection fails for some reason, specify it using - -.. code-block:: console - - ./devbuild.sh --platform=hera --compiler=intel - -If this method doesn't work, we will have to manually setup the environment, and build SRW app binaries with CMake. +.. _BuildExecutables: -.. _SetUpBuild: +Set Up the Environment and Build the Executables +=================================================== -Set up the Build/Run Environment -================================ +.. _DevBuild: -We need to setup our environment to run a workflow or to build the SRW app with CMake. Note that ``devbuild.sh`` does not prepare environment for workflow runs so this step is necessary even though binaries are built properly using ``devbuild.sh``. +``devbuild.sh`` Approach +----------------------------- -The build environment must be set up for the user's specific platform. First, we need to make sure ``Lmod`` is the app used for loading modulefiles. That is often the case on most systems, however, on some systems such as Gaea/Odin, the default modulefile loader is from Cray and we need to swap it for ``Lmod``. For example on Gaea, assuming a ``bash`` login shell, run: +On Level 1 systems for which a modulefile is provided under the ``modulefiles`` directory, we can build the SRW App binaries with: .. code-block:: console - source etc/lmod-setup.sh gaea + ./devbuild.sh --platform= -or if your login shell is ``csh`` or ``tcsh``, source ``etc/lmod-setup.csh`` instead. If you execute the above command on systems that don't need it, it will simply do a ``module purge``. From here on, we can assume, ``Lmod`` is ready to load modulefiles needed by the SRW app. +where ```` is replaced with the name of the platform the user is working on. Valid values are: ``cheyenne`` | ``gaea`` | ``hera`` | ``jet`` | ``macos`` | ``odin`` | ``orion`` | ``singularity`` | ``wcoss_dell_p3`` -The modulefiles needed for building and running SRW App are located in ``modulefiles`` directory. To load the necessary modulefile for a specific ```` using ```` , run: +If compiler auto-detection fails for some reason, specify it using the ``--compiler`` argument. FOr example: .. code-block:: console - module use - module load build__ - -where ```` is the full path to the ``modulefiles`` directory. This will work on Level 1 systems, where a modulefile is available in the ``modulefiles`` directory. - -On Level 2-4 systems, users will need to modify certain environment variables, such as the path to NCEP libraries, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__`` modulefiles can be copied and used as a template. To check whether Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, users can modify or set the required environment variables with the ``export`` or ``setenv`` commands despending on whether they are using a bash or csh/tcsh shell, respectively: - -.. code-block:: - - export = - setenv - - -.. _BuildExecutables: - -Build the Executables -======================= - -Create a directory to hold the build's executables: - -.. code-block:: console - - mkdir build - cd build - -From the build directory, run the following commands to build the pre-processing utilities, forecast model, and post-processor: - -.. code-block:: console - - cmake .. -DCMAKE_INSTALL_PREFIX=.. - make -j 4 >& build.out & + ./devbuild.sh --platform=hera --compiler=intel -``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, and ``share`` directories will be created. These directories will contain various components of the SRW App. Its recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. +where valid values are ``intel`` or ``gnu``. -The build will take a few minutes to complete. When it starts, a random number is printed to the console, and when it is done, a ``[1]+ Done`` message is printed to the console. ``[1]+ Exit`` indicates an error. Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, users should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. +The last line of the console output should be ``[100%] Built target ufs-weather-model``, indicating that the UFS Weather Model executable has been built successfully. -.. hint:: +The executables listed in :numref:`Table %s ` should appear in the ``ufs-srweather-app/bin`` directory. If this build method doesn't work, or it users are not on a supported machine, they will have to manually setup the environment and build the SRW App binaries with CMake as described in :numref:`Section %s `. - If you see the build.out file, but there is no ``ufs-srweather-app/bin`` directory, wait a few more minutes for the build to complete. .. _ExecDescription: @@ -257,6 +211,73 @@ The build will take a few minutes to complete. When it starts, a random number i | | grid point. | +------------------------+---------------------------------------------------------------------------------+ +.. _CMakeApproach: + +CMake Approach +----------------- + +Set Up the Workflow Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. attention:: + If users successfully built the executables in :numref:`Step %s `, they should skip to step :numref:`Step %s `. + +If the ``devbuild.sh`` approach failed, users need to set up their environment to run a workflow on their specific platform. First, users should make sure ``Lmod`` is the app used for loading modulefiles. This is the case on most Level 1 systems; however, on systems such as Gaea/Odin, the default modulefile loader is from Cray and must be switched to Lmod. For example, on Gaea, assuming a ``bash`` login shell, run: + +.. code-block:: console + + source etc/lmod-setup.sh gaea + +or if the login shell is ``csh`` or ``tcsh``, run ``source etc/lmod-setup.csh`` instead. If users execute the above command on systems that don't need it, it will simply do a ``module purge``, and the user can continue without problems. From here on, ``Lmod`` is ready to load the modulefiles needed by the SRW App. These modulefiles are located in ``modulefiles`` directory. To load the necessary modulefile for a specific ```` using ````, run: + +.. code-block:: console + + module use + module load build__ + +where ```` is the full path to the ``modulefiles`` directory. This will work on Level 1 systems, where a modulefile is available in the ``modulefiles`` directory. + +On Level 2-4 systems, users will need to modify certain environment variables, such as the path to HPC-Stack, so that the SRW App can find and load the appropriate modules. For systems with Lmod installed, one of the current ``build__`` modulefiles can be copied and used as a template. To check whether Lmod is installed, run ``echo $LMOD_PKG``, and see if it outputs a path to the Lmod package. On systems without Lmod, users can modify or set the required environment variables with the ``export`` or ``setenv`` commands despending on whether they are using a bash or csh/tcsh shell, respectively: + +.. code-block:: + + export = + setenv + +.. + COMMENT: Might be good to list an example here... + +.. _BuildCMake: + +Build the Executables Using CMake +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. attention:: + If users successfully built the executables in :numref:`Step %s `, they should skip to step :numref:`Step %s `. + +In the ``ufs-srweather-app`` directory, create a subdirectory to hold the build's executables: + +.. code-block:: console + + mkdir build + cd build + +From the build directory, run the following commands to build the pre-processing utilities, forecast model, and post-processor: + +.. code-block:: console + + cmake .. -DCMAKE_INSTALL_PREFIX=.. + make -j 4 >& build.out & + +``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, and ``share`` directories will be created. These directories will contain various components of the SRW App. Its recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. + +The build will take a few minutes to complete. When it starts, a random number is printed to the console, and when it is done, a ``[1]+ Done`` message is printed to the console. ``[1]+ Exit`` indicates an error. Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, users should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. + +.. hint:: + + If you see the build.out file, but there is no ``ufs-srweather-app/bin`` directory, wait a few more minutes for the build to complete. + + .. _Data: Download and Stage the Data @@ -540,7 +561,7 @@ Sample settings are indicated below for Level 1 platforms. Detailed guidance app .. important:: - If you set up the build environment with the GNU compiler in :numref:`Section %s `, you will have to check that the line ``COMPILER="gnu"`` appears in the ``config.sh`` file. + If your modulefile uses a GNU compiler to set up the build environment in :numref:`Section %s `, you will have to check that the line ``COMPILER="gnu"`` appears in the ``config.sh`` file. .. hint:: diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 0a8077943c..1bb7451257 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -19,7 +19,7 @@ Initial and Boundary Condition Files The external model files needed for initializing an experiment can be obtained in a number of ways, including: - * pulled directly from `NOMADS `_ (limited data availability), + * pulled directly from `NOMADS `_ (limited timespan for data availability), * pulled from the NOAA High Performance Storage System (HPSS) during the workflow execution (requires user access), or * obtained and staged by the user from a different source. diff --git a/docs/UsersGuide/source/_static/SUBCONUS_Ind_3km.png b/docs/UsersGuide/source/_static/SUBCONUS_Ind_3km.png new file mode 100644 index 0000000000000000000000000000000000000000..8bbcbc7aa3aadd290991cc56b46be672d5811372 GIT binary patch literal 81808 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

b4Mo)M@(h-ccf-y5B@+1#kLOFQ$VP1|W{)`=Z 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 q Date: Mon, 9 May 2022 18:41:34 -0400 Subject: [PATCH 128/158] Graphics Ch-1st pass --- docs/UsersGuide/source/BuildRunSRW.rst | 3 +- docs/UsersGuide/source/Glossary.rst | 6 + docs/UsersGuide/source/Graphics.rst | 125 +++++++++++--------- docs/UsersGuide/source/InputOutputFiles.rst | 4 + 4 files changed, 81 insertions(+), 57 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index a5725843cd..5b29f478aa 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -228,7 +228,7 @@ If the ``devbuild.sh`` approach failed, users need to set up their environment t source etc/lmod-setup.sh gaea -or if the login shell is ``csh`` or ``tcsh``, run ``source etc/lmod-setup.csh`` instead. If users execute the above command on systems that don't need it, it will simply do a ``module purge``, and the user can continue without problems. From here on, ``Lmod`` is ready to load the modulefiles needed by the SRW App. These modulefiles are located in ``modulefiles`` directory. To load the necessary modulefile for a specific ```` using ````, run: +or if the login shell is ``csh`` or ``tcsh``, run ``source etc/lmod-setup.csh`` instead. If users execute the above command on systems that don't need it, it will not cause any problems (it will simply do a ``module purge``). From here on, ``Lmod`` is ready to load the modulefiles needed by the SRW App. These modulefiles are located in ``modulefiles`` directory. To load the necessary modulefile for a specific ```` using ````, run: .. code-block:: console @@ -714,6 +714,7 @@ The workflow requires Python 3 with the packages 'PyYAML', 'Jinja2', and 'f90nml .. code-block:: console module load wflow_ + conda activate regional_workflow This command will activate the ``regional_workflow`` conda environment. The user should see ``(regional_workflow)`` in front of the Terminal prompt at this point. If this is not the case, activate the regional workflow from the ``ush`` directory by running: diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 4274df7981..b098eb9e64 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -12,6 +12,9 @@ Glossary advection According to the American Meteorological Society (AMS) `definition `__, advection is "The process of transport of an atmospheric property solely by the mass motion (velocity field) of the atmosphere." In common parlance, advection is movement of atmospheric substances that are carried around by the wind. + CAPE + Convective Available Potential Energy. + CCPA Climatology-Calibrated Precipitation Analysis (CCPA) data. This data is required for use of the METplus verification suite within the SRW App. The most recent 8 days worth of data are publicly available and can be accessed `here `__. @@ -22,6 +25,9 @@ Glossary The preprocessing software used to create initial and boundary condition files to “coldstart” the forecast model. + CIN + Convective Inhibition. + CRTM `Community Radiative Transfer Model `__. CRTM is a fast and accurate radiative transfer model developed at the `Joint Center for Satellite Data Assimilation `__ (JCSDA) in the United States. It is a sensor-based radiative transfer model and supports more than 100 sensors, including sensors on most meteorological satellites and some from other remote sensing satellites. diff --git a/docs/UsersGuide/source/Graphics.rst b/docs/UsersGuide/source/Graphics.rst index 73929fe7eb..d152e2120a 100644 --- a/docs/UsersGuide/source/Graphics.rst +++ b/docs/UsersGuide/source/Graphics.rst @@ -13,24 +13,26 @@ output over the :term:`CONUS` for a number of variables, including: * 250 hPa winds * Accumulated precipitation * Composite reflectivity -* Surface-based CAPE/CIN +* Surface-based :term:`CAPE`/:term:`CIN` * Max/Min 2-5 km updraft helicity * Sea level pressure (SLP) The Python scripts are located under ``ufs-srweather-app/regional_workflow/ush/Python``. The script ``plot_allvars.py`` plots the output from a single cycle within an experiment, while the script ``plot_allvars_diff.py`` plots the difference between the same cycle from two different -experiments (e.g. the experiments may differ in some aspect such as the physics suite used). If +experiments (e.g., the experiments may differ in some aspect such as the physics suite used). If plotting the difference, the two experiments must be on the same domain and available for the same cycle starting date/time and forecast hours. The Python scripts require a cycle starting date/time in YYYYMMDDHH format, a starting forecast -hour, an ending forecast hour, a forecast hour increment, the paths to one or two experiment directories, +hour, an ending forecast hour, a forecast hour increment, paths to one or two experiment directories, and a path to the directory where the Cartopy Natural Earth shape files are located. The full set of Cartopy shape files can be downloaded at https://www.naturalearthdata.com/downloads/. For convenience, the small subset of files required for these Python scripts can be obtained from the `EMC ftp data repository `_ or from `AWS cloud storage `_. +.. + COMMENT: Update these links!!! In addition, the Cartopy shape files are available on a number of Level 1 platforms in the following locations: @@ -64,9 +66,18 @@ On Gaea: /lustre/f2/pdata/esrl/gsd/ufs/NaturalEarth +On NOAA Cloud: + +.. code-block:: console + + /contrib/........... + +.. + COMMENT: Update path for NOAA Cloud. + The medium scale (1:50m) cultural and physical shapefiles are used to create coastlines and other geopolitical borders on the map. Cartopy provides the ‘background_img()’ method to add background -images in a convenient way. The default scale (resolution) of background attributes in the Python +images in a convenient way. The default scale (resolution) of background attributes in the Python scripts is 1:50m Natural Earth I with Shaded Relief and Water, which should be sufficient for most regional applications. @@ -104,13 +115,21 @@ On Gaea: module use /lustre/f2/pdata/esrl/gsd/contrib/modulefiles module load miniconda3/4.8.3-regional-workflow +On NOAA Cloud: + + module use ............... + module load .................. + +.. + COMMENT: Update for NOAA Cloud. + .. note:: If using one of the batch submission scripts described below, the user does not need to manually load an environment because the scripts perform this task. -Plotting output from one experiment -=================================== +Plotting Output from One Experiment +====================================== Before generating plots, it is convenient to change location to the directory containing the plotting scripts: @@ -123,25 +142,25 @@ To generate plots for a single cycle, the ``plot_allvars.py`` script must be cal following six command line arguments: #. Cycle date/time (``CDATE``) in YYYYMMDDHH format -#. Starting forecast hour +#. Starting forecast hour (same as ``CYCL_HRS`` value) #. Ending forecast hour -#. Forecast hour increment -#. The top level of the experiment directory ``EXPTDIR`` containing the post-processed data. The script will look for the data files in the directory ``EXPTDIR/CDATE/postprd``. -#. The base directory ``CARTOPY_DIR`` of the cartopy shapefiles. The script will look for the shape files (``*.shp``) in the directory ``CARTOPY_DIR/shapefiles/natural_earth/cultural``. +#. Forecast hour increment (same as ``LBC_SPEC_INTVL_HRS`` value) +#. The top level of the experiment directory ``EXPTDIR`` containing the post-processed data. The script will look for the data files in the directory ``EXPTDIR/CDATE/postprd``. +#. The base directory ``CARTOPY_DIR`` of the cartopy shapefiles. The script will look for the shape files (``*.shp``) in the directory ``CARTOPY_DIR/shapefiles/natural_earth/cultural``. An example of plotting output from a cycle generated using the sample experiment/workflow -configuration in the ``config.community.sh`` script (which uses the GFSv15p2 suite definition file) +configuration in the ``config.community.sh`` script (which uses the GFSv16 suite definition file) is as follows: .. code-block:: console - python plot_allvars.py 2019061500 6 48 6 /path-to/expt_dirs/test_CONUS_25km_GFSv15p2 /path-to/NaturalEarth + python plot_allvars.py 2019061500 6 48 6 /path-to/expt_dirs/test_CONUS_25km_GFSv16 /path-to/NaturalEarth -The output files (in .png format) will be located in the directory ``EXPTDIR/CDATE/postprd``, -where in this case ``EXPTDIR`` is ``/path-to/expt_dirs/test_CONUS_25km_GFSv15p2`` and ``CDATE`` +The output files (in ``.png`` format) will be located in the directory ``EXPTDIR/CDATE/postprd``, +where in this case ``EXPTDIR`` is ``/path-to/expt_dirs/test_CONUS_25km_GFSv16`` and ``CDATE`` is ``2019061500``. -Plotting differences from two experiments +Plotting Differences from Two Experiments ========================================= To generate difference plots, the ``plot_allvars_diff.py`` script must be called with the following @@ -151,66 +170,51 @@ seven command line arguments: #. Starting forecast hour #. Ending forecast hour #. Forecast hour increment -#. The top level of the first experiment directory ``EXPTDIR1`` containing the first set of post-processed data. The script will look for the data files in the directory ``EXPTDIR1/CDATE/postprd``. -#. The top level of the first experiment directory ``EXPTDIR2`` containing the second set of post-processed data. The script will look for the data files in the directory ``EXPTDIR2/CDATE/postprd``. -#. The base directory ``CARTOPY_DIR`` of the cartopy shapefiles. The script will look for the shape files (``*.shp``) in the directory ``CARTOPY_DIR/shapefiles/natural_earth/cultural``. +#. The top level of the first experiment directory ``EXPTDIR1`` containing the first set of post-processed data. The script will look for the data files in the directory ``EXPTDIR1/CDATE/postprd``. +#. The top level of the first experiment directory ``EXPTDIR2`` containing the second set of post-processed data. The script will look for the data files in the directory ``EXPTDIR2/CDATE/postprd``. +#. The base directory ``CARTOPY_DIR`` of the cartopy shapefiles. The script will look for the shape files (``*.shp``) in the directory ``CARTOPY_DIR/shapefiles/natural_earth/cultural``. An example of plotting differences from two experiments for the same date and predefined domain where one uses -the "FV3_GFS_v15p2" suite definition file (SDF) and one using the "FV3_RRFS_v1alpha" SDF is as follows: +the "FV3_GFS_v16" suite definition file (SDF) and one using the "FV3_RRFS_v1beta" SDF is as follows: .. code-block:: console - python plot_allvars_diff.py 2019061518 6 18 3 /path-to/expt_dirs1/test_CONUS_3km_GFSv15p2 /path-to/expt_dirs2/test_CONUS_3km_RRFSv1alpha /path-to/NaturalEarth + python plot_allvars_diff.py 2019061518 0 18 6 /path-to/expt_dirs1/test_CONUS_3km_GFSv16 /path-to/expt_dirs2/test_CONUS_3km_RRFSv1beta /path-to/NaturalEarth -In this case, the output png files will be located in the directory ``EXPTDIR1/CDATE/postprd``. +In this case, the output ``.png`` files will be located in the directory ``EXPTDIR1/CDATE/postprd``. -Submitting plotting scripts through a batch system -================================================== +Submitting Plotting Scripts Through a Batch System +====================================================== -If the Python scripts are being used to create plots of multiple forecast lead times and forecast -variables, then you may need to submit them to the batch system. Example scripts are provided called -``sq_job.sh`` and ``sq_job_diff.sh`` for use on a platform such as Hera that uses the Slurm -job scheduler or ``qsub_job.sh`` and ``qsub_job_diff.sh`` for use on a platform such as -Cheyenne that uses PBS as the job scheduler. Examples of these scripts are located under -``ufs-srweather-app/regional_workflow/ush/Python`` and can be used as a starting point to create a batch script -for your platform/job scheduler of use. +If users plan to create plots of multiple forecast lead times and forecast variables, then they may need to submit the Python scripts to the batch system. Sample scripts are provided for use on a platform such as Hera that uses the Slurm job scheduler: ``sq_job.sh`` and ``sq_job_diff.sh``. Equivalent sample scripts are provided for use on a platform such as Cheyenne that uses PBS as the job scheduler: ``qsub_job.sh`` and ``qsub_job_diff.sh``. Examples of these scripts are located under ``ufs-srweather-app/regional_workflow/ush/Python`` and can be used as a starting point to create a batch script for a user's specific platform/job scheduler. At a minimum, the account should be set appropriately prior to job submission: .. code-block:: console - #SBATCH --account=an_account + #SBATCH --account= -Depending on the platform you are running on, you may also need to adjust the settings to use -the correct Python environment and path to the shape files. +Depending on the platform, users may also need to adjust the settings to use the correct Python environment and path to the shape files. -When using these batch scripts, several environment variables must be set prior to submission. +When working with these batch scripts, several environment variables must be set prior to submission. If plotting output from a single cycle, the variables to set are ``HOMErrfs`` and ``EXPTDIR``. -In this case, if the user's login shell is csh/tcsh, these variables can be set as follows: - -.. code-block:: console - - setenv HOMErrfs /path-to/ufs-srweather-app/regional_workflow - setenv EXPTDIR /path-to/experiment/directory - -If the user's login shell is bash, they can be set as follows: +In this case, if the user's login shell is bash, these variables can be set as follows: .. code-block:: console export HOMErrfs=/path-to/ufs-srweather-app/regional_workflow export EXPTDIR=/path-to/experiment/directory -If plotting the difference between the same cycle from two different experiments, the variables -to set are ``HOMErrfs``, ``EXPTDIR1``, and ``EXPTDIR2``. In this case, if the user's login shell -is csh/tcsh, these variables can be set as follows: +If the user's login shell is csh/tcsh, they can be set as follows: .. code-block:: console setenv HOMErrfs /path-to/ufs-srweather-app/regional_workflow - setenv EXPTDIR1 /path-to/experiment/directory1 - setenv EXPTDIR2 /path-to/experiment/directory2 + setenv EXPTDIR /path-to/experiment/directory -If the user's login shell is bash, they can be set as follows: +If plotting the difference between the same cycle from two different experiments, the variables +to set are ``HOMErrfs``, ``EXPTDIR1``, and ``EXPTDIR2``. In this case, if the user's login shell +is bash, these variables can be set as follows: .. code-block:: console @@ -218,21 +222,29 @@ If the user's login shell is bash, they can be set as follows: export EXPTDIR1=/path-to/experiment/directory1 export EXPTDIR2=/path-to/experiment/directory2 +If the user's login shell is csh/tcsh, they can be set as follows: + +.. code-block:: console + + setenv HOMErrfs /path-to/ufs-srweather-app/regional_workflow + setenv EXPTDIR1 /path-to/experiment/directory1 + setenv EXPTDIR2 /path-to/experiment/directory2 + In addition, the variables ``CDATE``, ``FCST_START``, ``FCST_END``, and ``FCST_INC`` in the batch -scripts can be modified depending on the user's needs. By default, ``CDATE`` is set as follows +scripts can be modified depending on the user's needs. By default, ``CDATE`` is set as follows in the batch scripts: .. code-block:: console export CDATE=${DATE_FIRST_CYCL}${CYCL_HRS} -This sets ``CDATE`` to the first cycle in the set of cycles that the experiment has run. If the +This sets ``CDATE`` to the first cycle in the set of cycles that the experiment has run. If the experiment contains multiple cycles and the user wants to plot output from a cycle other than the very first one, ``CDATE`` in the batch scripts will have to be set to the specific YYYYMMDDHH -value for that cycle. Also, to plot hourly forecast output, ``FCST_INC`` should be set to 1; to +value for that cycle. Also, to plot hourly forecast output, ``FCST_INC`` should be set to 1; to plot only a subset of the output hours, ``FCST_START``, ``FCST_END``, and ``FCST_INC`` must be -set accordingly, e.g. to generate plots for every 6th forecast hour starting with forecast hour 6 -and ending with the last forecast hour, use +set accordingly, e.g., to generate plots for every 6th forecast hour starting with forecast hour 6 +and ending with the last forecast hour, use: .. code-block:: console @@ -240,9 +252,10 @@ and ending with the last forecast hour, use export FCST_END=${FCST_LEN_HRS} export FCST_INC=6 -The scripts must be submitted using the command appropriate -for the job scheduler used on your platform. For example, on Hera, -``sq_job.sh`` can be submitted as follows: +.. + COMMENT: Shouldn't the FCST_END line actually read: "export FCST_END=${FCST_START}+${FCST_LEN_HRS}"??? The current code would only work if the forecast starts at 00 hours. + +The scripts must be submitted using the command appropriate for the job scheduler used on the user's platform. For example, on Hera, ``sq_job.sh`` can be submitted as follows: .. code-block:: console diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 1bb7451257..7dbe977941 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -345,6 +345,10 @@ NCDC archive: * NAM: https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/north-american-mesoscale-forecast-system-nam * RAP: https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/rapid-refresh-rap +.. + COMMENT: These links don't work. Did they get moved? Or removed? + + AWS S3: * GFS: https://registry.opendata.aws/noaa-gfs-bdp-pds/ From a7080167ae8bfc35041725625f4c4ca014831146 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 10 May 2022 11:03:56 -0400 Subject: [PATCH 129/158] minor updates to Graphics --- docs/UsersGuide/source/Graphics.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/UsersGuide/source/Graphics.rst b/docs/UsersGuide/source/Graphics.rst index d152e2120a..6abcdb7011 100644 --- a/docs/UsersGuide/source/Graphics.rst +++ b/docs/UsersGuide/source/Graphics.rst @@ -27,12 +27,14 @@ the same cycle starting date/time and forecast hours. The Python scripts require a cycle starting date/time in YYYYMMDDHH format, a starting forecast hour, an ending forecast hour, a forecast hour increment, paths to one or two experiment directories, and a path to the directory where the Cartopy Natural Earth shape files are located. -The full set of Cartopy shape files can be downloaded at https://www.naturalearthdata.com/downloads/. +The full set of Cartopy shape files can be downloaded `here `. For convenience, the small subset of files required for these Python scripts can be obtained from the `EMC ftp data repository `_ or from `AWS cloud storage `_. + .. COMMENT: Update these links!!! + In addition, the Cartopy shape files are available on a number of Level 1 platforms in the following locations: @@ -142,12 +144,15 @@ To generate plots for a single cycle, the ``plot_allvars.py`` script must be cal following six command line arguments: #. Cycle date/time (``CDATE``) in YYYYMMDDHH format -#. Starting forecast hour (same as ``CYCL_HRS`` value) -#. Ending forecast hour -#. Forecast hour increment (same as ``LBC_SPEC_INTVL_HRS`` value) +#. Starting forecast hour +#. Ending forecast hour +#. Forecast hour increment #. The top level of the experiment directory ``EXPTDIR`` containing the post-processed data. The script will look for the data files in the directory ``EXPTDIR/CDATE/postprd``. #. The base directory ``CARTOPY_DIR`` of the cartopy shapefiles. The script will look for the shape files (``*.shp``) in the directory ``CARTOPY_DIR/shapefiles/natural_earth/cultural``. +.. note:: + If a forecast starts at 18h, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. + An example of plotting output from a cycle generated using the sample experiment/workflow configuration in the ``config.community.sh`` script (which uses the GFSv16 suite definition file) is as follows: From 0f1c2237b310b147faff982787d4105c4661ac8d Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 10 May 2022 11:04:52 -0400 Subject: [PATCH 130/158] minor updates to Graphics --- docs/UsersGuide/source/Graphics.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/Graphics.rst b/docs/UsersGuide/source/Graphics.rst index 6abcdb7011..a7c61decd1 100644 --- a/docs/UsersGuide/source/Graphics.rst +++ b/docs/UsersGuide/source/Graphics.rst @@ -179,8 +179,7 @@ seven command line arguments: #. The top level of the first experiment directory ``EXPTDIR2`` containing the second set of post-processed data. The script will look for the data files in the directory ``EXPTDIR2/CDATE/postprd``. #. The base directory ``CARTOPY_DIR`` of the cartopy shapefiles. The script will look for the shape files (``*.shp``) in the directory ``CARTOPY_DIR/shapefiles/natural_earth/cultural``. -An example of plotting differences from two experiments for the same date and predefined domain where one uses -the "FV3_GFS_v16" suite definition file (SDF) and one using the "FV3_RRFS_v1beta" SDF is as follows: +An example of plotting differences from two experiments for the same date and predefined domain where one uses the "FV3_GFS_v16" suite definition file (SDF) and one using the "FV3_RRFS_v1beta" SDF is as follows: .. code-block:: console From 975bce9f5bd5dbafa51267b65d33e69d9b49057b Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 10 May 2022 19:32:11 -0400 Subject: [PATCH 131/158] edit ConfigNewPlatform sections 1-4 --- docs/UsersGuide/source/BuildRunSRW.rst | 6 +- docs/UsersGuide/source/ConfigNewPlatform.rst | 155 +++++-------------- docs/UsersGuide/source/Graphics.rst | 19 +-- 3 files changed, 51 insertions(+), 129 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 5b29f478aa..942f333690 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -113,7 +113,7 @@ The cloned repository contains the configuration files and sub-directories shown Check Out External Components ================================ -The SRW App relies on a variety of components (e.g., regional_workflow, UFS_UTILS, ufs-weather-model, and UPP) detailed in :numref:`Chapter %s ` of this User's Guide. Users must run the ``checkout_externals`` script to link the necessary external repositories to the SRW App. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App to clone the correct tags (code versions) of the external repositories listed in :numref:`Section %s ` into the appropriate directories under the ``regional_workflow`` and ``src`` directories. +The SRW App relies on a variety of components (e.g., regional_workflow, UFS_UTILS, ufs-weather-model, and UPP) detailed in :numref:`Chapter %s ` of this User's Guide. Each component has its own :term:`repository`. Users must run the ``checkout_externals`` script to collect the individual components of the SRW App from their respective git repositories. The ``checkout_externals`` script uses the configuration file ``Externals.cfg`` in the top level directory of the SRW App to clone the correct tags (code versions) of the external repositories listed in :numref:`Section %s ` into the appropriate directories under the ``regional_workflow`` and ``src`` directories. Run the executable that pulls in SRW App components from external repositories: @@ -122,6 +122,7 @@ Run the executable that pulls in SRW App components from external repositories: cd ufs-srweather-app ./manage_externals/checkout_externals +The script should output dialogue indicating that it is retrieving different code repositories. It may take several minutes to download these repositories. .. _BuildExecutables: @@ -269,7 +270,7 @@ From the build directory, run the following commands to build the pre-processing cmake .. -DCMAKE_INSTALL_PREFIX=.. make -j 4 >& build.out & -``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, and ``share`` directories will be created. These directories will contain various components of the SRW App. Its recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. +``-DCMAKE_INSTALL_PREFIX`` specifies the location in which the ``bin``, ``include``, ``lib``, and ``share`` directories will be created. These directories will contain various components of the SRW App. Its recommended value ``..`` denotes one directory up from the build directory. In the next line, the ``make`` call argument ``-j 4`` indicates that the build will run in parallel with 4 threads. Although users can specify a larger or smaller number of threads (e.g., ``-j8``, ``-j2``), it is highly recommended to use at least 4 parallel threads to prevent overly long installation times. The build will take a few minutes to complete. When it starts, a random number is printed to the console, and when it is done, a ``[1]+ Done`` message is printed to the console. ``[1]+ Exit`` indicates an error. Output from the build will be in the ``ufs-srweather-app/build/build.out`` file. When the build completes, users should see the forecast model executable ``ufs_model`` and several pre- and post-processing executables in the ``ufs-srweather-app/bin`` directory. These executables are described in :numref:`Table %s `. @@ -713,6 +714,7 @@ The workflow requires Python 3 with the packages 'PyYAML', 'Jinja2', and 'f90nml .. code-block:: console + module use module load wflow_ conda activate regional_workflow diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index 399a7c3a99..9d706e3ddb 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -4,9 +4,9 @@ Configuring a New Platform ========================== -The UFS SRW Application has been designed to work primarily on a number of Level 1 and 2 support platforms, as specified `here `__. However, it is also designed with flexibility in mind, so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. A full list of prerequisites for installing the UFS SRW App and running the Graduate Student Test can be found in :numref:`Section %s `. +The UFS SRW Application has been designed to work primarily on a number of Level 1 and 2 support platforms, listed `here `__. However, it is also designed with flexibility in mind, so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. A full list of prerequisites for installing the UFS SRW App and running the Graduate Student Test can be found in :numref:`Section %s `. -The first step to installing on a new machine is to install :term:`NCEPLIBS` (https://github.com/NOAA-EMC/NCEPLIBS), the NCEP libraries package, which is a set of libraries created and maintained by NCEP and EMC that are used in many parts of the UFS. NCEPLIBS comes with a large number of prerequisites (see :numref:`Section %s ` for more info), but the only required software prior to starting the installation process are as follows: +The first step to installing on a new machine is to install the :term:`HPC-Stack` (https://github.com/NOAA-EMC/hpc-stack), which is a unified, shell script-based build system created and maintained by NCEP and EMC, which builds the software stack required for the SRW App and its components. HPC-Stack comes with a large number of prerequisites (see :numref:`Section %s ` for more info), but the only required software prior to starting the installation process are as follows: * Fortran compiler with support for Fortran 2003 @@ -38,131 +38,55 @@ For both Linux and macOS, you will need to set the stack size to "unlimited" (if # macOS, this corresponds to 65MB ulimit -S -s unlimited -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 Linux systems, as long as the above software is available, you can move on to the next step: installing the :term:`HPC-Stack` package according to the instructions in :numref:`Chapter %s `. -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 +For macOS systems, some extra software is needed: ``gcc@11``, ``cmake``, ``make``, ``wget``, ``coreutils``, and ``pkg-config``. +It is recommended that you install this software using the `Homebrew `__ package manager for macOS: +* brew install gcc@11 * brew install cmake - +* brew install make +* brew install wget * brew install coreutils - * brew install pkg-config -* brew install gnu-sed - -However, it is also possible to install these utilities via Macports (https://www.macports.org/), or installing each utility individually (not recommended). - -Installing NCEPLIBS-external -============================ -In order to facilitate the installation of NCEPLIBS (and therefore, the SRW App and other UFS applications) on new platforms, EMC maintains a one-stop package containing most of the prerequisite libraries and software necessary for installing NCEPLIBS. This package is known as NCEPLIBS-external, and is maintained in a git repository at https://github.com/NOAA-EMC/NCEPLIBS-external. Instructions for installing these will depend on your platform, but generally so long as all the above-mentioned prerequisites have been installed you can follow the proceeding instructions verbatim (in bash; a csh-based shell will require different commands). Some examples for installing on specific platforms can be found in the `NCEPLIBS-external/doc directory `. - - -These instructions will install the NCEPLIBS-external in the current directory tree, so be sure you are in the desired location before starting. - -.. code-block:: console - - export WORKDIR=`pwd` - export INSTALL_PREFIX=${WORKDIR}/NCEPLIBS-ufs-v2.0.0/ - export CC=gcc - export FC=gfortran - export CXX=g++ - -The CC, CXX, and FC variables should specify the C, C++, and Fortran compilers you will be using, respectively. They can be the full path to the compiler if necessary (for example, on a machine with multiple versions of the same compiler). It will be important that all libraries and utilities are built with the same set of compilers, so it is best to set these variables once at the beginning of the process and not modify them again. +.. + COMMENT: Is this still accurate? It seems like we should delete the last 2 and add openssl@3, Lmod, curl, libtiff. -.. code-block:: console - - mkdir -p ${INSTALL_PREFIX}/src && cd ${INSTALL_PREFIX}/src - git clone -b release/public-v2 --recursive https://github.com/NOAA-EMC/NCEPLIBS-external - cd NCEPLIBS-external - mkdir build && cd build - cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} .. 2>&1 | tee log.cmake - make -j4 2>&1 | tee log.make +However, it is also possible to install these utilities via `Macports `__ or by installing each utility individually (not recommended). -The previous commands go through the process of cloning the git repository for NCEPLIBS-external, creating and entering a build directory, and invoking cmake and make to build the code/libraries. The ``make`` step will take a while; as many as a few hours depending on your machine and various settings. It is highly recommended you use at least 4 parallel make processes to prevent overly long installation times. The ``-j4`` option in the make command specifies 4 parallel make processes, ``-j8`` would specify 8 parallel processes, while omitting the flag all together will run make serially (not recommended). -If you would rather use a different version of one or more of the software packages included in NCEPLIBS-external, you can skip building individual parts of the package by including the proper flags in your call to cmake. For example: +Installing the HPC-Stack +=========================== +Prior to building the UFS SRW Application on a new machine, users will need to install the :term:`HPC-Stack`. Installation instructions appear in both the `HPC-Stack documentation `__ and in :numref:`Chapter %s ` of this User's Guide. The instructions will vary somewhat 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`` to build the code. This process will create a number of modulefiles and scripts that will be used for setting up the build environment for the UFS SRW App. -.. code-block:: console +Once the HPC-Stack has been successfully installed, users can move on to building the UFS SRW Application. - cmake -DBUILD_MPI=OFF -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} .. 2>&1 | tee log.cmake +.. note:: + The ``ESMFMKFILE`` variable allows HPC-Stack to find the location where ESMF has been built; if users receive a ``ESMF not found, abort`` error, they may need to specify a slightly different location: -will skip the building of MPICH that comes with NCEPLIBS-external. See the readme file ``NCEPLIBS-external/README.md`` for more information on these flags, or for general troubleshooting. + .. code-block:: console -Once NCEPLIBS-external is installed, you can move on to installing NCEPLIBS. + export ESMFMKFILE=${INSTALL_PREFIX}/lib64/esmf.mk -Installing NCEPLIBS -=================== -Prior to building the UFS SRW Application on a new machine, you will need to install NCEPLIBS. Installation instructions will again depend on your platform, but so long as NCEPLIBS-external has been installed successfully you should be able to build NCEPLIBS. The following instructions will install the NCEPLIBS in the same directory tree as was used for NCEPLIBS-external above, so if you did not install NCEPLIBS-external in the same way, you will need to modify these commands. + Then they can delete and re-create the build directory and continue the build process as described above. -.. code-block:: console +.. note:: - cd ${INSTALL_PREFIX}/src - git clone -b release/public-v2 --recursive https://github.com/NOAA-EMC/NCEPLIBS - cd NCEPLIBS - mkdir build && cd build - export ESMFMKFILE=${INSTALL_PREFIX}/lib/esmf.mk - cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} -DOPENMP=ON .. 2>&1 | tee log.cmake - make -j4 2>&1 | tee log.make - make deploy 2>&1 | tee log.deploy - -As with NCEPLIBS-external, the above commands go through the process of cloning the git repository for NCEPLIBS, creating and entering a build directory, and invoking cmake and make to build the code. The ``make deploy`` step created a number of modulefiles and scripts that will be used for setting up the build environment for the UFS SRW App. The ``ESMFMKFILE`` variable allows NCEPLIBS to find the location where ESMF has been built; if you receive a ``ESMF not found, abort`` error, you may need to specify a slightly different location: - -.. code-block:: console + If users skipped the building of any of the software provided by HPC-Stack, they may need to add the appropriate locations to their ``CMAKE_PREFIX_PATH`` variable. Multiple directories may be added, separated by semicolons (;) as in the following example: - export ESMFMKFILE=${INSTALL_PREFIX}/lib64/esmf.mk + .. code-block:: console -Then delete and re-create the build directory and continue the build process as described above. + cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DCMAKE_PREFIX_PATH=”${INSTALL_PREFIX};/location/of/other/software” -DOPENMP=ON .. 2>&1 | tee log.cmake -If you skipped the building of any of the software provided by NCEPLIBS-external, you may need to add the appropriate locations to your ``CMAKE_PREFIX_PATH`` variable. Multiple directories may be added, separated by semicolons (;) like in the following example: - -.. code-block:: console - - cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DCMAKE_PREFIX_PATH=”${INSTALL_PREFIX};/location/of/other/software” -DOPENMP=ON .. 2>&1 | tee log.cmake - -Further information on including prerequisite libraries, as well as other helpful tips, can be found in the ``NCEPLIBS/README.md`` file. - -Once the NCEPLIBS package has been successfully installed, you can move on to building the UFS SRW Application. +.. + COMMENT: Are these notes relevant now that NCEPLIBS/NCEPLIBS-external have been changed to HPC-Stack? Building the UFS SRW Application ======================================= -Building the UFS SRW App is similar to building NCEPLIBS, in that the code is stored in a git repository and is built using CMake software. The first step is to retrieve the code from GitHub, using the variables defined earlier: -.. code-block:: console - - cd ${WORKDIR} - git clone -b release/public-v1 https://github.com/ufs-community/ufs-srweather-app.git - cd ufs-srweather-app/ - ./manage_externals/checkout_externals - -Here the procedure differs a bit from NCEPLIBS and NCEPLIBS-external. The UFS SRW App is maintained using an umbrella git repository that collects the individual components of the application from their individual, independent git repositories. This is handled using "Manage Externals" software, which is included in the application; this is the final step listed above, which should output a bunch of dialogue indicating that it is retrieving different code repositories as described in :numref:`Table %s `. It may take several minutes to download these repositories. - -Once the Manage Externals step has completed, you will need to make sure your environment is set up so that the UFS SRW App can find all of the prerequisite software and libraries. There are a few ways to do this, the simplest of which is to load a modulefile if your machine supports Lua Modules: - -.. code-block:: console - - module use ${INSTALL_PREFIX}/modules - module load NCEPLIBS/2.0.0 -If your machine does not support Lua but rather TCL modules, see instructions in the ``NCEPLIBS/README.md`` file for converting to TCL modulefiles. -If your machine does not support modulefiles, you can instead source the provided bash script for setting up the environment: - -.. code-block:: console - - source ${INSTALL_PREFIX}/bin/setenv_nceplibs.sh - -This script, just like the modulefiles, will set a number of environment variables that will allow CMake to easily find all the libraries that were just built. There is also a csh version of the script in the same directory if your shell is csh-based. If you are using your machine’s pre-built version of any of the NCEP libraries (not recommended), reference that file to see which variables should be set to point CMake in the right direction. - -At this point there are just a few more variables that need to be set prior to building: - -.. code-block:: console - - export CMAKE_C_COMPILER=mpicc - 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: @@ -172,13 +96,6 @@ If you are using your machine’s built-in MPI compilers, it is recommended you This is the variable used by the weather model to set a few additional flags based on your machine. The available options can be found `here `_. -Now all the prerequisites have been installed and variables set, so you should be ready to build the model! - -.. code-block:: console - - mkdir build && cd build - cmake .. -DCMAKE_INSTALL_PREFIX=.. | tee log.cmake - make -j4 | tee log.make On many platforms this build step will take less than 30 minutes, but for some machines it may take up to a few hours, depending on the system architecture, compiler and compiler flags, and number of parallel make processes used. @@ -202,7 +119,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 `. @@ -331,7 +248,7 @@ The line numbers may differ slightly given future bug fixes. Additionally, you m Software/Operating System Requirements ====================================== -Those requirements highlighted in **bold** are included in the NCEPLIBS-external (https://github.com/NOAA-EMC/NCEPLIBS-external) package. +Those requirements highlighted in **bold** are included in the `HPC-Stack `__. **Minimum platform requirements for the UFS SRW Application and NCEPLIBS:** @@ -358,13 +275,13 @@ Those requirements highlighted in **bold** are included in the NCEPLIBS-external * MPI (**MPICH**, OpenMPI, or other implementation) -* CMake v3.12+ +* CMake v3.15+ * Software libraries * **netCDF (C and Fortran libraries)** * **HDF5** - * **ESMF** 8.0.0 + * **ESMF** 8.0.2 * **Jasper** * **libJPG** * **libPNG** @@ -375,11 +292,15 @@ Those requirements highlighted in **bold** are included in the NCEPLIBS-external macOS-specific prerequisites: -* brew install wget +* brew install gcc@11 * brew install cmake +* brew install make +* brew install wget * brew install coreutils * brew install pkg-config -* brew install gnu-sed + +.. + COMMENT: Do we need these last 2? Are there others? (e.g., openssl@3?) Lmod, curl, libtiff Optional but recommended prerequisites: @@ -388,3 +309,7 @@ Optional but recommended prerequisites: * Rocoto Workflow Management System (1.3.1) * **CMake v3.15+** * Python packages scipy, matplotlib, pygrib, cartopy, and pillow for graphics +* Lmod + +.. + COMMENT: Are we supporting any installations that don't use Lmod? Should this come under "required?" Or not because it is not mandatory for running the SRW App (but do we know that?). diff --git a/docs/UsersGuide/source/Graphics.rst b/docs/UsersGuide/source/Graphics.rst index a7c61decd1..6243696ce7 100644 --- a/docs/UsersGuide/source/Graphics.rst +++ b/docs/UsersGuide/source/Graphics.rst @@ -72,10 +72,8 @@ On NOAA Cloud: .. code-block:: console - /contrib/........... + /contrib/EPIC/NaturalEarth -.. - COMMENT: Update path for NOAA Cloud. The medium scale (1:50m) cultural and physical shapefiles are used to create coastlines and other geopolitical borders on the map. Cartopy provides the ‘background_img()’ method to add background @@ -119,11 +117,11 @@ On Gaea: On NOAA Cloud: - module use ............... - module load .................. +.. code-block:: console -.. - COMMENT: Update for NOAA Cloud. + module use /contrib/GST/miniconda3/modulefiles + module load miniconda3/4.10.3 + conda activate regional_workflow .. note:: @@ -202,7 +200,7 @@ Depending on the platform, users may also need to adjust the settings to use the When working with these batch scripts, several environment variables must be set prior to submission. If plotting output from a single cycle, the variables to set are ``HOMErrfs`` and ``EXPTDIR``. -In this case, if the user's login shell is bash, these variables can be set as follows: +If the user's login shell is bash, these variables can be set as follows: .. code-block:: console @@ -217,7 +215,7 @@ If the user's login shell is csh/tcsh, they can be set as follows: setenv EXPTDIR /path-to/experiment/directory If plotting the difference between the same cycle from two different experiments, the variables -to set are ``HOMErrfs``, ``EXPTDIR1``, and ``EXPTDIR2``. In this case, if the user's login shell +to set are ``HOMErrfs``, ``EXPTDIR1``, and ``EXPTDIR2``. If the user's login shell is bash, these variables can be set as follows: .. code-block:: console @@ -256,9 +254,6 @@ and ending with the last forecast hour, use: export FCST_END=${FCST_LEN_HRS} export FCST_INC=6 -.. - COMMENT: Shouldn't the FCST_END line actually read: "export FCST_END=${FCST_START}+${FCST_LEN_HRS}"??? The current code would only work if the forecast starts at 00 hours. - The scripts must be submitted using the command appropriate for the job scheduler used on the user's platform. For example, on Hera, ``sq_job.sh`` can be submitted as follows: .. code-block:: console From 3ae46d9b25667a2bf1b67eb17c8e36a34745fdad Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 11 May 2022 15:51:34 -0400 Subject: [PATCH 132/158] ConfigNewPlatform edits --- docs/UsersGuide/source/BuildRunSRW.rst | 2 +- docs/UsersGuide/source/ConfigNewPlatform.rst | 213 +++++++------------ docs/UsersGuide/source/ConfigWorkflow.rst | 4 +- docs/UsersGuide/source/LAMGrids.rst | 2 + 4 files changed, 85 insertions(+), 136 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 942f333690..5c49bb95e9 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -938,7 +938,7 @@ In addition to the baseline tasks described in :numref:`Table %s `. There are two main ways to run the workflow with Rocoto: (1) with the ``launch_FV3LAM_wflow.sh`` script, and (2) by manually calling the ``rocotorun`` command. Users can also automate the workflow using a crontab. +The information in this section assumes that Rocoto is available on the desired platform. All official HPC platforms for the UFS SRW App release make use of the Rocoto workflow management software for running experiments. However, Rocoto cannot be used when running the workflow within a container. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts according to the process outlined in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: (1) with the ``launch_FV3LAM_wflow.sh`` script, and (2) by manually calling the ``rocotorun`` command. Users can also automate the workflow using a crontab. .. note:: Users may find it helpful to review :numref:`Chapter %s ` to gain a better understanding of Rocoto commands and workflow management before continuing, but this is not required to run the experiment. diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index 9d706e3ddb..7fd867bfe5 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -1,12 +1,12 @@ .. _ConfigNewPlatform: -========================== +============================ Configuring a New Platform -========================== +============================ The UFS SRW Application has been designed to work primarily on a number of Level 1 and 2 support platforms, listed `here `__. However, it is also designed with flexibility in mind, so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. A full list of prerequisites for installing the UFS SRW App and running the Graduate Student Test can be found in :numref:`Section %s `. -The first step to installing on a new machine is to install the :term:`HPC-Stack` (https://github.com/NOAA-EMC/hpc-stack), which is a unified, shell script-based build system created and maintained by NCEP and EMC, which builds the software stack required for the SRW App and its components. HPC-Stack comes with a large number of prerequisites (see :numref:`Section %s ` for more info), but the only required software prior to starting the installation process are as follows: +The first step to installing on a new machine is to install the :term:`HPC-Stack` (https://github.com/NOAA-EMC/hpc-stack), which is a unified, shell script-based build system created and maintained by NCEP and EMC, which builds the software stack required for the SRW App and its components. HPC-Stack comes with a large number of prerequisites (see :numref:`Section %s ` for more info), but the only required software prior to starting the installation process is as follows: * Fortran compiler with support for Fortran 2003 @@ -28,20 +28,19 @@ The first step to installing on a new machine is to install the :term:`HPC-Stack * 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 both Linux and macOS, you will need to set the stack size to "unlimited" (if allowed) or the largest possible value. +For both Linux and macOS systems, users 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 + # MacOS, this corresponds to 65MB ulimit -S -s unlimited -For Linux systems, as long as the above software is available, you can move on to the next step: installing the :term:`HPC-Stack` package according to the instructions in :numref:`Chapter %s `. +For Linux systems, as long as the above software is available, users can move on to the next step: installing the :term:`HPC-Stack` package according to the instructions in :numref:`Chapter %s `. -For macOS systems, some extra software is needed: ``gcc@11``, ``cmake``, ``make``, ``wget``, ``coreutils``, and ``pkg-config``. -It is recommended that you install this software using the `Homebrew `__ package manager for macOS: +For MacOS systems, some extra software is needed: ``gcc@11``, ``cmake``, ``make``, ``wget``, ``coreutils``, and ``pkg-config``. It is recommended that users install this software using the `Homebrew `__ package manager for MacOS: * brew install gcc@11 * brew install cmake @@ -85,169 +84,117 @@ Once the HPC-Stack has been successfully installed, users can move on to buildin Building the UFS SRW Application ======================================= +For a detailed explanation of how to build and run the SRW App on any supported system, see :numref:`Chapter %s `. The overall procedure for generating an experiment is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. An overview of the required steps appears below. However, users can expect to access other referenced sections of this User's Guide for more detail. + #. Clone the SRW App from GitHub: + .. code-block:: console -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: + git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git -.. code-block:: console + #. Check out the external repositories: - export CMAKE_Platform=macosx.gnu + .. code-block:: console -This is the variable used by the weather model to set a few additional flags based on your machine. The available options can be found `here `_. + cd ufs-srweather-app + ./manage_externals/checkout_externals + #. Set up the build environment. -On many platforms this build step will take less than 30 minutes, but for some machines it may take up to a few hours, depending on the system architecture, compiler and compiler flags, and number of parallel make processes used. + .. code-block:: console -Setting Up Your Python Environment -================================== -The regional_workflow repository contains scripts for generating and running experiments, and these require some specific python packages to function correctly. First, as mentioned before, your platform will need Python 3.6 or newer installed. Once this is done, you will need to install several python packages that are used by the workflow: ``jinja2`` (https://jinja2docs.readthedocs.io/), ``pyyaml`` (https://pyyaml.org/wiki/PyYAML), and ``f90nml`` (https://pypi.org/project/f90nml/). These packages can be installed individually, but it is recommended you use a package manager (https://www.datacamp.com/community/tutorials/pip-python-package-manager). + source etc/lmod-setup.sh -If you have conda on your machine: + where refers to the user's platform (e.g., ``macos``, ``gaea``, ``odin``, ``singularity``). -.. code-block:: console + Users will also need to load the "build" modulefile appropriate to their system. On Level 3 & 4 systems, users can adapt an existing modulefile (such as ``build_macos_gnu``) to their system. - conda install jinja2 pyyaml f90nml + .. code-block:: console -Otherwise you may be able to use pip3 (the Python3 package manager; may need to be installed separately depending on your platform): + module use + module load build__ -.. code-block:: console + #. Build the executables - pip3 install jinja2 pyyaml f90nml + From the top-level ``ufs-srweather-app`` directory, run: -Running the graphics scripts in ``${WORKDIR}/ufs-srweather-app/regional_workflow/ush/Python`` will require the additional packages ``pygrib``, ``cartopy``, ``matplotlib``, ``scipy``, and ``pillow``. These can be installed in the same way as described above. + .. code-block:: console -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). + mkdir build + cd build + cmake .. -DCMAKE_INSTALL_PREFIX=.. + make -j 4 >& build.out & -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 `. + #. Download and stage data (both the fix files and the :term:`IC/LBC` files) according to the instructions in :numref:`Chapter %s ` (if on a Level 3-4 system). -Once the data has been staged, setting up your experiment on a platform without a workflow manager is similar to the procedure for other platforms described in earlier chapters. Enter the ``${WORKDIR}/ufs-srweather-app/regional_workflow/ush`` directory and configure the workflow by creating a ``config.sh`` file as described in :numref:`Chapter %s `. There will be a few specific settings that you may need change prior to generating the experiment compared to the instructions for pre-configured platforms: + .. code-block:: console -``MACHINE="MACOS" or MACHINE="LINUX"`` - These are the two ``MACHINE`` settings for generic, non-Rocoto-based platforms; you should choose the one most appropriate for your machine. ``MACOS`` has its own setting due to some differences in how command-line utilities function on Darwin-based operating systems. + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/ + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/FV3GFS/grib2/2019061518/ -``LAYOUT_X=2`` + #. Configure the experiment parameters. -``LAYOUT_Y=2`` - These are the settings that control the MPI decomposition when running the weather model. There are default values, but for your machine it is recommended that you specify your own layout to achieve the correct number of MPI processes for your application. In total, your machine should be able to handle ``LAYOUT_X×LAYOUT_Y+WRTCMP_write_tasks_per_group`` tasks. ``WRTCMP_write_tasks_per_group`` is the number of MPI tasks that will be set aside for writing model output, and it is a setting dependent on the domain you have selected. You can find and edit the value of this variable in the file ``regional_workflow/ush/set_predef_grid_params.sh``. + .. code-block:: console -``RUN_CMD_UTILS="mpirun -np 4"`` - This is the run command for MPI-enabled pre-processing utilities. Depending on your machine and your MPI installation, you may need to use a different command for launching an MPI-enabled executable. + cd regional_workflow/ush + cp config.community.sh config.sh + + 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:`Chapter %s `. Parameters and valid values are listed in :numref:`Chapter %s `. -``RUN_CMD_POST="mpirun -np 1"`` - This is the same as RUN_CMD_UTILS but for UPP. + #. Load the python environment for the regional workflow. Users on Level 3-4 systems will need to use one of the existing ``wflow_`` modulefiles (e.g., ``wflow_macos``) and adapt it to their system. -``RUN_CMD_FCST='mpirun -np ${PE_MEMBER01}'`` - This is the run command for the weather model. It is **strongly** recommended that you use the variable ``${PE_MEMBER01}`` here, which is calculated within the workflow generation script (based on the layout and write tasks described above) and is the number of MPI tasks that the weather model will expect to run with. Running the weather model with a different number of MPI tasks than the workflow has been set up for can lead to segmentation faults and other errors. It is also important to use single quotes here (or escape the “$” character) so that ``PE_MEMBER01`` is not referenced until runtime, since it is not defined at the beginning of the workflow generation script. + .. code-block:: console -``FIXgsm=${WORKDIR}/data/fix_am`` - The location of the ``fix_am`` static files. This and the following two static data sets will need to be downloaded to your machine, as described in :numref:`Section %s `. + module use + module load wflow_ + conda activate regional_workflow -``TOPO_DIR=${WORKDIR}/data/fix_orog`` - Location of ``fix_orog`` static files + #. Generate the experiment workflow. -``SFC_CLIMO_INPUT_DIR=${WORKDIR}/data/fix_sfc_climo`` - Location of ``climo_fields_netcdf`` static files + .. code-block:: console -Once you are happy with your settings in ``config.sh``, it is time to run the workflow and move to the experiment directory (that is printed at the end of the script’s execution): + ./generate_FV3LAM_wflow.sh -.. code-block:: console + #. Run the regional workflow. There are several methods available for this step, which are discussed in :numref:`Chapter %s ` and :numref:`Chapter %s `. One possible method is summarized below. It requires the Rocoto Workflow Manager. - ./generate_FV3LAM_wflow.sh - export EXPTDIR="your experiment directory" - cd $EXPTDIR + .. code-block:: console -From here, you can run each individual task of the UFS SRW App using the provided run scripts: + cd $EXPTDIR + ./launch_FV3LAM_wflow.sh -.. code-block:: console + To launch the workflow and check the experiment's progress: - 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: - -.. table:: Example wallclock times for each workflow task. - - - +--------------------+----------------------------+------------+-----------+ - | **UFS Component** | **Script Name** | **Num.** | **Wall** | - | | | **Cores** | **time** | - +====================+============================+============+===========+ - | UFS_UTILS | ./run_get_ics.sh | n/a | 3 s | - +--------------------+----------------------------+------------+-----------+ - | UFS_UTILS | ./run_get_lbcs.sh | n/a | 3 s | - +--------------------+----------------------------+------------+-----------+ - | UFS_UTILS | ./run_make_grid.sh | n/a | 9 s | - +--------------------+----------------------------+------------+-----------+ - | UFS_UTILS | ./run_make_orog.sh | 4 | 1 m | - +--------------------+----------------------------+------------+-----------+ - | UFS_UTILS | ./run_make_sfc_climo.sh | 4 | 27 m | - +--------------------+----------------------------+------------+-----------+ - | UFS_UTILS | ./run_make_ics.sh | 4 | 5 m | - +--------------------+----------------------------+------------+-----------+ - | UFS_UTILS | ./run_make_lbcs.sh | 4 | 5 m | - +--------------------+----------------------------+------------+-----------+ - | ufs-weather-model | ./run_fcst.sh | 6 | 1h 40 m | - +--------------------+----------------------------+------------+-----------+ - | UPP | ./run_post.sh | 1 | 7 m | - +--------------------+----------------------------+------------+-----------+ - -Running on a New Platform with Rocoto Workflow Manager -====================================================== -All official HPC platforms for the UFS SRW App release make use of the Rocoto workflow management software for running experiments. If you would like to use the Rocoto workflow manager on a new machine, you will have to make modifications to the scripts in the ``regional_workflow`` repository. The easiest way to do this is to search the files in the ``regional_workflow/scripts`` and ``regional_workflow/ush`` directories for an existing platform name (e.g. ``CHEYENNE``) and add a stanza for your own unique machine (e.g. ``MYMACHINE``). As an example, here is a segment of code from ``regional_workflow/ush/setup.sh``, where the highlighted text is an example of the kind of change you will need to make: + .. code-block:: console + + ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow + +Optionally, users may `configure their own grid `, instead of using a predefined grid, and `plot the output ` of their experiment(s). -.. code-block:: console - :emphasize-lines: 11-18 - - ... - "CHEYENNE") - WORKFLOW_MANAGER="rocoto" - NCORES_PER_NODE=36 - SCHED="${SCHED:-pbspro}" - QUEUE_DEFAULT=${QUEUE_DEFAULT:-"regular"} - QUEUE_HPSS=${QUEUE_HPSS:-"regular"} - QUEUE_FCST=${QUEUE_FCST:-"regular"} - ;; - - "MYMACHINE") - WORKFLOW_MANAGER="rocoto" - NCORES_PER_NODE=your_machine_cores_per_node - SCHED="${SCHED:-your_machine_scheduler}" - QUEUE_DEFAULT=${QUEUE_DEFAULT:-"your_machine_queue_name"} - QUEUE_HPSS=${QUEUE_HPSS:-"your_machine_queue_name"} - QUEUE_FCST=${QUEUE_FCST:-"your_machine_queue_name"} - ;; - - "STAMPEDE") - WORKFLOW_MANAGER="rocoto" - ... - -You will also need to add ``MYMACHINE`` to the list of valid machine names in ``regional_workflow/ush/valid_param_vals.sh``. The minimum list of files that will need to be modified in this way are as follows (all in the ``regional_workflow`` repository): - -* ``scripts/exregional_run_post.sh``, line 131 -* ``scripts/exregional_make_sfc_climo.sh``, line 162 -* ``scripts/exregional_make_lbcs.sh``, line 114 -* ``scripts/exregional_make_orog.sh``, line 147 -* ``scripts/exregional_make_grid.sh``, line 145 -* ``scripts/exregional_run_fcst.sh``, line 140 -* ``scripts/exregional_make_ics.sh``, line 114 -* ``ush/setup.sh``, lines 431 and 742 -* ``ush/launch_FV3LAM_wflow.sh``, line 104 -* ``ush/get_extrn_mdl_file_dir_info.sh``, many lines, starting around line 589 -* ``ush/valid_param_vals.sh``, line 3 -* ``ush/load_modules_run_task.sh``, line 126 -* ``ush/set_extrn_mdl_params.sh``, many lines, starting around line 61 - -The line numbers may differ slightly given future bug fixes. Additionally, you may need to make further changes depending on the exact setup of your machine and Rocoto installation. Information about installing and configuring Rocoto on your machine can be found in the Rocoto GitHub repository: https://github.com/christopherwharrop/rocoto + +Background Knowledge Prerequisites +===================================== + +In general, the instructions in this documentation assume that users have certain background knowledge. + +* Familiarity with LINUX/UNIX systems +* Command line basics +* System configuration knowledge (e.g., compilers, environment variables, paths, etc.) +* Meteorology & Numerical Weather Prediction + +.. + COMMENT: Suggested sub-bullets for Meteorology/NWP? + +Additional background knowledge in the following areas could be helpful: +* High-Performance Computing (HPC) Systems for those running the SRW App on an HPC system +* Programming (particularly Python) for those interested in contributing to the SRW App code +* Creating an SSH Tunnel to access HPC systems from the command line +* Containerization +* Workflow Managers/Rocoto .. _SW-OS-Requirements: Software/Operating System Requirements -====================================== +======================================= Those requirements highlighted in **bold** are included in the `HPC-Stack `__. **Minimum platform requirements for the UFS SRW Application and NCEPLIBS:** @@ -308,7 +255,7 @@ Optional but recommended prerequisites: * Bash v4+ * Rocoto Workflow Management System (1.3.1) * **CMake v3.15+** -* Python packages scipy, matplotlib, pygrib, cartopy, and pillow for graphics +* Python packages ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``, and ``pillow`` for graphics * Lmod .. diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index b4d006a695..1e88a49309 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -93,10 +93,10 @@ Parameters for Running Without a Workflow Manager These settings control run commands for platforms without a workflow manager. Values will be ignored unless ``WORKFLOW_MANAGER="none"``. ``RUN_CMD_UTILS``: (Default: "mpirun -np 1") - The run command for pre-processing utilities (shave, orog, sfc_climo_gen, etc.). This can be left blank for smaller domains, in which case the executables will run without :term:`MPI`. + The run command for MPI-enabled pre-processing utilities (e.g., shave, orog, sfc_climo_gen). This can be left blank for smaller domains, in which case the executables will run without :term:`MPI`. Users may need to use a different command for launching an MPI-enabled executable depending on their machine and MPI installation. ``RUN_CMD_FCST``: (Default: "mpirun -np \${PE_MEMBER01}") - The run command for the model forecast step. This will be appended to the end of the variable definitions file (``var_defns.sh``). + The run command for the model forecast step. This will be appended to the end of the variable definitions file (``var_defns.sh``). Changing the ``${PE_MEMBER01}`` variable is **not** recommended; it refers to the number of MPI tasks that the Weather Model will expect to run with. Running the Weather Model with a different number of MPI tasks than the workflow has been set up for can lead to segmentation faults and other errors. It is also important to escape the ``$`` character or use single quotes here so that ``PE_MEMBER01`` is not referenced until runtime, since it is not defined at the beginning of the workflow generation script. ``RUN_CMD_POST``: (Default: "mpirun -np 1") The run command for post-processing (:term:`UPP`). Can be left blank for smaller domains, in which case UPP will run without :term:`MPI`. diff --git a/docs/UsersGuide/source/LAMGrids.rst b/docs/UsersGuide/source/LAMGrids.rst index ddbdb0fa8b..ffdb127f25 100644 --- a/docs/UsersGuide/source/LAMGrids.rst +++ b/docs/UsersGuide/source/LAMGrids.rst @@ -111,6 +111,8 @@ However, for users who would like to use the 25-km domain for research, the ``FV Ultimately, the choice of grid is experiment-dependent and resource-dependent. For example, a user may wish to use the ``FV3_GFS_v16`` physics suite, which uses cumulus physics that are not configured to run at the 3-km resolution. In this case, the 13-km or 25-km domain options are better suited to the experiment. Users will also have fewer computational constraints when running with the 13-km and 25-km domains, so depending on the resources available to them, certain grids may be better options than others. +.. UserDefinedGrid: + Creating User-Generated Grids =============================== While the four predefined grids available in this release are ideal for users just starting From 563cc6894fa5e6061bffe679bc41095d7bdce1f2 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 11 May 2022 16:38:15 -0400 Subject: [PATCH 133/158] resolve merge conflicts --- docs/UsersGuide/source/BuildRunSRW.rst | 162 ------------------- docs/UsersGuide/source/ConfigNewPlatform.rst | 8 - docs/UsersGuide/source/Glossary.rst | 16 -- docs/UsersGuide/source/WE2Etests.rst | 19 ++- 4 files changed, 9 insertions(+), 196 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 55b7dcf60d..6f851bd06d 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -515,7 +515,6 @@ The user must specify certain basic information about the experiment in a ``conf | EXTRN_MDL_FILES_ICS | "" | "gfs.pgrb2.0p25.f000" | +--------------------------------+-------------------+--------------------------------------------------------+ | EXTRN_MDL_SOURCE_BASEDIR_LBCS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | -<<<<<<< HEAD +--------------------------------+-------------------+--------------------------------------------------------+ | EXTRN_MDL_FILES_LBCS | "" | "gfs.pgrb2.0p25.f006" | +--------------------------------+-------------------+--------------------------------------------------------+ @@ -544,45 +543,10 @@ The user must specify certain basic information about the experiment in a ``conf | RUN_TASK_VX_ENSGRID | "FALSE" | "FALSE" | +--------------------------------+-------------------+--------------------------------------------------------+ | RUN_TASK_VX_ENSPOINT | "FALSE" | "FALSE" | -======= +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_FILES_LBCS | "" | "gfs.pgrb2.0p25.f006" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | MODEL | "" | FV3_GFS_v16_CONUS_25km" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | METPLUS_PATH | "" | "/path/to/METPlus" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | MET_INSTALL_DIR | "" | "/path/to/MET" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | CCPA_OBS_DIR | "" | "/path/to/processed/CCPA/data" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | MRMS_OBS_DIR | "" | "/path/to/processed/MRMS/data" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | NDAS_OBS_DIR | "" | "/path/to/processed/NDAS/data" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | RUN_TASK_GET_OBS_CCPA | "FALSE" | "FALSE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | RUN_TASK_GET_OBS_MRMS | "FALSE" | "FALSE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | RUN_TASK_GET_OBS_NDAS | "FALSE" | "FALSE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | RUN_TASK_VX_GRIDSTAT | "FALSE" | "FALSE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | RUN_TASK_VX_POINTSTAT | "FALSE" | "FALSE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - | RUN_TASK_VX_ENSGRID | "FALSE" | "FALSE" | ->>>>>>> origin/develop - +--------------------------------+-------------------+--------------------------------------------------------+ - | RUN_TASK_VX_ENSPOINT | "FALSE" | "FALSE" | - +--------------------------------+-------------------+--------------------------------------------------------+ - - -<<<<<<< HEAD -======= ->>>>>>> origin/develop To get started, make a copy of ``config.community.sh``. From the ``ufs-srweather-app`` directory, run: .. code-block:: console @@ -693,47 +657,6 @@ For WCOSS_CRAY: found in the ``regional_workflow/tests/baseline_configs`` directory. .. _VXConfig: -<<<<<<< HEAD - -Configure METplus Verification Suite (Optional) --------------------------------------------------- - -Users who want to use the METplus verification suite to test their forecasts need to load the appropriate modules and add additional information to their ``config.sh`` file. Other users may skip to the :ref:`next section `. - -.. note:: - METplus is preinstalled on `Level 1 `__ systems. METplus *installation* is currently not supported for this release of the SRW App, but METplus *use* is supported on systems with a functioning METplus installation. For more information about METplus, see :numref:`Section %s `. - -Once installed, METplus users must load the appropriate modules (changing the module location and MET version to correspond to their system's installation): - -.. code-block:: console - - module use -a - module load met/<10.0.0> - -Then, the path to the MET and METplus directories must be added to ``config.sh``: - -.. code-block:: console - - METPLUS_PATH="" - MET_INSTALL_DIR="" - -Users who have already staged the METplus verification data (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data and set the corresponding ``RUN_TASK_GET_OBS_*`` parameters to "FALSE" in ``config.sh``. - -.. code-block:: console - - CCPA_OBS_DIR="/path/to/UFS_SRW_app/develop/obs_data/ccpa/proc" - MRMS_OBS_DIR="/path/to/UFS_SRW_app/develop/obs_data/mrms/proc" - NDAS_OBS_DIR="/path/to/UFS_SRW_app/develop/obs_data/ndas/proc" - RUN_TASK_GET_OBS_CCPA="FALSE" - RUN_TASK_GET_OBS_MRMS="FALSE" - RUN_TASK_GET_OBS_NDAS="FALSE" - -If users have access to NOAA HPSS but have not pre-staged the data, they can simply set the ``RUN_TASK_GET_OBS_*`` tasks to "TRUE", and the machine will attempt to download the appropriate data from NOAA HPSS. The ``*_OBS_DIR`` paths must be set to the location where users want the downloaded data to reside. - -Users who do not have access to NOAA HPSS and do not have the data on their system will need to download :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data manually from collections of publicly available data, such as the ones listed `here `__. - -Next, the verification tasks must be turned on according to the user's needs. Users should add the some or all of the following tasks to ``config.sh``, depending on the verification procedure(s) they have in mind: -======= Configure METplus Verification Suite (Optional) -------------------------------------------------- @@ -774,7 +697,6 @@ If users have access to NOAA HPSS but have not pre-staged the data, they can sim Users who do not have access to NOAA HPSS and do not have the data on their system will need to download :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data manually from collections of publicly available data, such as the ones listed `here `__. Next, the verification tasks must be turned on according to the user's needs. Users should add some or all of the following tasks to ``config.sh``, depending on the verification procedure(s) they have in mind: ->>>>>>> origin/develop .. code-block:: console @@ -850,11 +772,7 @@ Description of Workflow Tasks .. _WorkflowTasksFig: -<<<<<<< HEAD -.. figure:: _static/FV3LAM_wflow_flowchart_v2.svg -======= .. figure:: _static/FV3LAM_wflow_flowchart_v2.png ->>>>>>> origin/develop *Flowchart of the workflow tasks* @@ -903,16 +821,6 @@ In addition to the baseline tasks described in :numref:`Table %s >>>>>> origin/develop +-----------------------+------------------------------------------------------------+ | VX_GRIDSTAT | Runs METplus grid-to-grid verification for 1-h accumulated | | | precipitation | @@ -934,20 +841,9 @@ In addition to the baseline tasks described in :numref:`Table %s >>>>>> origin/develop +-----------------------+------------------------------------------------------------+ | VX_POINTSTAT | Runs METplus grid-to-point verification for surface and | | | upper-air variables | @@ -965,62 +861,16 @@ In addition to the baseline tasks described in :numref:`Table %s >>>>>> origin/develop +-----------------------+------------------------------------------------------------+ | VX_ENSGRID_MEAN | Runs METplus grid-to-grid verification for ensemble mean | | | 1-h accumulated precipitation. Can only be run if | | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | +-----------------------+------------------------------------------------------------+ -<<<<<<< HEAD - | VX_ENSGRID_PROB | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for 1-h accumulated precipitation. Can only | - | | be run if ``DO_ENSEMBLE="TRUE"`` and | - | | ``RUN_TASK_VX_ENSGRID="TRUE"``. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_MEAN_03h | Runs METplus grid-to-grid verification for ensemble mean | - | | 3-h accumulated precipitation. Can only be run if | - | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_03h | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for 3-h accumulated precipitation. Can only | - | | be run if ``DO_ENSEMBLE="TRUE"`` and | - | | ``RUN_TASK_VX_ENSGRID="TRUE"``. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_MEAN_06h | Runs METplus grid-to-grid verification for ensemble mean | - | | 6-h accumulated precipitation. Can only be run if | - | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_06h | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for 6-h accumulated precipitation. Can only | - | | be run if ``DO_ENSEMBLE="TRUE"`` and | - | | ``RUN_TASK_VX_ENSGRID="TRUE"``. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_MEAN_24h | Runs METplus grid-to-grid verification for ensemble mean | - | | daily accumulated precipitation. Can only be run if | - | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_24h | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for daily accumulated precipitation. Can | - | | only be run if ``DO_ENSEMBLE="TRUE"`` and | -======= | VX_ENSGRID_PROB | Runs METplus grid-to-grid verification for 1-h accumulated | | | precipitation probabilistic output. Can only be run if | | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | @@ -1035,7 +885,6 @@ In addition to the baseline tasks described in :numref:`Table %s >>>>>> origin/develop | | ``RUN_TASK_VX_ENSGRID="TRUE"``. | +-----------------------+------------------------------------------------------------+ | VX_ENSGRID_PROB_REFC | Runs METplus grid-to-grid verification for ensemble | @@ -1060,11 +909,6 @@ In addition to the baseline tasks described in :numref:`Table %s >>>>>> origin/develop .. _RocotoRun: @@ -1140,15 +984,9 @@ This will output the last 40 lines of the log file, which list the status of the Workflow status: IN PROGRESS If all the tasks complete successfully, the "Workflow status" at the bottom of the log file will change from "IN PROGRESS" to "SUCCESS". If certain tasks could not complete, the "Workflow status" will instead change to "FAILURE". Error messages for each specific task can be found in the task log files located in ``$EXPTDIR/log``. -<<<<<<< HEAD - -.. _Success: - -======= .. _Success: ->>>>>>> origin/develop The workflow run is complete when all tasks have "SUCCEEDED". If everything goes smoothly, users will eventually see a workflow status table similar to the following: .. code-block:: console diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index e7762c6767..236fa1f456 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -222,21 +222,13 @@ Those requirements highlighted in **bold** are included in the `HPC-Stack >>>>>> origin/develop * Software libraries * **netCDF (C and Fortran libraries)** * **HDF5** -<<<<<<< HEAD - * **ESMF** 8.0.2 -======= * **ESMF** 8.2.0 ->>>>>>> origin/develop * **Jasper** * **libJPG** * **libPNG** diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 83e50dcedb..c6e5d2f2af 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -6,7 +6,6 @@ Glossary .. glossary:: -<<<<<<< HEAD advect To transport substances in the atmostphere by :term:`advection`. @@ -16,12 +15,8 @@ Glossary CAPE Convective Available Potential Energy. - CCPA - Climatology-Calibrated Precipitation Analysis (CCPA) data. This data is required for use of the METplus verification suite within the SRW App. The most recent 8 days worth of data are publicly available and can be accessed `here `__. -======= CCPA Climatology-Calibrated Precipitation Analysis (CCPA) data. This data is required for METplus precipitation verification tasks within the SRW App. The most recent 8 days worth of data are publicly available and can be accessed `here `__. ->>>>>>> origin/develop CCPP The `Common Community Physics Package `_ is a forecast-model agnostic, vetted collection of codes containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model. @@ -70,12 +65,9 @@ Glossary echo top The radar-indicated top of an area of precipitation. Specifically, it contains the height of the 18 dBZ reflectivity value. -<<<<<<< HEAD EMC The `Environmental Modeling Center `__. -======= ->>>>>>> origin/develop EPIC EPIC stands for the `Earth Prediction Innovation Center `__. EPIC seeks to accelerate scientific research and modeling contributions through continuous and sustained community engagement to produce the most accurate and reliable operational modeling system in the world. @@ -125,11 +117,7 @@ Glossary MPI stands for Message Passing Interface. An MPI is a standardized communication system used in parallel programming. It establishes portable and efficient syntax for the exchange of messages and data between multiple processors that are used by a single computer program. An MPI is required for high-performance computing (HPC). MRMS -<<<<<<< HEAD - Multi-Radar/Multi-Sensor (MRMS) System Analysis data. This data is required for use of the METplus verification suite within the SRW App. A two-day archive of precipitation, radar, and aviation and severe weather fields is publicly available and can be accessed `here `__. -======= Multi-Radar/Multi-Sensor (MRMS) System Analysis data. This data is required for METplus composite reflectivity or :term:`echo top` verification tasks within the SRW App. A two-day archive of precipitation, radar, and aviation and severe weather fields is publicly available and can be accessed `here `__. ->>>>>>> origin/develop NAM `North American Mesoscale Forecast System `_. NAM generates multiple grids (or domains) of weather forecasts over the North American continent at various horizontal resolutions. Each grid contains data for dozens of weather parameters, including temperature, precipitation, lightning, and turbulent kinetic energy. NAM uses additional numerical weather models to generate high-resolution forecasts over fixed regions, and occasionally to follow significant weather events like hurricanes. @@ -157,11 +145,7 @@ Glossary visualization. Stands for NCAR Command Language. More information can be found at https://www.ncl.ucar.edu. NDAS -<<<<<<< HEAD - :term:`NAM` Data Assimilation System (NDAS) data. This data is required for use of the METplus verification suite within the SRW App. The most recent 1-2 days worth of data are publicly available in PrepBufr format and can be accessed `here `__. The most recent 8 days of data can be accessed `here `__. -======= :term:`NAM` Data Assimilation System (NDAS) data. This data is required for METplus surface and upper-air verification tasks within the SRW App. The most recent 1-2 days worth of data are publicly available in PrepBufr format and can be accessed `here `__. The most recent 8 days of data can be accessed `here `__. ->>>>>>> origin/develop NEMS The NOAA Environmental Modeling System is a common modeling framework whose purpose is diff --git a/docs/UsersGuide/source/WE2Etests.rst b/docs/UsersGuide/source/WE2Etests.rst index 9bf062bf10..56d026740b 100644 --- a/docs/UsersGuide/source/WE2Etests.rst +++ b/docs/UsersGuide/source/WE2Etests.rst @@ -1,8 +1,8 @@ .. _WE2E_tests: -================================ +================================== Workflow End-to-End (WE2E) Tests -================================ +================================== The SRW App contains a set of end-to-end tests that exercise the App in various configurations. These are referred to as workflow end-to-end (WE2E) tests because they all use the Rocoto workflow manager to run their individual workflows. @@ -35,9 +35,8 @@ where ``${test_name}`` is the name of the corresponding test. These configuration files are subsets of the full ``config.sh`` experiment configuration file used in :numref:`Section %s ` and described in :numref:`Section %s `. -For each test that the user wants -to run, the ``run_WE2E_tests.sh`` script reads in its configuration file and generates from -it a complete ``config.sh`` file. It then calls ``generate_FV3LAM_wflow.sh``, which in turn +For each test that the user wants to run, the ``run_WE2E_tests.sh`` script reads in its configuration file and generates from +it a complete ``config.sh`` file. It then calls ``generate_FV3LAM_wflow.sh``, which in turn reads in ``config.sh`` and generates a new experiment for the test. The name of each experiment directory is set to that of the corresponding test, and a copy of ``config.sh`` for each test is placed in its experiment directory. @@ -272,7 +271,7 @@ time it is run in a fresh git clone of the SRW App. Checking Test Status -==================== +====================== If cron jobs are being used to periodically relaunch the tests, the status of each test can be checked by viewing the end of the log file ``log.launch_FV3LAM_wflow`` (since the cron jobs use ``launch_FV3LAM_wflow.sh`` to relaunch the workflow, and @@ -336,7 +335,7 @@ The values that this can take on are "SUCCESS", "FAILURE", and "IN PROGRESS". Modifying the WE2E System -========================= +============================ This section describes various ways in which the WE2E testing system can be modified to suit specific testing needs. @@ -344,7 +343,7 @@ to suit specific testing needs. .. _ModExistingTest: Modifying an Existing Test ---------------------- +----------------------------- To modify an existing test, simply edit the configuration file for that test by changing existing variable values and/or adding new variables to suit the requirements of the modified test. Such a change may also require modifications to the test description @@ -372,7 +371,7 @@ above, say ``wflow_features``: .. _AddNewCategory: Adding a New WE2E Test Category ------------------------------ +----------------------------------- To create a new test category called, e.g. ``new_category``: 1) In the directory ``ufs-srweather-app/regional_workflow/tests/WE2E/test_configs``, @@ -399,7 +398,7 @@ New tests can now be added to ``new_category`` using the procedure described in .. _CreateAltTestNames: Creating Alternate Names for a Test ------------------------------------ +-------------------------------------- In order to prevent proliferation of WE2E tests, users might want to use the same test for multiple purposes. For example, consider the test From e866ccdf3dfa6033638b4b7c7e806993d2df8707 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 11 May 2022 19:30:25 -0400 Subject: [PATCH 134/158] I/O ch edits --- docs/UsersGuide/source/ConfigNewPlatform.rst | 2 +- docs/UsersGuide/source/ConfigWorkflow.rst | 5 +- docs/UsersGuide/source/Glossary.rst | 6 ++ docs/UsersGuide/source/InputOutputFiles.rst | 106 ++++++++++--------- docs/UsersGuide/source/LAMGrids.rst | 2 +- 5 files changed, 63 insertions(+), 58 deletions(-) diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index 236fa1f456..6d7cfd8e1e 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -168,7 +168,7 @@ For a detailed explanation of how to build and run the SRW App on any supported ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow -Optionally, users may `configure their own grid `, instead of using a predefined grid, and `plot the output ` of their experiment(s). +Optionally, users may :ref:`configure their own grid `, instead of using a predefined grid, and :ref:`plot the output ` of their experiment(s). Background Knowledge Prerequisites diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index adf2e54452..a513aadd9e 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -741,10 +741,7 @@ Write-Component (Quilting) Parameters .. attention:: The regional grid requires the use of the write component, so users generally should not need to change the default value for ``QUILTING``. - Flag that determines whether to use the write component for writing forecast output files to disk. If set to "TRUE", the forecast model will output files named ``dynf$HHH.nc`` and ``phyf$HHH.nc`` (where HHH is the 3-hour output forecast hour) containing dynamics and physics fields, respectively, on the write-component grid. (The regridding from the native FV3-LAM grid to the write-component grid is done by the forecast model.) If ``QUILTING`` is set to "FALSE", then the output file names are ``fv3_history.nc`` and ``fv3_history2d.nc``, and they contain fields on the native grid. Although the UFS Weather Model can run without quilting, the regional grid requires the use of the write component. Therefore, QUILTING should be set to "TRUE" when running the SRW App. If ``QUILTING`` is set to "FALSE", the ``RUN_POST_TN`` (meta)task cannot run because the :term:`UPP` code that this task calls cannot process fields on the native grid. In that case, the ``RUN_POST_TN`` (meta)task will be automatically removed from the Rocoto workflow XML. The :ref:`INLINE POST ` option also requires ``QUILTING`` to be set to "TRUE" in the SRW App. - -.. - COMMENT: Still don't undertand what HHH refers to... can we give an example? + Flag that determines whether to use the write component for writing forecast output files to disk. If set to "TRUE", the forecast model will output files named ``dynf$HHH.nc`` and ``phyf$HHH.nc`` (where HHH is the 3-digit forecast hour) containing dynamics and physics fields, respectively, on the write-component grid. For example, the output files for the 3rd hour of the forecast would be ``dynf$003.nc`` and ``phyf$003.nc``. (The regridding from the native FV3-LAM grid to the write-component grid is done by the forecast model.) If ``QUILTING`` is set to "FALSE", then the output file names are ``fv3_history.nc`` and ``fv3_history2d.nc``, and they contain fields on the native grid. Although the UFS Weather Model can run without quilting, the regional grid requires the use of the write component. Therefore, QUILTING should be set to "TRUE" when running the SRW App. If ``QUILTING`` is set to "FALSE", the ``RUN_POST_TN`` (meta)task cannot run because the :term:`UPP` code that this task calls cannot process fields on the native grid. In that case, the ``RUN_POST_TN`` (meta)task will be automatically removed from the Rocoto workflow XML. The :ref:`INLINE POST ` option also requires ``QUILTING`` to be set to "TRUE" in the SRW App. ``PRINT_ESMF``: (Default: "FALSE") Flag that determines whether to output extra (debugging) information from ESMF routines. Must be "TRUE" or "FALSE". Note that the write component uses ESMF library routines to interpolate from the native forecast model grid to the user-specified output grid (which is defined in the model configuration file ``model_configure`` in the forecast run directory). diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index c6e5d2f2af..34154fda30 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -98,18 +98,24 @@ Glossary 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. + HPSS + NOAA HPSS + National Oceanic and Atmospheric Administration (NOAA) High Performance Storage System (HPSS). + 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 Initial conditions/lateral boundary conditions + IC ICs Initial conditions LAM Limited Area Model, formerly known as the "Stand-Alone Regional Model," or SAR. LAM grids use a regional (rather than global) configuration of the FV3 dynamical core. + LBC LBCs Lateral boundary conditions diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 7dbe977941..f68bb0ba80 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -72,7 +72,7 @@ and are shown in :numref:`Table %s `. | | A different ``field_table`` may be needed for different | | | CCPP suites. | +-----------------------------+--------------------------------------------------------------+ - | FV3.input.yml | YAML configuration file containing the forecast model’s | + | FV3.input.yml | YAML configuration file containing the forecast model's | | | namelist settings for various physics suites. The values | | | specified in this file update the corresponding values in | | | the ``input.nml`` file. This file may be modified for the | @@ -98,7 +98,7 @@ and are shown in :numref:`Table %s `. +-----------------------------+--------------------------------------------------------------+ Additional information related to ``diag_table_[CCPP]``, ``field_table_[CCPP]``, ``input.nml.FV3``, ``model_conigure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, -while information on ``regional_grid.nml`` can be found in the `UFS_UTILS User’s Guide +while information on ``regional_grid.nml`` can be found in the `UFS_UTILS User's Guide `_. Migratory Route of the Input Files in the Workflow @@ -115,7 +115,7 @@ Migratory Route of the Input Files in the Workflow .. _OutputFiles: Output Files -============ +============== The location of the output files written to disk is within a subdirectory of the experiment directory, ``EXPTDIR/YYYYMMDDHH``, named based on the settings in ``config.sh``. @@ -133,32 +133,38 @@ experiment run directory ``EXPTDIR/YYYYMMDDHH/INPUT`` and consist of the followi * ``C403_grid.tile7.halo3.nc`` * ``gfs_bndy.tile7.000.nc`` * ``gfs_bndy.tile7.006.nc`` +* ``gfs_bndy.tile7.012.nc`` * ``gfs_ctrl.nc`` -* ``gfs_data.nc -> gfs_data.tile7.halo0.nc`` -* ``grid_spec.nc -> ../../grid/C403_mosaic.halo3.nc`` -* ``grid.tile7.halo4.nc -> ../../grid/C403_grid.tile7.halo4.nc`` -* ``oro_data.nc -> ../../orog/C403_oro_data.tile7.halo0.nc`` +* ``gfs_data.nc`` +* ``gfs_data.tile7.halo0.nc`` +* ``grid_spec.nc`` +* ``grid.tile7.halo4.nc`` +* ``oro_data.nc`` +* ``oro_data.tile7.halo4.nc`` * ``sfc_data.nc -> sfc_data.tile7.halo0.nc`` +* ``sfc_data.tile7.halo0.nc`` +* ``tmp_ICS`` +* ``tmp_LBCS`` -These output files are used as inputs for the UFS Weather Model, and are described in the `UFS Weather Model Users Guide +These output files are used as inputs for the UFS Weather Model, and are described in the `UFS Weather Model User's Guide `__. .. COMMENT: Change link above (structure of "latest" is significantly different) UFS Weather Model ------------------ -As stated in :numref:`Section %s `, the workflow can be run in ‘community’ or ‘nco’ mode, which determines the location and names of the output files. Weather Model output files can also be in :term:`netCDF` or :term:`NEMSIO` format. The output file format is set in the ``model_configure`` file (see :numref:`Table %s `) using the ``output_file`` variable. At this time, due to limitations in the post-processing component, only netCDF output is recommended for the SRW Application. +------------------ +As stated in :numref:`Section %s `, the workflow can be run in 'community' or 'nco' mode, which determines the location and names of the output files. Weather Model output files can also be in :term:`netCDF` or :term:`NEMSIO` format. The output file format is set in the ``model_configure`` file (see :numref:`Table %s `) using the ``output_file`` variable. At this time, due to limitations in the post-processing component, only netCDF output is recommended for the SRW Application. .. note:: - The fully supported options for this release include running in ‘community’ mode with netCDF-formatted output files. + The fully supported options for this release include running in 'community' mode with netCDF-formatted output files. In this case, the netCDF output files are written to the ``EXPTDIR/YYYYMMDDHH`` directory. The bases of the file names are specified in the input file ``model_configure`` and are set to the following in the SRW Application: * ``dynfHHH.nc`` * ``phyfHHH.nc`` -Additional details may be found in the `UFS Weather Model User's Guide +where HHH corresponds to the 3-digit forecast hour (e.g., ``dynf006.nc`` for the 6th hour of the forecast). Additional details may be found in the `UFS Weather Model User's Guide `__. @@ -173,7 +179,7 @@ For the SRW Application, the weather model netCDF output files are written to th The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by the user in the ``config.sh`` settings. -If users wish to modify the fields or levels that are output from the UPP, they will need to make modifications to file ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. Specifically, if the code was cloned in the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. +If users wish to modify the fields or levels that are output from the UPP, they will need to make modifications to ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. If the code was cloned into the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. .. note:: This process requires advanced knowledge of which fields can be output for the UFS Weather Model. @@ -182,7 +188,7 @@ UPP Product Output Tables for the UFS SRW LAM Grid: * :doc:`3D Native Hybrid Level Fields ` * :doc:`3D Pressure Level Fields ` -Use the directions in the `UPP User's Guide `__ for details on how to make modifications to the ``fv3lam.xml`` file and for remaking the flat text file that the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default). +Use the instructions in the `UPP User's Guide `__ to make modifications to the ``fv3lam.xml`` file and to remake the flat text file that the UPP reads, which is called ``postxconfig-NT-fv3lam.txt`` (default). Once you have created the new flat text file reflecting your changes, you will need to modify your ``config.sh`` to point the workflow to the new text file. In your ``config.sh``, set the following: @@ -192,7 +198,7 @@ Once you have created the new flat text file reflecting your changes, you will n USE_CUSTOM_POST_CONFIG_FILE=”TRUE” CUSTOM_POST_CONFIG_PATH=”” -which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If this is set to true and the file path is not found, then an error will occur when trying to generate the SRW Application workflow. +which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If this is set to true, and the file path is not found, then an error will occur when trying to generate the SRW Application workflow. Users may then start their experiment workflow as usual and the UPP will use the new flat ``*.txt`` file. @@ -200,21 +206,34 @@ Users may then start their experiment workflow as usual and the UPP will use the Downloading and Staging Input Data ================================== -A set of input files, including static (fix) data and raw initial and lateral boundary conditions (:term:`IC/LBC`'s), are needed to run the SRW Application. +A set of input files, including static (fix) data and raw initial and lateral boundary conditions (:term:`IC/LBC`'s), is required to run the SRW Application. The data required for the "out-of-the-box" SRW App case described in Chapters :numref:`%s ` and :numref:`%s ` is already preinstalled on `Level 1 & 2 `__ systems, along with data required to run the :ref:`WE2E ` test cases. These users do not need to stage the fixed files manually because they have been prestaged, and the paths are set in ``regional_workflow/ush/setup.sh``. + +Users on Level 3 & 4 systems can find the data required for the "out-of-the-box" SRW App case in the `UFS SRW App Data Bucket `__ by clicking on `Browse Bucket `__. In general, files required for a particular experiment must be downloaded individually. However, the input data required to run the default SRW App case from ``config.community.sh`` is available as a full tar file. To download the tar file: + +.. code-block:: console + + wget https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/fix/files.tar.gz + tar -xf files.tar.gz + +.. + COMMENT: Fix/update path to tar file! + .. _StaticFixFiles: Static Files ------------- -The environment variables ``FIXgsm``, ``TOPO_DIR``, and ``SFC_CLIMO_INPUT_DIR`` indicate the path to -the directories where the static files are located. If users are on a pre-configured or configurable platform (i.e., a Level 1 or 2 platform), there is no need to stage the fixed files manually because they have been prestaged, and the paths are set in ``regional_workflow/ush/setup.sh``. On Level 3 & 4 systems, the static files can be downloaded individually or as a full tar file from the `FTP data repository `__ or from `Amazon Web Services (AWS) cloud storage `__ using the ``wget`` command. Then the ``tar`` command will extract the compressed file: +-------------- + +To download the static files: .. code-block:: console - wget https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/fix/fix_files.tar.gz - tar -xf fix_files.tar.gz + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/ + +This will download *all* static files in the UFS SRW App Data Bucket. Users may adjust the path in the ``wget`` command to select the subset of files they need for their experiment. -The paths to the files must then be set in ``config.sh``. Add the following code or alter the variable paths if they are already listed in the ``config.sh`` file: +The environment variables ``FIXgsm``, ``TOPO_DIR``, and ``SFC_CLIMO_INPUT_DIR`` indicate the path to +the directories where the static files are located. After downloading the experiment data, users must set the paths to the files in ``config.sh``. Add the following code or alter the variable paths if they are already listed in the ``config.sh`` file: * ``FIXgsm="/path-to/fix/fix_am"`` * ``TOPO_DIR="/path-to/fix/fix_am/fix_orog"`` @@ -223,51 +242,34 @@ The paths to the files must then be set in ``config.sh``. Add the following code .. _InitialConditions: Initial Condition Formats and Source ------------------------------------- +--------------------------------------- The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. However, the SRW Application currently only supports the use of NEMSIO and netCDF input files from the GFS. .. COMMENT: So in reality, does this mean that only 2 formats are supported? -The data required to run the "out-of-the-box" SRW App case described in Chapters :numref:`%s ` and :numref:`%s ` is already preinstalled on `Level 1 `__ systems. Users on Level 3 & 4 systems can find the required IC/LBC data in the `FTP data repository `__ or on `AWS cloud storage `_. - -To add this data to your system, run the following commands from the ``ufs-srweather-app`` directory: +To download all available GRIB2 data for the FV3GFS model: .. code-block:: console - wget https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/simple_test_case/gst_model_data.tar.gz - tar -xf gst_model_data.tar.gz - -This will extract the files and place them within a new ``model_data`` directory inside the ``ufs-srweather-app``. + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/FV3GFS/grib2/ -Then, the paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` must be set in the ``config.sh`` file. +To download data for different models or in different formats, users can explore the data bucket and replace the link above with one that goes to their desired data. -.. code-block:: console - - cd - vi config.sh +Initial and Lateral Boundary Condition Organization +--------------------------------------------------- -Then, in ``config.sh``, set the following environment variables: +The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` must be set in the ``config.sh`` file as follows: .. code-block:: console USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="" - -These environment variables describe which :term:`IC/LBC` files to use (pre-staged files or files to be automatically pulled from NOAA HPSS) and the location of the IC/LBC files. ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` is the directory where the initial conditions are located, and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` is the directory where the lateral boundary conditions are located. - -Initial and Lateral Boundary Condition Organization ---------------------------------------------------- -The suggested directory structure and naming convention for the raw input files is described -below. While there is flexibility to modify these settings, this will provide the most reusability for multiple dates when using the SRW Application workflow. - -For ease of reusing the ``config.sh`` for multiple dates and cycles, it is recommended to set up the raw :term:`IC/LBC` files such that they includes the model name (e.g., FV3GFS, NAM, RAP, HRRR) and ``YYYYMMDDHH``, for example: ``/path-to/model_data/FV3GFS/2019061518``. Since both initial and lateral boundary condition files are necessary, you can also include an ICS and LBCS directory. The sample IC/LBC's available at the FTP data repository are structured as follows: + EXTRN_MDL_SOURCE_BASEDIR_ICS="" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="" -* ``/path-to/model_data/MODEL/YYYYMMDDHH/ICS`` -* ``/path-to/model_data/MODEL/YYYYMMDDHH/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) and date (in ``YYYYMMDDHH`` format). In addition, users can include separate ICS and LBCS directories. For example: ``/path-to/model_data/FV3GFS/2019061518/ICS`` and ``/path-to/model_data/FV3GFS/2019061518/LBCS``. 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 the NOAA HPSS, the naming convention looks something like: +When files are pulled from the NOAA :term:`HPSS` (rather than downloaded from the Data Bucket), the naming convention looks something like: * FV3GFS (GRIB2): ``gfs.t{cycle}z.pgrb2.0p25.f{fhr}`` * FV3GFS (NEMSIO): @@ -290,9 +292,9 @@ Doing this allows for the following to be set in the ``config.sh`` regardless of .. code-block:: console USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/path-to/model_data/HRRR" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/path-to/model_data/HRRR/YYYYMMDDHH/ICS" EXTRN_MDL_FILES_ICS=( "hrrr.wrfprsf00.grib2" ) - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/path-to/model_data/RAP" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/path-to/model_data/RAP/YYYYMMDDHH/LBCS" EXTRN_MDL_FILES_LBCS=( "rap.wrfprsf03.grib2" "rap.wrfprsf06.grib2" ) If you choose to forgo the extra ``ICS`` and ``LBCS`` directory, you may either diff --git a/docs/UsersGuide/source/LAMGrids.rst b/docs/UsersGuide/source/LAMGrids.rst index ffdb127f25..1d4070f751 100644 --- a/docs/UsersGuide/source/LAMGrids.rst +++ b/docs/UsersGuide/source/LAMGrids.rst @@ -111,7 +111,7 @@ However, for users who would like to use the 25-km domain for research, the ``FV Ultimately, the choice of grid is experiment-dependent and resource-dependent. For example, a user may wish to use the ``FV3_GFS_v16`` physics suite, which uses cumulus physics that are not configured to run at the 3-km resolution. In this case, the 13-km or 25-km domain options are better suited to the experiment. Users will also have fewer computational constraints when running with the 13-km and 25-km domains, so depending on the resources available to them, certain grids may be better options than others. -.. UserDefinedGrid: +.. _UserDefinedGrid: Creating User-Generated Grids =============================== From bc93840fddd65462e7a33f102938416c7e63e711 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 12 May 2022 15:15:51 -0400 Subject: [PATCH 135/158] I/O edits --- docs/UsersGuide/source/InputOutputFiles.rst | 40 +++++++++------------ 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index f68bb0ba80..eaf432b5e4 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -269,7 +269,7 @@ The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBC 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) and date (in ``YYYYMMDDHH`` format). In addition, users can include separate ICS and LBCS directories. For example: ``/path-to/model_data/FV3GFS/2019061518/ICS`` and ``/path-to/model_data/FV3GFS/2019061518/LBCS``. 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 the NOAA :term:`HPSS` (rather than downloaded from the Data Bucket), the naming convention looks something like: +When files are pulled from NOAA :term:`HPSS` (rather than downloaded from the data bucket), the naming convention looks something like: * FV3GFS (GRIB2): ``gfs.t{cycle}z.pgrb2.0p25.f{fhr}`` * FV3GFS (NEMSIO): @@ -278,6 +278,8 @@ When files are pulled from the NOAA :term:`HPSS` (rather than downloaded from th * RAP (GRIB2): ``rap.t{cycle}z.wrfprsf{fhr}.grib2`` * HRRR (GRIB2): ``hrrr.t{cycle}z.wrfprsf{fhr}.grib2`` +where {cycle} corresponds to the 2-digit hour of the day when the forecast cycle starts, and {fhr} corresponds to the nth hour of the forecast. For example, a forecast starting at 18h00 UTC would have a {cycle} value of 18, which is the 0th forecast hour. The LBCS file for 21h00 UTC would be named ``gfs.t18z.pgrb2.0p25.f03``. + In order to preserve the original file name, the ``f00`` files are placed in the ``ICS`` directory and all other forecast files are placed in the ``LBCS`` directory. Then, a symbolic link of the original files in the ``ICS/LBCS`` directory to the ``YYYYMMDDHH`` directory is suggested with @@ -292,12 +294,16 @@ Doing this allows for the following to be set in the ``config.sh`` regardless of .. code-block:: console USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/path-to/model_data/HRRR/YYYYMMDDHH/ICS" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/path-to/model_data/HRRR" EXTRN_MDL_FILES_ICS=( "hrrr.wrfprsf00.grib2" ) - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/path-to/model_data/RAP/YYYYMMDDHH/LBCS" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/path-to/model_data/RAP" EXTRN_MDL_FILES_LBCS=( "rap.wrfprsf03.grib2" "rap.wrfprsf06.grib2" ) -If you choose to forgo the extra ``ICS`` and ``LBCS`` directory, you may either +.. + COMMENT: Does this work anymore though? Thought we needed cycle data and ICS/LBCS. + COMMENT: Why do the ICS use HRRR, but the LBCS use RAP. Should they be the same? + +If users choose to forgo the extra ``ICS`` and ``LBCS`` directory, they may either rename the original files to remove the cycle or modify the ``config.sh`` to set: .. code-block:: console @@ -308,18 +314,16 @@ rename the original files to remove the cycle or modify the ``config.sh`` to set Default Initial and Lateral Boundary Conditions ----------------------------------------------- The default initial and lateral boundary condition files are set to be a severe weather case -from 20190615 at 00 UTC. FV3GFS GRIB2 files are the default model and file format. A tar file -(``gst_model_data.tar.gz``) containing the model data for this case is available on EMC's FTP -data repository at https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/simple_test_case/. It is -also available on Amazon Web Services (AWS) at https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/ic/gst_model_data.tar.gz. +from 20190615 at 18 UTC. FV3GFS GRIB2 files are the default model and file format. A tar file +(``gst_model_data.tar.gz``) containing the model data for this case is available in the `UFS SRW App Data Bucket `__. + +.. + COMMENT: Update tar file name later. Running the App for Different Dates ----------------------------------- -If users want to run the SRW Application for dates other than 06-15-2019, you will need to -make a change in the case to specify the desired data. This is done by modifying the -``config.sh`` ``DATE_FIRST_CYCL``, ``DATE_LAST_CYCL``, and ``CYCL_HRS`` settings. The -forecast length can be modified by changing the ``FCST_LEN_HRS``. In addition, the lateral -boundary interval can be specified using the ``LBC_SPEC_INTVL_HRS`` variable. +If users want to run the SRW Application for dates other than June 15-16, 2019, they will need to +make modify the ``config.sh`` settings, including the ``DATE_FIRST_CYCL``, ``DATE_LAST_CYCL``, and ``CYCL_HRS`` variables. The forecast length can be modified by changing the ``FCST_LEN_HRS``. In addition, the lateral boundary interval can be specified using the ``LBC_SPEC_INTVL_HRS`` variable. Users will need to ensure that the initial and lateral boundary condition files are available in the specified path for their new date, cycle, and forecast length. @@ -341,16 +345,6 @@ NOMADS: https://nomads.ncep.noaa.gov/pub/data/nccf/com/{model}/prod, where model * HRRR - available for the last 2 days https://nomads.ncep.noaa.gov/pub/data/nccf/com/hrrr/prod/ -NCDC archive: - -* GFS: https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/global-forcast-system-gfs -* NAM: https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/north-american-mesoscale-forecast-system-nam -* RAP: https://www.ncdc.noaa.gov/data-access/model-data/model-datasets/rapid-refresh-rap - -.. - COMMENT: These links don't work. Did they get moved? Or removed? - - AWS S3: * GFS: https://registry.opendata.aws/noaa-gfs-bdp-pds/ From 525dcb596eb3e8764f9b9cc388bdf4ec3fd2d350 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 12 May 2022 15:48:29 -0400 Subject: [PATCH 136/158] more I/O edits --- docs/UsersGuide/source/InputOutputFiles.rst | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index eaf432b5e4..992d7c88d6 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -243,10 +243,7 @@ the directories where the static files are located. After downloading the experi Initial Condition Formats and Source --------------------------------------- -The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. However, the SRW Application currently only supports the use of NEMSIO and netCDF input files from the GFS. - -.. - COMMENT: So in reality, does this mean that only 2 formats are supported? +The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. To download all available GRIB2 data for the FV3GFS model: @@ -289,7 +286,7 @@ the cycle removed. For example: ln -sf /path-to/model_data/RAP/2020041212/ICS/rap.t12z.wrfprsf00.grib2 /path-to/model_data/RAP/2020041212/rap.wrfprsf00.grib2 -Doing this allows for the following to be set in the ``config.sh`` regardless of what cycle you are running: +Linking the files like this removes the cycle-dependent part of the file names so that each cycle will use the same file name, regardless of initialization time. This allows for the following to be set in the ``config.sh`` regardless of what cycle you are running: .. code-block:: console @@ -299,10 +296,6 @@ Doing this allows for the following to be set in the ``config.sh`` regardless of EXTRN_MDL_SOURCE_BASEDIR_LBCS="/path-to/model_data/RAP" EXTRN_MDL_FILES_LBCS=( "rap.wrfprsf03.grib2" "rap.wrfprsf06.grib2" ) -.. - COMMENT: Does this work anymore though? Thought we needed cycle data and ICS/LBCS. - COMMENT: Why do the ICS use HRRR, but the LBCS use RAP. Should they be the same? - If users choose to forgo the extra ``ICS`` and ``LBCS`` directory, they may either rename the original files to remove the cycle or modify the ``config.sh`` to set: @@ -354,6 +347,10 @@ Google Cloud: * HRRR: https://console.cloud.google.com/marketplace/product/noaa-public/hrrr +FTP Data Repository: (data for SRW Release 1.0.0 & 1.0.1) +* https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/fix/ +* https://ftp.emc.ncep.noaa.gov/EIB/UFS/SRW/v1p0/simple_test_case/ + Others: * Univ. of Utah HRRR archive: http://home.chpc.utah.edu/~u0553130/Brian_Blaylock/cgi-bin/hrrr_download.cgi @@ -386,7 +383,7 @@ are initializing from NEMSIO format FV3GFS files. Best Practices for Conserving Disk Space and Keeping Files Safe --------------------------------------------------------------- Initial and lateral boundary condition files are large and can occupy a significant amount of -disk space. If various users will employ a common file system to conduct runs, it is recommended +disk space. If several users will employ a common file system to run forecasts, it is recommended that the users share the same ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` directories. That way, if raw model input files are already on disk for a given date they do not need to be replicated. From 4a4642d763b0fab5a8fb19746d9ec6865fcb06e3 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 12 May 2022 15:53:29 -0400 Subject: [PATCH 137/158] hpc-stack submodule updates --- hpc-stack-mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hpc-stack-mod b/hpc-stack-mod index 9fbcb9e3c8..dd5f1f53e5 160000 --- a/hpc-stack-mod +++ b/hpc-stack-mod @@ -1 +1 @@ -Subproject commit 9fbcb9e3c82196fdc9d3b324d5dfc537620ea97e +Subproject commit dd5f1f53e5babe7b786c72a75e8898fb0debe78c From 1871716867e165ea1d0a3e944d50727266b67f32 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 12 May 2022 16:11:31 -0400 Subject: [PATCH 138/158] add HPC-Stack MacOs info --- docs/UsersGuide/source/Include-HPCInstall.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/UsersGuide/source/Include-HPCInstall.rst b/docs/UsersGuide/source/Include-HPCInstall.rst index b467d96d23..e9d5e2d482 100644 --- a/docs/UsersGuide/source/Include-HPCInstall.rst +++ b/docs/UsersGuide/source/Include-HPCInstall.rst @@ -1,6 +1,7 @@ .. _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 From 6a49c8db31fa02a1680ed54c2b821a1a41fb28a5 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 12 May 2022 23:34:31 -0400 Subject: [PATCH 139/158] WE2E edits & tables --- docs/UsersGuide/source/CompleteTests.csv | 28 ++ docs/UsersGuide/source/CompleteTests.rst | 8 + docs/UsersGuide/source/WE2Etests.rst | 344 ++++++++---------- .../source/_static/theme_overrides.css | 8 +- 4 files changed, 185 insertions(+), 203 deletions(-) create mode 100644 docs/UsersGuide/source/CompleteTests.csv create mode 100644 docs/UsersGuide/source/CompleteTests.rst diff --git a/docs/UsersGuide/source/CompleteTests.csv b/docs/UsersGuide/source/CompleteTests.csv new file mode 100644 index 0000000000..28cc46162f --- /dev/null +++ b/docs/UsersGuide/source/CompleteTests.csv @@ -0,0 +1,28 @@ +Grid,ICS,LBCS,Suite,Date,Time (UTC),Script Name,Test Type +RRFS_CONUS_3km,FV3GFS,FV3GFS,GFS_v16,2019-07-01,00,config.grid_RRFS_CONUS_3km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh,Complete +RRFS_CONUS_25km,HRRR,RAP,RRFS_v1beta,2020-08-10,00,config.grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_RAP_suite_HRRR.sh,Complete +RRFS_CONUS_13km,HRRR,RAP,RRFS_v1beta,2020-08-01,00,config.grid_RRFS_CONUScompact_13km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta.sh,Complete +RRFS_CONUS_3km,HRRR,RAP,RRFS_v1beta,2020-08-01,00,config.grid_RRFS_CONUScompact_3km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta.sh,Complete +RRFS_CONUS_25km,HRRR,RAP,HRRR,2020-08-10,00,config.grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_RAP_suite_HRRR.sh,Complete +RRFS_CONUS_13km,HRRR,RAP,HRRR,2020-08-10,00,config.grid_RRFS_CONUScompact_13km_ics_HRRR_lbcs_RAP_suite_HRRR.sh,Complete +RRFS_CONUS_3km,HRRR,RAP,HRRR,2020-08-10,00,config.grid_RRFS_CONUScompact_3km_ics_HRRR_lbcs_RAP_suite_HRRR.sh,Complete +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_2017_gfdlmp,2019-07-01,"00,12",config.community_ensemble_008mems.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_2017_gfdlmp,2019-07-01,"00,12",config.community_ensemble_2mems.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_2017_gfdlmp,2019-07-02,"00,12",config.community_ensemble_008mems.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_2017_gfdlmp,2019-07-02,"00,12",config.community_ensemble_2mems.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_v15p2,2019-07-01,00,config.deactivate_tasks.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_v15p2,2019-07-01,00,config.inline_post.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_v15p2,2019-06-15,00,config.MET_ensemble_verification.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_v15p2,2019-06-15,00,config.MET_verification.sh,Complete/wflow +ESGgrid,FV3GFS,FV3GFS,FV3_GFS_2017_gfdlmp_regional,2019-07-01,00,config.new_ESGgrid.sh,Complete/wflow +GFDLgrid,FV3GFS,FV3GFS,FV3_GFS_2017_gfdlmp,2019-07-01,00,config.new_GFDLgrid.sh,Complete/wflow +GFDLgrid,FV3GFS,FV3GFS,FV3_GFS_2017_gfdlmp,2019-07-01,00,config.new_GFDLgrid__GFDLgrid_USE_GFDLgrid_RES_IN_FILENAMES_eq_FALSE.sh,Complete/wflow +GFDLgrid,FV3GFS,FV3GFS,FV3_GFS_2017_gfdlmp,2019-07-01,00,config.new_GFDLgrid__GFDLgrid_USE_GFDLgrid_RES_IN_FILENAMES_eq_TRUE.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_v15p2,2019-07-01,00,config.pregen_grid_orog_sfc_climo.sh,Complete/wflow +RRFS_CONUS_25km,GSMGFS,GSMGFS,FV3_GFS_2017_gfdlmp,2019-05-20,00,config.specify_DOT_OR_USCORE.sh,Complete/wflow +RRFS_CONUScompact_25km,HRRR,RAP,FV3_HRRR,2020-08-01,00,config.specify_DT_ATMOS_LAYOUT_XY_BLOCKSIZE.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_v15p2,2021-06-03,06,config.specify_EXTRN_MDL_SYSBASEDIR_ICS_LBCS.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_v15p2,2019-07-01,00,config.specify_RESTART_INTERVAL.sh,Complete/wflow +RRFS_CONUScompact_25km,HRRR,RAP,FV3_RRFS_v1beta,2020-08-10,00,config.subhourly_post_ensemble_2mems.sh,Complete/wflow +RRFS_CONUScompact_25km,HRRR,RAP,FV3_RRFS_v1beta,2020-08-10,00,config.subhourly_post.sh,Complete/wflow +RRFS_CONUS_25km,FV3GFS,FV3GFS,FV3_GFS_v15p2,2019-07-01,00,config.specify_template_filenames.sh,Complete/wflow \ No newline at end of file diff --git a/docs/UsersGuide/source/CompleteTests.rst b/docs/UsersGuide/source/CompleteTests.rst new file mode 100644 index 0000000000..50cf6f69fb --- /dev/null +++ b/docs/UsersGuide/source/CompleteTests.rst @@ -0,0 +1,8 @@ +************************************************************ +Complete WE2E Tests +************************************************************ + +.. csv-table:: + :file: CompleteTests.csv + :widths: 20,20,20,20,20,20,20,20 + :header-rows: 1 diff --git a/docs/UsersGuide/source/WE2Etests.rst b/docs/UsersGuide/source/WE2Etests.rst index 56d026740b..945da6050e 100644 --- a/docs/UsersGuide/source/WE2Etests.rst +++ b/docs/UsersGuide/source/WE2Etests.rst @@ -3,209 +3,177 @@ ================================== Workflow End-to-End (WE2E) Tests ================================== -The SRW App contains a set of end-to-end tests that exercise the App in various configurations. -These are referred to as workflow end-to-end (WE2E) tests because they all use the Rocoto -workflow manager to run their individual workflows. -The purpose of these tests is to -ensure that new changes to the App do not break existing functionality and capabilities. - - -Note that the WE2E tests are not regression tests, i.e. they do not check whether -current results are identical to previously established baselines. They are also -not tests of the scientific integrity of the results, e.g. they do not check that values -of output fields are reasonable. -These tests only check that the tasks within each test's workflow complete -successfully. -They are in essence tests of the workflow generation, task execution (j-jobs, +The SRW App contains a set of end-to-end tests that exercise various workflow configurations of the SRW App. These are referred to as workflow end-to-end (WE2E) tests because they all use the Rocoto +workflow manager to run their individual workflows. The purpose of these tests is to +ensure that new changes to the App do not break existing functionality and capabilities. + +Note that the WE2E tests are not regression tests---they do not check whether +current results are identical to previously established baselines. They also do +not test the scientific integrity of the results (e.g., they do not check that values +of output fields are reasonable). These tests only check that the tasks within each test's workflow complete successfully. They are, in essence, tests of the workflow generation, task execution (j-jobs, ex-scripts), and other auxiliary scripts (which are mostly in the ``regional_workflow`` -repo) to ensure that these scripts are correctly performing their functions. These functions +repository) to ensure that these scripts function correctly. These functions include creating and correctly arranging and naming directories and files, ensuring -that all input files are available and readable, calling -executables with correct namelists and/or options, etc. -For the time being, it is up to the external repositories that the App clones (:numref:`Section %s `) -to check that changes to those repos do not change results, or, if they do, to ensure that the new -results are acceptable. -(At least two of these external repositories --- ``UFS_UTILS`` and ``ufs-weather-model`` --- -do have such regression tests.) - -The script to run all or a subset of the WE2E tests is named ``run_WE2E_tests.sh`` and is located in the directory -``ufs-srweather-app/regional_workflow/tests/WE2E``. -Each WE2E test has associated with it a configuration file named ``config.${test_name}.sh``, -where ``${test_name}`` is the name of the corresponding test. -These configuration files are subsets of -the full ``config.sh`` experiment configuration file used in :numref:`Section %s ` -and described in :numref:`Section %s `. -For each test that the user wants to run, the ``run_WE2E_tests.sh`` script reads in its configuration file and generates from -it a complete ``config.sh`` file. It then calls ``generate_FV3LAM_wflow.sh``, which in turn -reads in ``config.sh`` and generates a new experiment for the test. -The name of each experiment directory is set to that of the corresponding test, -and a copy of ``config.sh`` for each test is placed in its experiment directory. +that all input files are available and readable, calling executables with correct namelists and/or options, etc. Currently, it is up to the external repositories that the App clones (:numref:`Section %s `) to check that changes to those repos do not change results, or, if they do, to ensure that the new results are acceptable. (At least two of these external repositories---``UFS_UTILS`` and ``ufs-weather-model``---do have such regression tests.) For convenience, the WE2E tests are currently grouped into the following categories: * ``grids_extrn_mdls_suites_community`` - - This category of tests ensures that the SRW App workflow running in **community mode** - (i.e. with ``RUN_ENVIR`` set to ``"community"``) completes successfully for various - combinations of predefined grids, physics suites, and external models for ICs and LBCs. - Note that in community mode, all output from the App is placed under a single experiment - directory. + This category of tests ensures that the SRW App workflow running in **community mode** (i.e. with ``RUN_ENVIR`` set to ``"community"``) completes successfully for various combinations of predefined grids, physics suites, and external models for ICs and LBCs. Note that in community mode, all output from the App is placed under a single experiment directory. * ``grids_extrn_mdls_suites_nco`` - - This category of tests ensures that the workflow running in **NCO mode** - (i.e. with ``RUN_ENVIR`` set to ``"nco"``) completes successfully for various combinations - of predefined grids, physics suites, and external models for ICs and LBCs. Note that - in NCO mode, an operational run environment (i.e. variable names) is used along with - a directory structure in which output is placed in multiple directories (see - Sections :numref:`%s ` and :numref:`%s `). + This category of tests ensures that the workflow running in **NCO mode** (i.e. with ``RUN_ENVIR`` set to ``"nco"``) completes successfully for various combinations of predefined grids, physics suites, and external models for ICs and LBCs. Note that in NCO mode, an operational run environment (i.e. variable names) is used along with a directory structure in which output is placed in multiple directories (see + Sections :numref:`%s ` and :numref:`%s `). * ``wflow_features`` - This category of tests ensures that the workflow with various features/capabilities activated - completes successfully. To reduce computational cost, most tests in this category - use coarser grids. + This category of tests ensures that the workflow with various features/capabilities activated + completes successfully. To reduce computational cost, most tests in this category use coarser grids. -The test configuration files for these categories are located in the following directories, -respectively: +The test configuration files for these categories are located in the following directories, respectively: .. code-block:: - ufs-srweather-app/regional_workflow/tests/WE2E/test_configs/grids_extrn_mdls_suites_community - ufs-srweather-app/regional_workflow/tests/WE2E/test_configs/grids_extrn_mdls_suites_nco - ufs-srweather-app/regional_workflow/tests/WE2E/test_configs/wflow_features + ufs-srweather-app/regional_workflow/tests/WE2E/test_configs/grids_extrn_mdls_suites_community + ufs-srweather-app/regional_workflow/tests/WE2E/test_configs/grids_extrn_mdls_suites_nco + ufs-srweather-app/regional_workflow/tests/WE2E/test_configs/wflow_features + +The script to run the WE2E tests is named ``run_WE2E_tests.sh`` and is located in the directory ``ufs-srweather-app/regional_workflow/tests/WE2E``. Each WE2E test has an associated configuration file named ``config.${test_name}.sh``, where ``${test_name}`` is the name of the corresponding test. These configuration files are subsets of the full ``config.sh`` experiment configuration file used in :numref:`Section %s ` and described in :numref:`Section %s `. For each test, the ``run_WE2E_tests.sh`` script reads in its configuration file and generates from it a complete ``config.sh`` file. It then calls ``generate_FV3LAM_wflow.sh``, which in turn reads in ``config.sh`` and generates a new experiment for the test. The name of each experiment directory is set to that of the corresponding test, and a copy of ``config.sh`` for each test is placed in its experiment directory. Since ``run_WE2E_tests.sh`` calls ``generate_FV3LAM_wflow.sh`` for each test, the Python modules required for experiment generation must be loaded before ``run_WE2E_tests.sh`` -can be called. See :numref:`Section %s ` for information on loading the Python -environment on supported platforms. Note also that ``run_WE2E_tests.sh`` assumes that all of -the executables have been built. If they have not, then ``run_WE2E_tests.sh`` will still +can be called. See :numref:`Section %s ` for information on loading the Python +environment on supported platforms. Note also that ``run_WE2E_tests.sh`` assumes that all of +the executables have been built. If they have not, then ``run_WE2E_tests.sh`` will still generate the experiment directories, but the workflows will fail. +Supported Tests +=================== + +The full list of WE2E tests is extensive; it is not recommended to run all of the tests, as some are computationally expensive. A subset of the tests are supported for the latest release of the SRW Application`. Frequent test cases appear in :numref:`Table %s ` below, and complete test cases appear :doc:`here `. Frequent tests are a lightweight set of tests that can be automated and run regularly on each Level 1 platform. These tests and cover a wide scope of capabilities to ensure that there are no major, obvious faults in the underlying code. Complete tests include the remainder of the supported WE2E tests and cover a fuller list of workflow configurations. + +.. + COMMENT: Add file w/supported tests to repo + COMMENT: Contrib Guide says that "Fundamental testing consists of a lightweight set of tests that can be automated and run regularly on each Level 1 platform. These are mostly low-resolution tests and cover a wide scope of capabilities to ensure that there are no major, obvious faults in the underlying code. Comprehensive testing includes the entire set of WE2E tests." How would we define frequent v complete? + +.. _FrequentTests: + +.. table:: Frequent Test Cases (Supported) + + +------------------+--------+--------+---------------+--------------+---------------------------------------------------------------------+ + | Grid | ICs | LBCs | Physics Suite | Dataset Used | Script Name | + +==================+========+========+===============+==============+=====================================================================+ + | CONUS_25km | FV3GFS | FV3GFS | GFS_v16 | 2019-07-01 | config.grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh | + +------------------+--------+--------+---------------+--------------+---------------------------------------------------------------------+ + | CONUS_13km | FV3GFS | FV3GFS | GFS_v16 | 2019-07-01 | config.grid_RRFS_CONUS_13km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh | + +------------------+--------+--------+---------------+--------------+---------------------------------------------------------------------+ + | INDIANAPOLIS_3km | FV3GFS | FV3GFS | GFS_v16 | 2019-06-15 | config.SUBCONUS_Ind_3km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh | + +------------------+--------+--------+---------------+--------------+---------------------------------------------------------------------+ + | INDIANAPOLIS_3km | HRRR | RAP | RRFS_v1beta | 2019-06-15 | config.SUBCONUS_Ind_3km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta.sh | + +------------------+--------+--------+---------------+--------------+---------------------------------------------------------------------+ + | INDIANAPOLIS_3km | HRRR | RAP | HRRR | 2019-06-15 | config.SUBCONUS_Ind_3km_ics_HRRR_lbcs_RAP_suite_HRRR.sh | + +------------------+--------+--------+---------------+--------------+---------------------------------------------------------------------+ + | INDIANAPOLIS_3km | HRRR | RAP | WoFS | 2019-06-15 | config.SUBCONUS_Ind_3km_ics_HRRR_lbcs_RAP_suite_WoFS.sh | + +------------------+--------+--------+---------------+--------------+---------------------------------------------------------------------+ + Running the WE2E Tests ================================ -The user specifies the set of tests that ``run_WE2E_tests.sh`` will run by creating a text -file, say ``my_tests.txt``, that contains a list of the WE2E tests to run (one per line) -and passing the name of that file to ``run_WE2E_tests.sh``. For example, if the user -wants to run the tests ``new_ESGgrid`` and ``grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16`` -(from the ``wflow_features`` and ``grids_extrn_mdls_suites_community`` categories, respectively), we would have: +Users may specify the set of tests to run by creating a text file, such as ``my_tests.txt``, which contains a list of the WE2E tests to run (one per line). Then, they pass the name of that file to ``run_WE2E_tests.sh``. For example, to run the tests ``new_ESGgrid`` and ``grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16`` (from the ``wflow_features`` and ``grids_extrn_mdls_suites_community`` categories, respectively), users would enter the following: .. code-block:: console - > cat my_tests.txt - new_ESGgrid - grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 + > cat my_tests.txt + new_ESGgrid + grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 -For each test in ``my_tests.txt``, ``run_WE2E_tests.sh`` -will generate a new experiment directory and, by default, create a new cron job in the user's cron -table that will (re)launch the workflow every 2 minutes. This cron job calls the workflow launch script -``launch_FV3LAM_wflow.sh`` located in the experiment directory until the workflow either -completes successfully (i.e. all tasks are successful) or fails (i.e. at least one task fails). +For each test in ``my_tests.txt``, ``run_WE2E_tests.sh`` will generate a new experiment directory and, by default, create a new cron job in the user's cron table that will (re)launch the workflow every 2 minutes. This cron job calls the workflow launch script ``launch_FV3LAM_wflow.sh`` until the workflow either completes successfully (i.e., all tasks are successful) or fails (i.e., at least one task fails). The cron job is then removed from the user's cron table. -Next, we show several common ways that ``run_WE2E_tests.sh`` can be called with -the ``my_tests.txt`` file above. +The examples below demonstrate several common ways that ``run_WE2E_tests.sh`` can be called with the ``my_tests.txt`` file above. -1) To run the tests listed in ``my_tests.txt`` on Hera and charge the computational +#. To run the tests listed in ``my_tests.txt`` on Hera and charge the computational resources used to the "rtrr" account, use: .. code-block:: - > run_WE2E_tests.sh tests_file="my_tests.txt" machine="hera" account="rtrr" - - This will create the experiment subdirectories for the two tests in - the directory - - .. code-block:: - - ${SR_WX_APP_TOP_DIR}/../expt_dirs + > run_WE2E_tests.sh tests_file="my_tests.txt" machine="hera" account="rtrr" - where ``SR_WX_APP_TOP_DIR`` is the directory in which the ufs-srweather-app - repository is cloned (usually set to something like ``/path/to/ufs-srweather-app``). + This will create the experiment subdirectories for the two sample WE2E tests in the directory ``${SR_WX_APP_TOP_DIR}/../expt_dirs``, where ``SR_WX_APP_TOP_DIR`` is the directory in which the ufs-srweather-app repository is cloned (usually set to something like ``/path/to/ufs-srweather-app``). Thus, the following two experiment directories will be created: .. code-block:: - ${SR_WX_APP_TOP_DIR}/../expt_dirs/new_ESGgrid - ${SR_WX_APP_TOP_DIR}/../expt_dirs/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 + ${SR_WX_APP_TOP_DIR}/../expt_dirs/new_ESGgrid + ${SR_WX_APP_TOP_DIR}/../expt_dirs/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - In addition, by default, cron jobs will be added to the user's cron - table to relaunch the workflows of these experiments every 2 minutes. + In addition, by default, cron jobs will be added to the user's cron table to relaunch the workflows of these experiments every 2 minutes. -2) To change the frequency with which the cron relaunch jobs are submitted +#. To change the frequency with which the cron relaunch jobs are submitted from the default of 2 minutes to 1 minute, use: .. code-block:: - > run_WE2E_tests.sh tests_file="my_tests.txt" machine="hera" account="rtrr" cron_relaunch_intvl_mnts="01" + > run_WE2E_tests.sh tests_file="my_tests.txt" machine="hera" account="rtrr" cron_relaunch_intvl_mnts="01" -3) To disable use of cron (which implies the worfkow for each test will - have to be relaunched manually from within each experiment directory), - use: +#. To disable use of cron (which implies the worfkow for each test will have to be relaunched manually from within each experiment directory), use: .. code-block:: - > run_WE2E_tests.sh tests_file="my_tests.txt" machine="hera" account="rtrr" use_cron_to_relaunch="FALSE" + > run_WE2E_tests.sh tests_file="my_tests.txt" machine="hera" account="rtrr" use_cron_to_relaunch="FALSE" - In this case, the user will have to go into each test's experiment directory and - either manually call the ``launch_FV3LAM_wflow.sh`` script or use the Rocoto commands described - in :numref:`Chapter %s ` to (re)launch the workflow. Note that if using the Rocoto - commands directly, the log file ``log.launch_FV3LAM_wflow`` will not be created; in this case, - the status of the workflow can be checked using the ``rocotostat`` command (see :numref:`Chapter %s `). + In this case, the user will have to go into each test's experiment directory and either manually call the ``launch_FV3LAM_wflow.sh`` script or use the Rocoto commands described in :numref:`Chapter %s ` to (re)launch the workflow. Note that if using the Rocoto commands directly, the log file ``log.launch_FV3LAM_wflow`` will not be created; in this case, the status of the workflow can be checked using the ``rocotostat`` command (see :numref:`Chapter %s `). -4) To place the experiment subdirectories in a subdirectory named ``test_set_01`` under +#. To place the experiment subdirectories in a subdirectory named ``test_set_01`` under ``${SR_WX_APP_TOP_DIR}/../expt_dirs`` (instead of immediately under the latter), use: .. code-block:: - > run_WE2E_tests.sh tests_file="my_tests.txt" machine="hera" account="rtrr" expt_basedir="test_set_01" + > run_WE2E_tests.sh tests_file="my_tests.txt" machine="hera" account="rtrr" expt_basedir="test_set_01" In this case, the full paths to the experiment directories will be: .. code-block:: - ${SR_WX_APP_TOP_DIR}/../expt_dirs/test_set_01/new_ESGgrid - ${SR_WX_APP_TOP_DIR}/../expt_dirs/test_set_01/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 + ${SR_WX_APP_TOP_DIR}/../expt_dirs/test_set_01/new_ESGgrid + ${SR_WX_APP_TOP_DIR}/../expt_dirs/test_set_01/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 This is useful for grouping various sets of tests. -5) To use a test list file (again named ``my_tests.txt``) located in ``/path/to/custom/location`` - instead of in the same directory as ``run_WE2E_tests.sh``, and to have the experiment directories - be placed in an arbitrary location, say ``/path/to/custom/expt_dirs``, use: +#. To use a test list file (again named ``my_tests.txt``) located in ``/path/to/custom/location`` instead of in the same directory as ``run_WE2E_tests.sh``, and to have the experiment directories be placed in an arbitrary location, say ``/path/to/custom/expt_dirs``, use: .. code-block:: - > run_WE2E_tests.sh tests_file="/path/to/custom/location/my_tests.txt" machine="hera" account="rtrr" expt_basedir="/path/to/custom/expt_dirs" + > run_WE2E_tests.sh tests_file="/path/to/custom/location/my_tests.txt" machine="hera" account="rtrr" expt_basedir="/path/to/custom/expt_dirs" The full usage statement for ``run_WE2E_tests.sh`` is as follows: .. code-block:: - run_WE2E_tests.sh \ - tests_file="..." \ - machine="..." \ - account="..." \ - [expt_basedir="..."] \ - [exec_subdir="..."] \ - [use_cron_to_relaunch="..."] \ - [cron_relaunch_intvl_mnts="..."] \ - [verbose="..."] \ - [machine_file="..."] \ - [stmp="..."] \ - [ptmp="..."] \ - [compiler="..."] \ - [build_env_fn="..."] - -The arguments in brackets are optional. A complete description of these arguments can be + run_WE2E_tests.sh \ + tests_file="..." \ + machine="..." \ + account="..." \ + [expt_basedir="..."] \ + [exec_subdir="..."] \ + [use_cron_to_relaunch="..."] \ + [cron_relaunch_intvl_mnts="..."] \ + [verbose="..."] \ + [machine_file="..."] \ + [stmp="..."] \ + [ptmp="..."] \ + [compiler="..."] \ + [build_env_fn="..."] + +The arguments in brackets are optional. A complete description of these arguments can be obtained by issuing .. code-block:: - run_WE2E_tests.sh --help + run_WE2E_tests.sh --help in the directory ``ufs-srweather-app/regional_workflow/tests/WE2E``. @@ -218,11 +186,10 @@ In addition to creating the WE2E tests' experiment directories and optionally cr cron jobs to launch their workflows, the ``run_WE2E_tests.sh`` script generates (if necessary) a CSV (Comma-Separated Value) file named ``WE2E_test_info.csv`` that contains information on the full set of WE2E tests. This file serves as a single location where relevant -information about the WE2E tests can be found. It can be imported into Google Sheets -using the "|" (pipe symbol) character as the custom field separator. The rows of the +information about the WE2E tests can be found. It can be imported into Google Sheets +using the "|" (pipe symbol) character as the custom field separator. The rows of the file/sheet represent the full set of available tests (not just the ones to be run), -while the columns contain the following information (column titles are included in the -CSV file): +while the columns contain the following information (column titles are included in the CSV file): | Column 1: | The primary test name and (in parentheses) the category subdirectory it is @@ -237,14 +204,14 @@ CSV file): | Column 4: | The number of times the forecast model will be run by the test. This gives an idea - of how expensive the test is. It is calculated using quantities such as the number + of how expensive the test is. It is calculated using quantities such as the number of cycle dates (i.e. forecast model start dates) and the number of of ensemble members - (if running ensemble forecasts). The are in turn obtained directly or indirectly + (if running ensemble forecasts). The are in turn obtained directly or indirectly from the quantities in Columns 5, 6, .... | Columns 5,6,...: | The values of various experiment variables (if defined) in each test's configuration - file. Currently, the following experiment variables are included: + file. Currently, the following experiment variables are included: | ``PREDEF_GRID_NAME`` | ``CCPP_PHYS_SUITE`` @@ -261,38 +228,30 @@ CSV file): Additional fields (columns) will likely be added to the CSV file in the near future. Note that the CSV file is not part of the ``regional_workflow`` repo (i.e. it is -not tracked by the repo). The ``run_WE2E_tests.sh`` script will generate a CSV +not tracked by the repo). The ``run_WE2E_tests.sh`` script will generate a CSV file if (1) the CSV file doesn't already exist, or (2) the CSV file does exist -but changes have been made to one or more of the category subdirectories (e.g. +but changes have been made to one or more of the category subdirectories (e.g., test configuration files modified, added, or deleted) since the creation of the -CSV file. Thus, ``run_WE2E_tests.sh`` will always create a CSV file the first +CSV file. Thus, ``run_WE2E_tests.sh`` will always create a CSV file the first time it is run in a fresh git clone of the SRW App. - Checking Test Status ====================== -If cron jobs are being used to periodically relaunch the tests, the status of -each test can be checked by viewing the end of the log file ``log.launch_FV3LAM_wflow`` -(since the cron jobs use ``launch_FV3LAM_wflow.sh`` to relaunch the workflow, and -that in turn generates the log files). Otherwise (or alternatively), the ``rocotorun``/``rocotostat`` -combination of commands can be used. See :numref:`Section %s ` for -details. - -The App also provides the script ``get_expts_status.sh`` in the directory -``ufs-srweather-app/regional_workflow/tests/WE2E`` that can be used to generate -a status summary for all tests in a given base directory. This script updates +If cron jobs are used to periodically relaunch the tests, the status of each test can be checked by viewing the end of the log file ``log.launch_FV3LAM_wflow`` (since the cron jobs use ``launch_FV3LAM_wflow.sh`` to relaunch the workflow, and that in turn generates the log files). Otherwise (or alternatively), the ``rocotorun``/``rocotostat`` combination of commands can be used. See :numref:`Section %s ` for details. + +The SRW App also provides the script ``get_expts_status.sh`` in the directory +``ufs-srweather-app/regional_workflow/tests/WE2E``, which can be used to generate +a status summary for all tests in a given base directory. This script updates the workflow status of each test (by internally calling ``launch_FV3LAM_wflow.sh``) -and then prints out to screen the status of the various tests. It also creates +and then prints out to the command prompt the status of the various tests. It also creates a status report file named ``expts_status_${create_date}.txt`` (where ``create_date`` is a time stamp of the form ``YYYYMMDDHHmm`` corresponding to the creation date/time -of the report) and places it in the experiment base directory. This status file +of the report) and places it in the experiment base directory. This status file contains the last 40 lines (by default; this can be adjusted via the ``num_log_lines`` -argument) from the end of each -``log.launch_FV3LAM_wflow`` log file. These lines include the experiment status -as well as the task status table generated by ``rocotostat`` (so that, in +argument) from the end of each ``log.launch_FV3LAM_wflow`` log file. These lines include the experiment status as well as the task status table generated by ``rocotostat`` (so that, in case of failure, it is convenient to pinpoint the task that failed). -For details on the usage of ``get_expts_stats.sh``, issue +For details on the usage of ``get_expts_stats.sh``, issue the command: .. code-block:: @@ -325,12 +284,12 @@ Here is an example of how to call ``get_expts_status.sh`` along with sample outp ====================================== A status report has been created in: - expts_status_fp = "/path/to/expt_dirs/set01/expts_status_202204211440.txt" + expts_status_fp = "/path/to/expt_dirs/set01/expts_status_202204211440.txt" DONE. -The "Workflow status" field of each test indicates the status of its workflow. +The "Workflow status" field of each test indicates the status of its workflow. The values that this can take on are "SUCCESS", "FAILURE", and "IN PROGRESS". @@ -346,7 +305,7 @@ Modifying an Existing Test ----------------------------- To modify an existing test, simply edit the configuration file for that test by changing existing variable values and/or adding new variables to suit the requirements of the -modified test. Such a change may also require modifications to the test description +modified test. Such a change may also require modifications to the test description in the header of the file. @@ -355,31 +314,24 @@ in the header of the file. Adding a New Test --------------------- To add a new test named, for example ``new_test01``, to one of the existing categories listed -above, say ``wflow_features``: +above, such as ``wflow_features``: -1) Choose an existing test configuration file in any one of the category directories that - matches most closely the new test to be added. Copy that file to ``config.new_test01.sh`` - and, if necessary, move it to the ``wflow_features`` category directory. +#. Choose an existing test configuration file in any one of the category directories that matches most closely the new test to be added. Copy that file to ``config.new_test01.sh`` and, if necessary, move it to the ``wflow_features`` category directory. -2) Edit ``config.new_test01.sh`` so that the header containing the test description properly - describes the new test. +#. Edit ``config.new_test01.sh`` so that the header containing the test description properly describes the new test. -3) Further edit ``config.new_test01.sh`` by modifying existing experiment variable values - and/or adding new variables such that the test runs with the intended configuration. +#. Further edit ``config.new_test01.sh`` by modifying existing experiment variable values and/or adding new variables such that the test runs with the intended configuration. .. _AddNewCategory: Adding a New WE2E Test Category ----------------------------------- -To create a new test category called, e.g. ``new_category``: +To create a new test category called, e.g., ``new_category``: -1) In the directory ``ufs-srweather-app/regional_workflow/tests/WE2E/test_configs``, - create a new directory named ``new_category``. +#. In the directory ``ufs-srweather-app/regional_workflow/tests/WE2E/test_configs``, create a new directory named ``new_category``. -2) In the file ``get_WE2Etest_names_subdirs_descs.sh``, add the element ``"new_category"`` - to the array ``category_subdirs`` that contains the list of categories/subdirectories - in which to search for test configuration files. Thus, ``category_subdirs`` becomes: +#. In the file ``get_WE2Etest_names_subdirs_descs.sh``, add the element ``"new_category"`` to the array ``category_subdirs`` that contains the list of categories/subdirectories in which to search for test configuration files. Thus, ``category_subdirs`` becomes: .. code-block:: console @@ -391,56 +343,48 @@ To create a new test category called, e.g. ``new_category``: "new_category" \ ) -New tests can now be added to ``new_category`` using the procedure described in -:numref:`Section %s `. +New tests can now be added to ``new_category`` using the procedure described in :numref:`Section %s `. .. _CreateAltTestNames: Creating Alternate Names for a Test -------------------------------------- -In order to prevent proliferation of WE2E tests, users might want to use the same -test for multiple purposes. For example, consider the test - - ``grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16`` - -in the ``grids_extrn_mdls_suites_community`` category. This checks for the successful -completion of the Rocoto workflow running the combination -of the ``RRFS_CONUScompact_25km`` grid, the ``FV3GFS`` model for -ICs and LBCs, and the ``FV3_GFS_v16`` physics suite. If this test also -happens to use the inline post capability of the weather model (it currently -doesn't; this is only a hypothetical example), then this test can also be used -to ensure that the inline post feature of the App/weather model (which is -activated in the App by setting ``WRITE_DOPOST`` to ``"TRUE"``) is working properly. -Since this test will serve two purposes, it should have two names --- one per purpose. -Assume we want to set the second (alternate) name to ``activate_inline_post``. This -can be accomplished by creating -a symlink named ``config.activate_inline_post.sh``, most appropriately in the ``wflow_features`` -category directory, that points to the configuration file +To prevent proliferation of WE2E tests, users might want to use the same test for multiple purposes. For example, consider the test + + ``grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16`` + +in the ``grids_extrn_mdls_suites_community`` category. This checks for the successful +completion of the Rocoto workflow running the combination of the ``RRFS_CONUScompact_25km`` grid, the ``FV3GFS`` model for ICs and LBCs, and the ``FV3_GFS_v16`` physics suite. If this test also +happens to use the inline post capability of the weather model (it currently doesn't; this is only a hypothetical example), then this test can also be used to ensure that the inline post feature of the App/Weather Model (which is activated in the App by setting ``WRITE_DOPOST`` to ``"TRUE"``) is working properly. +Since this test will serve two purposes, it should have two names --- one per purpose. To set the second (alternate) name to ``activate_inline_post``, the user needs to create a symlink named ``config.activate_inline_post.sh`` in the ``wflow_features`` category directory that points to the configuration file ``config.grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh`` -in the ``grids_extrn_mdls_suites_community`` category directory. +in the ``grids_extrn_mdls_suites_community`` category directory. + +.. code-block:: console + + ln -sf + +.. + COMMENT: Is the above code correct? + In this situation, the primary name for the test is ``grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16`` -(because ``config.grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh`` -is an actual file, not a symlink), and ``activate_inline_post`` is an alternate name. -This approach of allowing multiple names for the same test makes it easier to identify -the multiple purposes that a test may serve. +(because ``config.grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh`` is an actual file, not a symlink), and ``activate_inline_post`` is an alternate name. This approach of allowing multiple names for the same test makes it easier to identify the multiple purposes that a test may serve. Note the following: -* A primary test can have more than one alternate test name (by having more than - one symlink point to the test's configuration file). -* The symlinks representing the alternate test names can be in the same or a - different category directory. +* A primary test can have more than one alternate test name (by having more than one symlink point to the test's configuration file). +* The symlinks representing the alternate test names can be in the same or a different category directory. * To determine whether a test has one or more alternate names, a user can - view the CSV file ``WE2E_test_info.csv`` that ``run_WE2E_tests.sh`` generates. + view the CSV file ``WE2E_test_info.csv`` that ``run_WE2E_tests.sh`` generates. Recall from :numref:`Section %s ` that column 1 of this CSV file contains the test's primary name (and its category) while column 2 contains any alternate names (and their categories). * With this primary/alternate test naming convention, a user can list either the primary test name or one of the alternate test names in the experiments list file - (e.g. ``my_tests.txt``) that ``run_WE2E_tests.sh`` reads in. If both primary and + (e.g. ``my_tests.txt``) that ``run_WE2E_tests.sh`` reads in. If both primary and one or more alternate test names are listed, then ``run_WE2E_tests.sh`` will exit with a warning message without running any tests. diff --git a/docs/UsersGuide/source/_static/theme_overrides.css b/docs/UsersGuide/source/_static/theme_overrides.css index 9143850a43..c38958b095 100644 --- a/docs/UsersGuide/source/_static/theme_overrides.css +++ b/docs/UsersGuide/source/_static/theme_overrides.css @@ -7,9 +7,11 @@ white-space: normal !important; } - .wy-table-responsive { - overflow: visible !important; - } + /* .wy-table-responsive { */ + /* overflow: visible !important; */ + /* } */ } + + From 8570d6a9960eff69e2c2a75ff08357470b828ef0 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 16 May 2022 14:04:54 -0400 Subject: [PATCH 140/158] fix typo --- docs/UsersGuide/source/BuildRunSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 6f851bd06d..0d2730656c 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -284,7 +284,7 @@ The build will take a few minutes to complete. When it starts, a random number i Download and Stage the Data ============================ -The SRW App requires input files to run. These include static datasets, initial and boundary conditions files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW App tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in the :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. +The SRW App requires input files to run. These include static datasets, initial and boundary conditions files, and model configuration files. On Level 1 and 2 systems, the data required to run SRW App tests are already available. For Level 3 and 4 systems, the data must be added. Detailed instructions on how to add the data can be found in :numref:`Section %s Downloading and Staging Input Data `. :numref:`Sections %s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. .. _GridSpecificConfig: From fc1d87c09c34f9cb75a0bc46ff6cf042e2dc4ed3 Mon Sep 17 00:00:00 2001 From: gspetro Date: Mon, 16 May 2022 14:54:46 -0400 Subject: [PATCH 141/158] minor grammar/typos --- docs/UsersGuide/source/BuildRunSRW.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 0d2730656c..26a46f554a 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -49,11 +49,11 @@ Install the HPC-Stack Background ---------------- -The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g. NCEPLIBS, FMS, etc.) to libraries developed by NOAA's partners (e.g. PIO, ESMF, etc.) to truly third party libraries (e.g. NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `__ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW App. +The UFS Weather Model draws on over 50 code libraries to run its applications. These libraries range from libraries developed in-house at NOAA (e.g., NCEPLIBS, FMS) to libraries developed by NOAA's partners (e.g., PIO, ESMF) to truly third party libraries (e.g., NETCDF). Individual installation of these libraries is not practical, so the `HPC-Stack `__ was developed as a central installation system to ensure that the infrastructure environment across multiple platforms is as similar as possible. Installation of the HPC-Stack is required to run the SRW App. Instructions ------------------------- -Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to build applications (such as the SRW App) or models that depend on it. Users can either build the HPC-stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. +Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to build applications (such as the SRW App) or models that depend on it. Users can either build the HPC-Stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. After completing installation, continue to the next section. From f143c44948659b4413db15a18e5ffba9c2f7dc9c Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 17 May 2022 13:19:38 -0400 Subject: [PATCH 142/158] merge conflict resolution --- docs/UsersGuide/source/Introduction.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 5d2595c777..b151fcc481 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -77,11 +77,7 @@ The `Unified Post Processor `__ (DTC) for use by the :term:`NWP` community to help them assess and evaluate the performance of numerical weather predictions. MET is the core component of the unified METplus verification framework. The suite also includes the associated database and display systems called METviewer and METexpress. METplus spans a wide range of temporal and spatial scales. It is intended to be extensible through additional capabilities developed by the community. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. -======= The Model Evaluation Tools (MET) package is a set of statistical verification tools developed by the `Developmental Testbed Center `__ (DTC) for use by the :term:`NWP` community to help them assess and evaluate the performance of numerical weather predictions. MET is the core component of the enhanced METplus verification framework. The suite also includes the associated database and display systems called METviewer and METexpress. METplus spans a wide range of temporal and spatial scales. It is intended to be extensible through additional capabilities developed by the community. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. ->>>>>>> origin/develop Visualization Example ------------------------- From 4f939ffdc7031ff0e5555f086f1f9d80e9d6dd40 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 17 May 2022 13:51:36 -0400 Subject: [PATCH 143/158] merge conflict resolution --- docs/UsersGuide/source/Components.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index 3f9975148b..028c87c851 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -54,11 +54,7 @@ METplus Verification Suite The enhanced Model Evaluation Tools (`METplus `__) verification system has been integrated into the SRW App to facilitate forecast evaluation. METplus is a verification framework that spans a wide range of temporal scales (warn-on-forecast to climate) and spatial scales (storm to global). It is supported by the `Developmental Testbed Center (DTC) `__. -<<<<<<< HEAD -METplus is preinstalled on all `Level 1 `__ systems; existing builds can be viewed `here `__. METplus can be installed on other systems individually or as part of :term:`HPC-Stack`. Users on non-Level 1 systems can follow the `MET Installation `__ and `METplus Installation `__ Guides for individual installation. Currently, METplus *installation* is not a supported feature for this release of the SRW App. However, METplus *use* is supported on systems with a functioning METplus installation. -======= METplus *installation* is not included as part of the build process for this release of the SRW App. However, METplus is preinstalled on all `Level 1 `__ systems; existing builds can be viewed `here `__. METplus can be installed on other systems individually or as part of :term:`HPC-Stack`. Users on non-Level 1 systems can follow the `MET Installation `__ and `METplus Installation `__ Guides for individual installation. Currently, METplus *installation* is not a supported feature for this release of the SRW App. However, METplus *use* is supported on systems with a functioning METplus installation. ->>>>>>> origin/develop The core components of the METplus framework include the statistical driver, MET, the associated database and display systems known as METviewer and METexpress, and a suite of Python wrappers to provide low-level automation and examples, also called use-cases. MET is a set of verification tools developed for use by the :term:`NWP` community. It matches up grids with either gridded analyses or point observations and applies configurable methods to compute statistics and diagnostics. Extensive documentation is available in the `METplus User’s Guide `__ and `MET User’s Guide `__. Documentation for all other components of the framework can be found at the Documentation link for each component on the METplus `downloads `__ page. From aebc0eaf5279950adb2b1b29c0ded81bbf47b73b Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 17 May 2022 13:58:07 -0400 Subject: [PATCH 144/158] fix grid name --- docs/UsersGuide/source/BuildRunSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 26a46f554a..8adc50a2b7 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -306,7 +306,7 @@ The SRW App officially supports four different predefined grids as shown in :num +----------------------+-------------------+--------------------------------+ | RRFS_CONUS_3km | ESG grid | lambert_conformal | +----------------------+-------------------+--------------------------------+ - | RRFS_SUBCONUS_3km | ESG grid | lambert_conformal | + | SUBCONUS_Ind_3km | ESG grid | lambert_conformal | +----------------------+-------------------+--------------------------------+ From 8377f21a3ee6311f990192b3d8ea8ea43ad98a70 Mon Sep 17 00:00:00 2001 From: gspetro Date: Tue, 17 May 2022 14:58:55 -0400 Subject: [PATCH 145/158] remove resolved comments --- docs/UsersGuide/source/ConfigWorkflow.rst | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index a513aadd9e..e98b73ad95 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -5,9 +5,6 @@ Workflow Parameters: Configuring the Workflow in ``config.sh`` and ``config_defa ============================================================================================ To create the experiment directory and workflow when running the SRW App, the user must create an experiment configuration file named ``config.sh``. This file contains experiment-specific information, such as dates, external model data, observation data, directories, and other relevant settings. To help the user, two sample configuration files have been included in the ``regional_workflow`` repository’s ``ush`` directory: ``config.community.sh`` and ``config.nco.sh``. The first is for running experiments in community mode (``RUN_ENVIR`` set to "community"; see below), and the second is for running experiments in "nco" mode (``RUN_ENVIR`` set to "nco"). Note that for this release, only "community" mode is supported. These files can be used as the starting point from which to generate a variety of experiment configurations in which to run the SRW App. -.. - COMMENT: Is community mode still the only one supported? - There is an extensive list of experiment parameters that a user can set when configuring the experiment. Not all of these need to be explicitly set by the user in ``config.sh``. If a user does not define an entry in the ``config.sh`` script, either its value in ``config_defaults.sh`` will be used, or it will be reset depending on other parameters, such as the platform on which the experiment will be run (specified by ``MACHINE``). Note that ``config_defaults.sh`` contains the full list of experiment parameters that a user may set in ``config.sh`` (i.e., the user cannot set parameters in config.sh that are not initialized in ``config_defaults.sh``). The following is a list of the parameters in the ``config_defaults.sh`` file. For each parameter, the default value and a brief description is given. In addition, any relevant information on features and settings supported or unsupported in this release is specified. @@ -27,9 +24,6 @@ Platform Environment ``MACHINE``: (Default: "BIG_COMPUTER") The machine (a.k.a. platform) on which the workflow will run. Currently supported platforms include "WCOSS_DELL_P3", "HERA", "ORION", "JET", "ODIN", "CHEYENNE", "STAMPEDE", "GAEA", "SINGULARITY", "NOAACLOUD", "MACOS", and "LINUX". When running the SRW App in a container, set ``MACHINE`` to "SINGULARITY" regardless of the underlying platform. -.. - COMMENT: Are we deleting WCOSS_CRAY and/or GAEA? They're not listed in valid_param_vals.sh. What is the difference between SINGULARITY & NOAACLOUD? Can we use just one? Any other machines to add? - ``MACHINE_FILE``: (Default: "") Path to a configuration file with machine-specific settings. If none is provided, ``setup.sh`` will attempt to set the path to a configuration file for a supported platform. @@ -561,9 +555,6 @@ Set default Stochastically Perturbed Parameterizations (SPP) stochastic physics ``SPP_VAR_LIST``: (Default: ( "pbl" "sfc" "mp" "rad" "gwd" ) ) The list of parameterizations to perturb: planetary boundary layer (PBL), surface physics (SFC), microphysics (MP), radiation (RAD), gravity wave drag (GWD). Valid values: "pbl", "sfc", "rad", "gwd", and "mp". -.. - COMMENT: Needs review. Is "rad" radiation? Need confiromation. - Land Surface Model (LSM) SPP ------------------------------- @@ -838,9 +829,6 @@ Predefined Grid Parameters | "RRFS_NA_3km" | "RRFS_SUBCONUS_3km" -.. - COMMENT: Are all of these now being supported or still just the three main ones? Am I missing any? - .. note:: * If ``PREDEF_GRID_NAME`` is set to a valid predefined grid name, the grid generation method ``GRID_GEN_METHOD``, the (native) grid parameters, and the write-component grid parameters are set to predefined values for the specified grid, overwriting any settings of these parameters in the user-specified experiment configuration file (``config.sh``). In addition, if the time step ``DT_ATMOS`` and the computational parameters ``LAYOUT_X``, ``LAYOUT_Y``, and ``BLOCKSIZE`` are not specified in that configuration file, they are also set to predefined values for the specified grid. @@ -1105,10 +1093,6 @@ Verification Tasks ``RUN_TASK_GET_OBS_NDAS``: (Default: "FALSE") Flag that determines whether to run the ``GET_OBS_NDAS_TN`` task, which retrieves the :term:`NDAS` PrepBufr files used by METplus from NOAA HPSS. -.. - COMMENT: Need confirmation that the above 3 task explanations are correct. - - ``RUN_TASK_VX_GRIDSTAT``: (Default: "FALSE") Flag that determines whether to run the grid-stat verification task. @@ -1287,7 +1271,7 @@ Subhourly Forecast Parameters Time interval in minutes between the forecast model output files. If ``SUB_HOURLY_POST`` is set to "TRUE", this needs to be set to a two-digit integer between "01" and "59". Note that if ``SUB_HOURLY_POST`` is set to "TRUE" but ``DT_SUB_HOURLY_POST_MNTS`` is set to "00", ``SUB_HOURLY_POST`` will get reset to "FALSE" in the experiment generation scripts (there will be an informational message in the log file to emphasize this). .. - COMMENT: In valid_param_vals.sh only these values are listed: "1" "01" "2" "02" "3" "03" "4" "04" "5" "05" "6" "06" "10" "12" "15" "20" "30". + COMMENT: In valid_param_vals.sh only these values are listed: "1" "01" "2" "02" "3" "03" "4" "04" "5" "05" "6" "06" "10" "12" "15" "20" "30", but it says in this description that any value 00-59 can be used. Which is is? Customized Post Configuration Parameters ======================================== From 39e62e413971bfea327ee9677cceea0a84490600 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 18 May 2022 16:54:07 -0400 Subject: [PATCH 146/158] add compact grids --- docs/UsersGuide/source/ConfigWorkflow.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index e98b73ad95..03c69815dd 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -813,10 +813,8 @@ Predefined Grid Parameters **Other valid values include:** - | "RRFS_AK_13km" - | "RRFS_AK_3km" | "CONUS_25km_GFDLgrid" - | "CONUS_3km_GFDLgrid" + | "CONUS_3km_GFDLgrid" | "EMC_AK" | "EMC_HI" | "EMC_PR" @@ -824,10 +822,16 @@ Predefined Grid Parameters | "GSL_HAFSV0.A_25km" | "GSL_HAFSV0.A_13km" | "GSL_HAFSV0.A_3km" - | "GSD_HRRR_AK_50km" + | "GSD_HRRR_AK_50km" + | "RRFS_AK_13km" + | "RRFS_AK_3km" + | "RRFS_CONUScompact_25km" + | "RRFS_CONUScompact_13km" + | "RRFS_CONUScompact_3km" | "RRFS_NA_13km" | "RRFS_NA_3km" | "RRFS_SUBCONUS_3km" + | "WoFS_3km" .. note:: @@ -1268,10 +1272,7 @@ Subhourly Forecast Parameters Flag that indicates whether the forecast model will generate output files on a sub-hourly time interval (e.g., 10 minutes, 15 minutes). This will also cause the post-processor to process these sub-hourly files. If this variable is set to "TRUE", then ``DT_SUBHOURLY_POST_MNTS`` should be set to a value between "01" and "59". ``DT_SUB_HOURLY_POST_MNTS``: (Default: "00") - Time interval in minutes between the forecast model output files. If ``SUB_HOURLY_POST`` is set to "TRUE", this needs to be set to a two-digit integer between "01" and "59". Note that if ``SUB_HOURLY_POST`` is set to "TRUE" but ``DT_SUB_HOURLY_POST_MNTS`` is set to "00", ``SUB_HOURLY_POST`` will get reset to "FALSE" in the experiment generation scripts (there will be an informational message in the log file to emphasize this). - -.. - COMMENT: In valid_param_vals.sh only these values are listed: "1" "01" "2" "02" "3" "03" "4" "04" "5" "05" "6" "06" "10" "12" "15" "20" "30", but it says in this description that any value 00-59 can be used. Which is is? + Time interval in minutes between the forecast model output files. If ``SUB_HOURLY_POST`` is set to "TRUE", this needs to be set to a two-digit integer between "01" and "59". Note that if ``SUB_HOURLY_POST`` is set to "TRUE" but ``DT_SUB_HOURLY_POST_MNTS`` is set to "00", ``SUB_HOURLY_POST`` will get reset to "FALSE" in the experiment generation scripts (there will be an informational message in the log file to emphasize this). Valid values: "1" "01" "2" "02" "3" "03" "4" "04" "5" "05" "6" "06" "10" "12" "15" "20" "30". Customized Post Configuration Parameters ======================================== From c09769df516c944143f085656bf616edb211c939 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 18 May 2022 18:36:48 -0400 Subject: [PATCH 147/158] file path updates & info for HPC-Stack --- docs/UsersGuide/source/BuildRunSRW.rst | 55 +++++++++++++++----------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 8adc50a2b7..002d06b08f 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -53,7 +53,17 @@ The UFS Weather Model draws on over 50 code libraries to run its applications. T Instructions ------------------------- -Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to build applications (such as the SRW App) or models that depend on it. Users can either build the HPC-Stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. +Users working on systems that fall under `Support Levels 2-4 `_ will need to install the HPC-Stack the first time they try to build applications (such as the SRW App) or models that depend on it. Users can either build the HPC-Stack on their local system or use the centrally maintained stacks on each HPC platform if they are working on a Level 1 system. Before installing the HPC-Stack, users on both Linux and MacOS systems should set the stack size to "unlimited" (if allowed) or to the largest possible value: + +.. code-block:: console + + # Linux, if allowed + ulimit -s unlimited + + # MacOS, this corresponds to 65MB + ulimit -S -s unlimited + +For a detailed description of installation options, see :ref:`Installing the HPC-Stack `. After completing installation, continue to the next section. @@ -578,45 +588,50 @@ Minimum parameter settings for running the out-of-the-box SRW App case on Level ACCOUNT="" EXPT_SUBDIR="" USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_app/staged_extrn_mdl_files" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_app/staged_extrn_mdl_files" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_App/develop/staged_extrn_mdl_files////ICS" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_App/develop/staged_extrn_mdl_files////LBCS" + +where: +* refers to a subdirectory such as "FV3GFS" or "HRRR" containing the experiment data. +* refers to one of 3 possible data formats: ``grib2``, ``nemsio``, or ``netcdf``. +* YYYYMMDDHH refers to a subdirectory containing data for the :term:`cycle` date. + **Hera, Jet, Orion, Gaea:** -The ``MACHINE``, ``ACCOUNT``, and ``EXPT_SUBDIR`` settings are the same as for Cheyenne, except that ``"cheyenne"`` should be switched to ``"hera"``, ``"jet"``, ``"orion"``, or ``"gaea"``, respectively. Set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, but replace the file paths to Cheyenne's data with the file paths for the correct machine. ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` use the same file path. +The ``MACHINE``, ``ACCOUNT``, and ``EXPT_SUBDIR`` settings are the same as for Cheyenne, except that ``"cheyenne"`` should be switched to ``"hera"``, ``"jet"``, ``"orion"``, or ``"gaea"``, respectively. Set ``USE_USER_STAGED_EXTRN_FILES="TRUE"``, but replace the file paths to Cheyenne's data with the file paths for the correct machine. ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` use the same base file path. On Hera: .. code-block:: console - "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data" + "/scratch2/BMC/det/UFS_SRW_App/develop/model_data///YYYYMMDDHH/" On Jet: .. code-block:: console - "/lfs4/BMC/wrfruc/FV3-LAM/model_data" + "/mnt/lfs4/BMC/wrfruc/UFS_SRW_App/develop/model_data///YYYYMMDDHH/" On Orion: .. code-block:: console - "/work/noaa/fv3-cam/UFS_SRW_app/v1p0/model_data" + "/work/noaa/fv3-cam/UFS_SRW_App/develop/model_data///YYYYMMDDHH/" On Gaea: .. code-block:: console - "/lustre/f2/pdata/esrl/gsd/ufs/ufs-srw-release-v1.0.0/staged_extrn_mdl_files" - + "/lustre/f2/dev/Mark.Potts/EPIC/UFS_SRW_App/develop/staged_extrn_mdl_files///YYYYMMDDHH/" For **WCOSS** systems, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: .. code-block:: console MACHINE="wcoss_cray" or MACHINE="wcoss_dell_p3" - ACCOUNT="my_account" + ACCOUNT="valid_wcoss_project_code" EXPT_SUBDIR="my_expt_name" USE_USER_STAGED_EXTRN_FILES="TRUE" @@ -624,16 +639,8 @@ For WCOSS_DELL_P3: .. code-block:: console - EXTRN_MDL_SOURCE_BASEDIR_ICS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/model_data" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/model_data" - -For WCOSS_CRAY: - -.. code-block:: console - - EXTRN_MDL_SOURCE_BASEDIR_ICS="/gpfs/hps3/emc/meso/noscrub/UFS_SRW_App/model_data" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/gpfs/hps3/emc/meso/noscrub/UFS_SRW_App/model_data" - + EXTRN_MDL_SOURCE_BASEDIR_ICS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/develop/model_data///YYYYMMDDHH/ICS" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/develop/model_data///YYYYMMDDHH/LBCS" **NOAA Cloud Systems:** @@ -645,10 +652,10 @@ For WCOSS_CRAY: EXPT_BASEDIR="lustre/$USER/expt_dirs" COMPILER="gnu" USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/EPIC/model_data/FV3GFS" - EXTRN_MDL_FILES_ICS=( "gfs.pgrb2.0p25.f000" ) - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/EPIC/model_data/FV3GFS" - EXTRN_MDL_FILES_LBCS=( "gfs.pgrb2.0p25.f006" "gfs.pgrb2.0p25.f012" ) + EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/EPIC/UFS_SRW_App/develop/model_data/FV3GFS" + EXTRN_MDL_FILES_ICS=( "gfs.t18z.pgrb2.0p25.f000" ) + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/EPIC/UFS_SRW_App/develop/model_data/FV3GFS" + EXTRN_MDL_FILES_LBCS=( "gfs.t18z.pgrb2.0p25.f006" "gfs.t18z.pgrb2.0p25.f012" ) .. note:: From 5364e9919f386ff8fa0643ff84bdd329e806ee21 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 18 May 2022 19:07:53 -0400 Subject: [PATCH 148/158] add SRW prereqs to Intro --- docs/UsersGuide/source/Introduction.rst | 110 ++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index b151fcc481..f92b7ecd12 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -38,6 +38,116 @@ File paths or code that include angle brackets (e.g., ``build__` below or refer to :numref:`Chapter %s ` for a more in-depth treatment. +.. _Prerequisites: + +Prerequisites for Using the SRW Application +=============================================== + +Background Knowledge Prerequisites +-------------------------------------- + +The instructions in this documentation assume that users have certain background knowledge: + +* Familiarity with LINUX/UNIX systems +* Command line basics +* System configuration knowledge (e.g., compilers, environment variables, paths, etc.) +* Numerical Weather Prediction +* Meteorology (particularly meteorology at the scales being predicted) + +.. + COMMENT: Suggested sub-bullets for Meteorology/NWP? Cumulus and microphysics parameterizations? Convection? Microphysics? + +Additional background knowledge in the following areas could be helpful: +* High-Performance Computing (HPC) Systems for those running the SRW App on an HPC system +* Programming (particularly Python) for those interested in contributing to the SRW App code +* Creating an SSH Tunnel to access HPC systems from the command line +* Containerization +* Workflow Managers/Rocoto + + +Software/Operating System Requirements +----------------------------------------- +The UFS SRW Application has been designed so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. NOAA `Level 1 & 2 systems `__ already have these prerequisites installed. However, users working on other systems must ensure that the following requirements are installed on their system: + +**Minimum Platform Requirements:** + +* POSIX-compliant UNIX-style operating system + +* >40 GB disk space + + * 18 GB input data from GFS, RAP, and HRRR for "out-of-the-box" SRW App case described in :numref:`Chapter %s ` + * 6 GB for :term:`HPC-Stack` full installation + * 1 GB for ufs-srweather-app installation + * 11 GB for 48hr forecast on CONUS 25km domain + +* 4GB memory (CONUS 25km domain) + +* Fortran compiler with full Fortran 2008 standard support +* Fortran compiler with support for Fortran 2003 + + * gfortran v9+ or ifort v18+ are the only ones tested, but others may work. + +.. + COMMENT: Which one is it?! + +* C and C++ compilers compatible with the Fortran compiler + + * gcc v9+, ifort v18+, and clang v9+ (macOS, native Apple clang or LLVM clang) have been tested + +* Python v3.6+, including prerequisite packages ``jinja2``, ``pyyaml`` and ``f90nml`` + + * Python packages ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``, and ``pillow`` are required for users who would like to use the provided graphics scripts + +* Perl 5 + +* git v1.8+ + +.. + COMMENT: Should curl/wget/TIFF library also be required? These are listed as prerequisites for building HPC-Stack on generic MacOS/Linux + + +The following software is also required to run the SRW Application, but the :term:`HPC-Stack` (which contains the software libraries necessary for building and running the SRW App) can be configured to build these requirements: + +* CMake v3.15+ + +* MPI (MPICH, OpenMPI, or other implementation) + + * Only **MPICH** can be built with HPC-Stack. Other options must be installed separately by the user. + +* Software libraries + + * netCDF (C and Fortran libraries) + * HDF5 + * ESMF 8.2.0 + * Jasper + * libJPG + * libPNG + * zlib + +.. + COMMENT: Update version of ESMF? Need other version updates? + +For MacOS systems, some additional software is needed. It is recommended that users install this software using the `Homebrew `__ package manager for MacOS: + +* brew install gcc@11 +* brew install cmake +* brew install make +* brew install wget +* brew install coreutils +* brew install pkg-config + +.. + COMMENT: Is this still accurate? It seems like we should delete the last one. And gcc@11 is basically the same as requiring fortran/C/C++ compilers, no? CMake is listed above. + +Optional but recommended prerequisites for all systems: + +* Conda for installing/managing Python packages +* Bash v4+ +* Rocoto Workflow Management System (1.3.1) +* Python packages ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``, and ``pillow`` for graphics +* Lmod + + .. _ComponentsOverview: SRW App Components Overview From f51bb57bde32e066c7917f7aa7e5dd9b76f49333 Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 18 May 2022 19:12:48 -0400 Subject: [PATCH 149/158] change ConfigNewPlatform to a non-container quickstart --- docs/UsersGuide/source/ConfigNewPlatform.rst | 262 ------------------- docs/UsersGuide/source/Introduction.rst | 2 +- docs/UsersGuide/source/Non-ContainerQS.rst | 120 +++++++++ docs/UsersGuide/source/index.rst | 2 +- 4 files changed, 122 insertions(+), 264 deletions(-) delete mode 100644 docs/UsersGuide/source/ConfigNewPlatform.rst create mode 100644 docs/UsersGuide/source/Non-ContainerQS.rst diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst deleted file mode 100644 index 6d7cfd8e1e..0000000000 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ /dev/null @@ -1,262 +0,0 @@ -.. _ConfigNewPlatform: - -============================ -Configuring a New Platform -============================ - -The UFS SRW Application has been designed to work primarily on a number of Level 1 and 2 support platforms, listed `here `__. However, it is also designed with flexibility in mind, so that any sufficiently up-to-date machine with a UNIX-based operating system should be capable of running the application. A full list of prerequisites for installing the UFS SRW App and running the Graduate Student Test can be found in :numref:`Section %s `. - -The first step to installing on a new machine is to install the :term:`HPC-Stack` (https://github.com/NOAA-EMC/hpc-stack), which is a unified, shell script-based build system created and maintained by NCEP and EMC, which builds the software stack required for the SRW App and its components. HPC-Stack comes with a large number of prerequisites (see :numref:`Section %s ` for more info), but the only required software prior to starting the installation process is as follows: - -* Fortran compiler with support for Fortran 2003 - - * gfortran v9+ or ifort v18+ are the only ones tested, but others may work. - -* C and C++ compilers compatible with the Fortran compiler - - * 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 a number of additional Python modules (see :numref:`Section %s `) if the user would like to use the provided graphics scripts - -* Perl 5 - -* git v1.8+ - -* CMake v3.12+ - - * 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 both Linux and macOS systems, users 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 - -For Linux systems, as long as the above software is available, users can move on to the next step: installing the :term:`HPC-Stack` package according to the instructions in :numref:`Chapter %s `. - -For MacOS systems, some extra software is needed: ``gcc@11``, ``cmake``, ``make``, ``wget``, ``coreutils``, and ``pkg-config``. It is recommended that users install this software using the `Homebrew `__ package manager for MacOS: - -* brew install gcc@11 -* brew install cmake -* brew install make -* brew install wget -* brew install coreutils -* brew install pkg-config - -.. - COMMENT: Is this still accurate? It seems like we should delete the last 2 and add openssl@3, Lmod, curl, libtiff. - -However, it is also possible to install these utilities via `Macports `__ or by installing each utility individually (not recommended). - - -Installing the HPC-Stack -=========================== -Prior to building the UFS SRW Application on a new machine, users will need to install the :term:`HPC-Stack`. Installation instructions appear in both the `HPC-Stack documentation `__ and in :numref:`Chapter %s ` of this User's Guide. The instructions will vary somewhat 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`` to build the code. This process will create a number of modulefiles and scripts that will be used for setting up the build environment for the UFS SRW App. - -Once the HPC-Stack has been successfully installed, users can move on to building the UFS SRW Application. - -.. note:: - The ``ESMFMKFILE`` variable allows HPC-Stack to find the location where ESMF has been built; if users receive a ``ESMF not found, abort`` error, they may need to specify a slightly different location: - - .. code-block:: console - - export ESMFMKFILE=${INSTALL_PREFIX}/lib64/esmf.mk - - Then they can delete and re-create the build directory and continue the build process as described above. - -.. note:: - - If users skipped the building of any of the software provided by HPC-Stack, they may need to add the appropriate locations to their ``CMAKE_PREFIX_PATH`` variable. Multiple directories may be added, separated by semicolons (;) as in the following example: - - .. code-block:: console - - cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DCMAKE_PREFIX_PATH=”${INSTALL_PREFIX};/location/of/other/software” -DOPENMP=ON .. 2>&1 | tee log.cmake - -.. - COMMENT: Are these notes relevant now that NCEPLIBS/NCEPLIBS-external have been changed to HPC-Stack? - -Building the UFS SRW Application -======================================= - -For a detailed explanation of how to build and run the SRW App on any supported system, see :numref:`Chapter %s `. The overall procedure for generating an experiment is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. An overview of the required steps appears below. However, users can expect to access other referenced sections of this User's Guide for more detail. - - #. Clone the SRW App from GitHub: - - .. code-block:: console - - git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git - - #. Check out the external repositories: - - .. code-block:: console - - cd ufs-srweather-app - ./manage_externals/checkout_externals - - #. Set up the build environment. - - .. code-block:: console - - source etc/lmod-setup.sh - - where refers to the user's platform (e.g., ``macos``, ``gaea``, ``odin``, ``singularity``). - - Users will also need to load the "build" modulefile appropriate to their system. On Level 3 & 4 systems, users can adapt an existing modulefile (such as ``build_macos_gnu``) to their system. - - .. code-block:: console - - module use - module load build__ - - #. Build the executables - - From the top-level ``ufs-srweather-app`` directory, run: - - .. code-block:: console - - mkdir build - cd build - 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:`Chapter %s ` (if on a Level 3-4 system). - - .. code-block:: console - - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/ - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/FV3GFS/grib2/2019061518/ - - #. Configure the experiment parameters. - - .. code-block:: console - - cd regional_workflow/ush - cp config.community.sh config.sh - - 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:`Chapter %s `. Parameters and valid values are listed in :numref:`Chapter %s `. - - #. Load the python environment for the regional workflow. Users on Level 3-4 systems will need to use one of the existing ``wflow_`` modulefiles (e.g., ``wflow_macos``) and adapt it to their system. - - .. code-block:: console - - module use - module load wflow_ - conda activate regional_workflow - - #. Generate the experiment workflow. - - .. code-block:: console - - ./generate_FV3LAM_wflow.sh - - #. Run the regional workflow. There are several methods available for this step, which are discussed in :numref:`Chapter %s ` and :numref:`Chapter %s `. One possible method is summarized below. It requires the Rocoto Workflow Manager. - - .. code-block:: console - - cd $EXPTDIR - ./launch_FV3LAM_wflow.sh - - To launch the workflow and check the experiment's progress: - - .. code-block:: console - - ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow - -Optionally, users may :ref:`configure their own grid `, instead of using a predefined grid, and :ref:`plot the output ` of their experiment(s). - - -Background Knowledge Prerequisites -===================================== - -In general, the instructions in this documentation assume that users have certain background knowledge. - -* Familiarity with LINUX/UNIX systems -* Command line basics -* System configuration knowledge (e.g., compilers, environment variables, paths, etc.) -* Meteorology & Numerical Weather Prediction - -.. - COMMENT: Suggested sub-bullets for Meteorology/NWP? - -Additional background knowledge in the following areas could be helpful: -* High-Performance Computing (HPC) Systems for those running the SRW App on an HPC system -* Programming (particularly Python) for those interested in contributing to the SRW App code -* Creating an SSH Tunnel to access HPC systems from the command line -* Containerization -* Workflow Managers/Rocoto - -.. _SW-OS-Requirements: - -Software/Operating System Requirements -======================================= -Those requirements highlighted in **bold** are included in the `HPC-Stack `__. - -**Minimum platform requirements for the UFS SRW Application and NCEPLIBS:** - -* POSIX-compliant UNIX-style operating system - -* >40 GB disk space - - * 18 GB input data from GFS, RAP, and HRRR for Graduate Student Test - * 6 GB for NCEPLIBS-external and NCEPLIBS full installation - * 1 GB for ufs-srweather-app installation - * 11 GB for 48hr forecast on CONUS 25km domain - -* 4GB memory (CONUS 25km domain) - -* Fortran compiler with full Fortran 2008 standard support - -* C and C++ compiler - -* Python v3.6+, including prerequisite packages ``jinja2``, ``pyyaml`` and ``f90nml`` - -* Perl 5 - -* git v1.8+ - -* MPI (**MPICH**, OpenMPI, or other implementation) - -* CMake v3.12+ - -* Software libraries - - * **netCDF (C and Fortran libraries)** - * **HDF5** - * **ESMF** 8.2.0 - * **Jasper** - * **libJPG** - * **libPNG** - * **zlib** - -.. - COMMENT: Update version of ESMF? Need other version updates? - -macOS-specific prerequisites: - -* brew install gcc@11 -* brew install cmake -* brew install make -* brew install wget -* brew install coreutils -* brew install pkg-config - -.. - COMMENT: Do we need these last 2? Are there others? (e.g., openssl@3?) Lmod, curl, libtiff - -Optional but recommended prerequisites: - -* Conda for installing/managing Python packages -* Bash v4+ -* Rocoto Workflow Management System (1.3.1) -* **CMake v3.15+** -* Python packages ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``, and ``pillow`` for graphics -* Lmod - -.. - COMMENT: Are we supporting any installations that don't use Lmod? Should this come under "required?" Or not because it is not mandatory for running the SRW App (but do we know that?). diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index f92b7ecd12..c66f39b391 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -38,7 +38,7 @@ File paths or code that include angle brackets (e.g., ``build__` below or refer to :numref:`Chapter %s ` for a more in-depth treatment. -.. _Prerequisites: +.. _SRWPrerequisites: Prerequisites for Using the SRW Application =============================================== diff --git a/docs/UsersGuide/source/Non-ContainerQS.rst b/docs/UsersGuide/source/Non-ContainerQS.rst new file mode 100644 index 0000000000..563bc59cd9 --- /dev/null +++ b/docs/UsersGuide/source/Non-ContainerQS.rst @@ -0,0 +1,120 @@ +.. _NCQuickstart: + +============================ +Non-Container Quick Start +============================ + +Installing the HPC-Stack +=========================== +Prior to building the UFS SRW Application on a new machine, users will need to install the :term:`HPC-Stack`. Installation instructions appear in both the `HPC-Stack documentation `__ and in :numref:`Chapter %s ` of this User's Guide. The instructions will vary somewhat 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`` to build the code. This process will create a number of modulefiles and scripts that will be used for setting up the build environment for the UFS SRW App. + +Once the HPC-Stack has been successfully installed, users can move on to building the UFS SRW Application. + +.. note:: + The ``ESMFMKFILE`` variable allows HPC-Stack to find the location where ESMF has been built; if users receive an ``ESMF not found, abort`` error, they may need to specify a slightly different location: + + .. code-block:: console + + export ESMFMKFILE=${INSTALL_PREFIX}/lib64/esmf.mk + + Then they can delete and re-create the build directory and continue the build process as described above. + +.. note:: + + If users skipped the building of any of the software provided by HPC-Stack, they may need to add the appropriate locations to their ``CMAKE_PREFIX_PATH`` variable. Multiple directories may be added, separated by semicolons (;) as in the following example: + + .. code-block:: console + + cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DCMAKE_PREFIX_PATH=”${INSTALL_PREFIX};/location/of/other/software” -DOPENMP=ON .. 2>&1 | tee log.cmake + +.. + COMMENT: Are these notes relevant now that NCEPLIBS/NCEPLIBS-external have been changed to HPC-Stack? + +Building the UFS SRW Application +======================================= + +For a detailed explanation of how to build and run the SRW App on any supported system, see :numref:`Chapter %s `. The overall procedure for generating an experiment is shown in :numref:`Figure %s `, with the scripts to generate and run the workflow shown in red. An overview of the required steps appears below. However, users can expect to access other referenced sections of this User's Guide for more detail. + + #. Clone the SRW App from GitHub: + + .. code-block:: console + + git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git + + #. Check out the external repositories: + + .. code-block:: console + + cd ufs-srweather-app + ./manage_externals/checkout_externals + + #. Set up the build environment. + + .. code-block:: console + + source etc/lmod-setup.sh + + where refers to the user's platform (e.g., ``macos``, ``gaea``, ``odin``, ``singularity``). + + Users will also need to load the "build" modulefile appropriate to their system. On Level 3 & 4 systems, users can adapt an existing modulefile (such as ``build_macos_gnu``) to their system. + + .. code-block:: console + + module use + module load build__ + + #. Build the executables + + From the top-level ``ufs-srweather-app`` directory, run: + + .. code-block:: console + + mkdir build + cd build + 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:`Chapter %s ` (if on a Level 3-4 system). + + .. code-block:: console + + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/ + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/FV3GFS/grib2/2019061518/ + + #. Configure the experiment parameters. + + .. code-block:: console + + cd regional_workflow/ush + cp config.community.sh config.sh + + 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:`Chapter %s `. Parameters and valid values are listed in :numref:`Chapter %s `. + + #. Load the python environment for the regional workflow. Users on Level 3-4 systems will need to use one of the existing ``wflow_`` modulefiles (e.g., ``wflow_macos``) and adapt it to their system. + + .. code-block:: console + + module use + module load wflow_ + conda activate regional_workflow + + #. Generate the experiment workflow. + + .. code-block:: console + + ./generate_FV3LAM_wflow.sh + + #. Run the regional workflow. There are several methods available for this step, which are discussed in :numref:`Chapter %s ` and :numref:`Chapter %s `. One possible method is summarized below. It requires the Rocoto Workflow Manager. + + .. code-block:: console + + cd $EXPTDIR + ./launch_FV3LAM_wflow.sh + + To launch the workflow and check the experiment's progress: + + .. code-block:: console + + ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow + +Optionally, users may :ref:`configure their own grid `, instead of using a predefined grid, and :ref:`plot the output ` of their experiment(s). diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index 8cc67f48e8..48ba5c40ca 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -13,13 +13,13 @@ UFS Short-Range Weather App Users Guide Introduction Quickstart + Non-ContainerQS BuildRunSRW Components Include-HPCInstall InputOutputFiles ConfigWorkflow LAMGrids - ConfigNewPlatform RocotoInfo WE2Etests Graphics From 3df05964c1bf0ac3c2931a9b8ae14a80b78e679b Mon Sep 17 00:00:00 2001 From: gspetro Date: Wed, 18 May 2022 19:35:44 -0400 Subject: [PATCH 150/158] clean up non-container quickstart --- docs/UsersGuide/source/Non-ContainerQS.rst | 26 +++++++++++----------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/UsersGuide/source/Non-ContainerQS.rst b/docs/UsersGuide/source/Non-ContainerQS.rst index 563bc59cd9..17dde869ee 100644 --- a/docs/UsersGuide/source/Non-ContainerQS.rst +++ b/docs/UsersGuide/source/Non-ContainerQS.rst @@ -4,31 +4,31 @@ Non-Container Quick Start ============================ -Installing the HPC-Stack +Install the HPC-Stack =========================== -Prior to building the UFS SRW Application on a new machine, users will need to install the :term:`HPC-Stack`. Installation instructions appear in both the `HPC-Stack documentation `__ and in :numref:`Chapter %s ` of this User's Guide. The instructions will vary somewhat 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`` to build the code. This process will create a number of modulefiles and scripts that will be used for setting up the build environment for the UFS 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 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`` to build the code. This process will create a number of modulefiles and scripts that will be used for setting up the build environment for the UFS SRW App. Once the HPC-Stack has been successfully installed, users can move on to building the UFS SRW Application. -.. note:: - The ``ESMFMKFILE`` variable allows HPC-Stack to find the location where ESMF has been built; if users receive an ``ESMF not found, abort`` error, they may need to specify a slightly different location: +.. + COMMENT: Are these notes relevant now that NCEPLIBS/NCEPLIBS-external have been changed to HPC-Stack? + .. note:: + The ``ESMFMKFILE`` variable allows HPC-Stack to find the location where ESMF has been built; if users receive an ``ESMF not found, abort`` error, they may need to specify a slightly different location: - .. code-block:: console + .. code-block:: console - export ESMFMKFILE=${INSTALL_PREFIX}/lib64/esmf.mk + export ESMFMKFILE=${INSTALL_PREFIX}/lib64/esmf.mk - Then they can delete and re-create the build directory and continue the build process as described above. + Then they can delete and re-create the build directory and continue the build process as described above. -.. note:: + .. note:: - If users skipped the building of any of the software provided by HPC-Stack, they may need to add the appropriate locations to their ``CMAKE_PREFIX_PATH`` variable. Multiple directories may be added, separated by semicolons (;) as in the following example: + If users skipped the building of any of the software provided by HPC-Stack, they may need to add the appropriate locations to their ``CMAKE_PREFIX_PATH`` variable. Multiple directories may be added, separated by semicolons (;) as in the following example: - .. code-block:: console + .. code-block:: console - cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DCMAKE_PREFIX_PATH=”${INSTALL_PREFIX};/location/of/other/software” -DOPENMP=ON .. 2>&1 | tee log.cmake + cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DCMAKE_PREFIX_PATH=”${INSTALL_PREFIX};/location/of/other/software” -DOPENMP=ON .. 2>&1 | tee log.cmake -.. - COMMENT: Are these notes relevant now that NCEPLIBS/NCEPLIBS-external have been changed to HPC-Stack? Building the UFS SRW Application ======================================= From 7f6e4e896250cd2a09cb0c96ceaf572dbf1869cb Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 19 May 2022 18:15:00 -0400 Subject: [PATCH 151/158] update build options for non-container QS --- docs/UsersGuide/source/Non-ContainerQS.rst | 38 +++++++++++++--------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/docs/UsersGuide/source/Non-ContainerQS.rst b/docs/UsersGuide/source/Non-ContainerQS.rst index 17dde869ee..7317f9860c 100644 --- a/docs/UsersGuide/source/Non-ContainerQS.rst +++ b/docs/UsersGuide/source/Non-ContainerQS.rst @@ -48,31 +48,39 @@ For a detailed explanation of how to build and run the SRW App on any supported cd ufs-srweather-app ./manage_externals/checkout_externals - #. Set up the build environment. + #. Set up the build environment and build the executables. - .. code-block:: console + * Option 1: - source etc/lmod-setup.sh + .. code-block:: console + + ./devbuild.sh --platform= - where refers to the user's platform (e.g., ``macos``, ``gaea``, ``odin``, ``singularity``). + where is replaced with the name of the platform the user is working on. Valid values are: cheyenne | gaea | hera | jet | macos | odin | orion | singularity | wcoss_dell_p3 - Users will also need to load the "build" modulefile appropriate to their system. On Level 3 & 4 systems, users can adapt an existing modulefile (such as ``build_macos_gnu``) to their system. + * Option 2: - .. code-block:: console + .. code-block:: console - module use - module load build__ + source etc/lmod-setup.sh - #. Build the executables + where refers to the user's platform (e.g., ``macos``, ``gaea``, ``odin``, ``singularity``). - From the top-level ``ufs-srweather-app`` directory, run: + Users will also need to load the "build" modulefile appropriate to their system. On Level 3 & 4 systems, users can adapt an existing modulefile (such as ``build_macos_gnu``) to their system. - .. code-block:: console + .. code-block:: console + + module use + module load build__ + + From the top-level ``ufs-srweather-app`` directory, run: + + .. code-block:: console - mkdir build - cd build - cmake .. -DCMAKE_INSTALL_PREFIX=.. - make -j 4 >& build.out & + mkdir build + cd build + 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:`Chapter %s ` (if on a Level 3-4 system). From 25851cb7b3aa0a08801b95180e179532207170ab Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 19 May 2022 18:16:02 -0400 Subject: [PATCH 152/158] update file paths & WE2E --- docs/UsersGuide/source/BuildRunSRW.rst | 15 +++++++-------- docs/UsersGuide/source/ConfigWorkflow.rst | 12 +++--------- docs/UsersGuide/source/WE2Etests.rst | 8 ++++++-- 3 files changed, 16 insertions(+), 19 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 002d06b08f..e0d43967a2 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -588,8 +588,8 @@ Minimum parameter settings for running the out-of-the-box SRW App case on Level ACCOUNT="" EXPT_SUBDIR="" USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_App/develop/staged_extrn_mdl_files////ICS" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_App/develop/staged_extrn_mdl_files////LBCS" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/glade/p/ral/jntp/UFS_SRW_App/develop/input_model_data///" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/glade/p/ral/jntp/UFS_SRW_App/develop/input_model_data///" where: * refers to a subdirectory such as "FV3GFS" or "HRRR" containing the experiment data. @@ -605,26 +605,25 @@ On Hera: .. code-block:: console - "/scratch2/BMC/det/UFS_SRW_App/develop/model_data///YYYYMMDDHH/" + "/scratch2/BMC/det/UFS_SRW_App/develop/input_model_data///YYYYMMDDHH/" On Jet: .. code-block:: console - "/mnt/lfs4/BMC/wrfruc/UFS_SRW_App/develop/model_data///YYYYMMDDHH/" + "/mnt/lfs4/BMC/wrfruc/UFS_SRW_App/develop/input_model_data///YYYYMMDDHH/" On Orion: .. code-block:: console - "/work/noaa/fv3-cam/UFS_SRW_App/develop/model_data///YYYYMMDDHH/" - + "/work/noaa/fv3-cam/UFS_SRW_App/develop/input_model_data///YYYYMMDDHH/" On Gaea: .. code-block:: console - "/lustre/f2/dev/Mark.Potts/EPIC/UFS_SRW_App/develop/staged_extrn_mdl_files///YYYYMMDDHH/" + "/lustre/f2/dev/Mark.Potts/EPIC/UFS_SRW_App/develop/input_model_data///YYYYMMDDHH/" For **WCOSS** systems, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: @@ -640,7 +639,7 @@ For WCOSS_DELL_P3: .. code-block:: console EXTRN_MDL_SOURCE_BASEDIR_ICS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/develop/model_data///YYYYMMDDHH/ICS" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/develop/model_data///YYYYMMDDHH/LBCS" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/gpfs/dell2/emc/modeling/noscrub/UFS_SRW_App/develop/input_model_data///YYYYMMDDHH/LBCS" **NOAA Cloud Systems:** diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index 03c69815dd..c8239f2996 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -744,10 +744,7 @@ Write-Component (Quilting) Parameters The number of MPI tasks to allocate for each write group. ``WRTCMP_output_grid``: (Default: "''") - Sets the type (coordinate system) of the write component grid. The default empty string forces the user to set a valid value for ``WRTCMP_output_grid`` in ``config.sh`` if specifying a *custom* grid. Otherwise, the ordinary "regional_latlon" grid will be used. Valid values: "lambert_conformal" "regional_latlon" "rotated_latlon" - -.. - COMMENT: If no value is specified in config.sh, would setup.sh (or some other script?) use the ordinary "regional_latlon"? Or would the experiment just fail? + Sets the type (coordinate system) of the write component grid. The default empty string forces the user to set a valid value for ``WRTCMP_output_grid`` in ``config.sh`` if specifying a *custom* grid. When creating an experiment with a user-defined grid, this parameter must be specified or the experiment will fail. Valid values: "lambert_conformal" "regional_latlon" "rotated_latlon" ``WRTCMP_cen_lon``: (Default: "") Longitude (in degrees) of the center of the write component grid. Can usually be set to the corresponding value from the native grid. @@ -756,13 +753,10 @@ Write-Component (Quilting) Parameters Latitude (in degrees) of the center of the write component grid. Can usually be set to the corresponding value from the native grid. ``WRTCMP_lon_lwr_left``: (Default: "") - Longitude (in degrees) of the center of the lower-left (southwest) cell on the write component grid. If using the "rotated_latlon" coordinate system, this is expressed in terms of the rotated longitude. Must be set manually. - -.. - COMMENT: Has this changed? Or still manual? + Longitude (in degrees) of the center of the lower-left (southwest) cell on the write component grid. If using the "rotated_latlon" coordinate system, this is expressed in terms of the rotated longitude. Must be set manually when running an experiment with a user-defined grid. ``WRTCMP_lat_lwr_left``: (Default: "") - Latitude (in degrees) of the center of the lower-left (southwest) cell on the write component grid. If using the "rotated_latlon" coordinate system, this is expressed in terms of the rotated latitude. Must be set manually. + Latitude (in degrees) of the center of the lower-left (southwest) cell on the write component grid. If using the "rotated_latlon" coordinate system, this is expressed in terms of the rotated latitude. Must be set manually when running an experiment with a user-defined grid. **The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "rotated_latlon":** diff --git a/docs/UsersGuide/source/WE2Etests.rst b/docs/UsersGuide/source/WE2Etests.rst index 945da6050e..53fec6aa77 100644 --- a/docs/UsersGuide/source/WE2Etests.rst +++ b/docs/UsersGuide/source/WE2Etests.rst @@ -365,18 +365,21 @@ in the ``grids_extrn_mdls_suites_community`` category directory. .. code-block:: console - ln -sf + ln -fs --relative + + .. COMMENT: Is the above code correct? In this situation, the primary name for the test is ``grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16`` -(because ``config.grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh`` is an actual file, not a symlink), and ``activate_inline_post`` is an alternate name. This approach of allowing multiple names for the same test makes it easier to identify the multiple purposes that a test may serve. +(because ``config.grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh`` is an actual file, not a symlink), and ``activate_inline_post`` is an alternate name. This approach of allowing multiple names for the same test makes it easier to identify the multiple purposes that a test may serve. Note the following: * A primary test can have more than one alternate test name (by having more than one symlink point to the test's configuration file). * The symlinks representing the alternate test names can be in the same or a different category directory. +* The --relative flag makes the symlink relative (i.e., within/below the ``regional_workflow`` directory structure) so that it stays valid when copied to other locations. However, the ``--relative`` flag may be different and/or not exist on every platform. * To determine whether a test has one or more alternate names, a user can view the CSV file ``WE2E_test_info.csv`` that ``run_WE2E_tests.sh`` generates. Recall from :numref:`Section %s ` that column 1 of this CSV @@ -388,3 +391,4 @@ Note the following: one or more alternate test names are listed, then ``run_WE2E_tests.sh`` will exit with a warning message without running any tests. + From e99cc1d101fbe6ac905897b46162ee2af1e74c20 Mon Sep 17 00:00:00 2001 From: gspetro Date: Thu, 19 May 2022 22:46:48 -0400 Subject: [PATCH 153/158] minor fixes --- docs/UsersGuide/source/ConfigWorkflow.rst | 7 +------ docs/UsersGuide/source/Non-ContainerQS.rst | 4 ++-- docs/UsersGuide/source/WE2Etests.rst | 5 ----- 3 files changed, 3 insertions(+), 13 deletions(-) diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index c8239f2996..ee42848779 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -409,8 +409,6 @@ CCPP Parameter | "FV3_GFS_v15_thompson_mynn_lam3km" | "FV3_RRFS_v1alpha" -.. - COMMENT: "FV3_WoFS" technically has not been merged yet... and is called NSSL? What should I put for now? Current Default is "FV3_GFS_v15p2" - need to make sure we change that. Stochastic Physics Parameters ================================ @@ -504,10 +502,7 @@ Stochastic Kinetic Energy Backscatter (SKEB) Parameters * 2-pattern is vorticity ``SKEB_VDOF``: (Default: "10") - The number of degrees of freedom in the vertical for the SKEB random pattern. - -.. - COMMENT: The vertical what? + The number of degrees of freedom in the vertical direction for the SKEB random pattern. .. _SPP: diff --git a/docs/UsersGuide/source/Non-ContainerQS.rst b/docs/UsersGuide/source/Non-ContainerQS.rst index 7317f9860c..d135c30c3f 100644 --- a/docs/UsersGuide/source/Non-ContainerQS.rst +++ b/docs/UsersGuide/source/Non-ContainerQS.rst @@ -50,7 +50,7 @@ For a detailed explanation of how to build and run the SRW App on any supported #. Set up the build environment and build the executables. - * Option 1: + * **Option 1:** .. code-block:: console @@ -58,7 +58,7 @@ For a detailed explanation of how to build and run the SRW App on any supported where is replaced with the name of the platform the user is working on. Valid values are: cheyenne | gaea | hera | jet | macos | odin | orion | singularity | wcoss_dell_p3 - * Option 2: + * **Option 2:** .. code-block:: console diff --git a/docs/UsersGuide/source/WE2Etests.rst b/docs/UsersGuide/source/WE2Etests.rst index 53fec6aa77..cb4b0a8673 100644 --- a/docs/UsersGuide/source/WE2Etests.rst +++ b/docs/UsersGuide/source/WE2Etests.rst @@ -367,11 +367,6 @@ in the ``grids_extrn_mdls_suites_community`` category directory. ln -fs --relative - - -.. - COMMENT: Is the above code correct? - In this situation, the primary name for the test is ``grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16`` (because ``config.grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.sh`` is an actual file, not a symlink), and ``activate_inline_post`` is an alternate name. This approach of allowing multiple names for the same test makes it easier to identify the multiple purposes that a test may serve. From 2bbd9b80527363d02f7363178e10f9a7f1fa618e Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 20 May 2022 12:59:24 -0400 Subject: [PATCH 154/158] update I/O & Gaea file paths --- docs/UsersGuide/source/BuildRunSRW.rst | 8 +++--- docs/UsersGuide/source/InputOutputFiles.rst | 32 +++++++++------------ docs/UsersGuide/source/Non-ContainerQS.rst | 2 +- 3 files changed, 19 insertions(+), 23 deletions(-) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index e0d43967a2..89ed68e6bf 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -623,7 +623,7 @@ On Gaea: .. code-block:: console - "/lustre/f2/dev/Mark.Potts/EPIC/UFS_SRW_App/develop/input_model_data///YYYYMMDDHH/" + "/lustre/f2/pdata/ncep/UFS_SRW_App/develop/input_model_data///YYYYMMDDHH/" For **WCOSS** systems, edit ``config.sh`` with these WCOSS-specific parameters, and use a valid WCOSS project code for the account parameter: @@ -645,15 +645,15 @@ For WCOSS_DELL_P3: .. code-block:: console - MACHINE="SINGULARITY" + MACHINE="NOAACLOUD" ACCOUNT="none" EXPT_SUBDIR="" EXPT_BASEDIR="lustre/$USER/expt_dirs" COMPILER="gnu" USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/EPIC/UFS_SRW_App/develop/model_data/FV3GFS" + EXTRN_MDL_SOURCE_BASEDIR_ICS="/contrib/EPIC/UFS_SRW_App/develop/input_model_data/FV3GFS" EXTRN_MDL_FILES_ICS=( "gfs.t18z.pgrb2.0p25.f000" ) - EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/EPIC/UFS_SRW_App/develop/model_data/FV3GFS" + EXTRN_MDL_SOURCE_BASEDIR_LBCS="/contrib/EPIC/UFS_SRW_App/develop/input_model_data/FV3GFS" EXTRN_MDL_FILES_LBCS=( "gfs.t18z.pgrb2.0p25.f006" "gfs.t18z.pgrb2.0p25.f012" ) .. note:: diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index 992d7c88d6..c6da0633df 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -212,25 +212,16 @@ Users on Level 3 & 4 systems can find the data required for the "out-of-the-box" .. code-block:: console - wget https://ufs-data.s3.amazonaws.com/public_release/ufs-srweather-app-v1.0.0/fix/files.tar.gz + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data tar -xf files.tar.gz -.. - COMMENT: Fix/update path to tar file! - .. _StaticFixFiles: Static Files -------------- -To download the static files: - -.. code-block:: console - - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/ - -This will download *all* static files in the UFS SRW App Data Bucket. Users may adjust the path in the ``wget`` command to select the subset of files they need for their experiment. +Many static files are available in the `"fix" directory `__ of the SRW Data Bucket. If users prefer not to download the tar file with the current release data in :numref:`Section %s ` above, they can download static files individually from the `"fix" directory `__ of the SRW Data Bucket using the ``wget`` command for each required file. The environment variables ``FIXgsm``, ``TOPO_DIR``, and ``SFC_CLIMO_INPUT_DIR`` indicate the path to the directories where the static files are located. After downloading the experiment data, users must set the paths to the files in ``config.sh``. Add the following code or alter the variable paths if they are already listed in the ``config.sh`` file: @@ -241,17 +232,22 @@ the directories where the static files are located. After downloading the experi .. _InitialConditions: -Initial Condition Formats and Source ---------------------------------------- +Inition Condition/Lateral Boundary Condition File Formats and Source +----------------------------------------------------------------------- The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. -To download all available GRIB2 data for the FV3GFS model: +To download the model input data for the 12-hour "out-of-the-box" experiment configuration in ``config.community.sh`` file, run: .. code-block:: console - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/FV3GFS/grib2/ + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/input_model_data/FV3GFS/grib2/2019061518/gfs.t18z.pgrb2.0p25.f000 + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/input_model_data/FV3GFS/grib2/2019061518/gfs.t18z.pgrb2.0p25.f006 + +.. + COMMENT: Add the following line once PR #766 goes through & Data Bucket is updated: + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/input_model_data/FV3GFS/grib2/2019061518/gfs.t18z.pgrb2.0p25.f012 -To download data for different models or in different formats, users can explore the data bucket and replace the link above with one that goes to their desired data. +To download data for different models or in different formats, users can explore the data bucket and replace the links above with ones that fetch their desired data. Initial and Lateral Boundary Condition Organization --------------------------------------------------- @@ -261,8 +257,8 @@ The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBC .. code-block:: console USE_USER_STAGED_EXTRN_FILES="TRUE" - EXTRN_MDL_SOURCE_BASEDIR_ICS="" - EXTRN_MDL_SOURCE_BASEDIR_LBCS="" + 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) and date (in ``YYYYMMDDHH`` format). In addition, users can include separate ICS and LBCS directories. For example: ``/path-to/model_data/FV3GFS/2019061518/ICS`` and ``/path-to/model_data/FV3GFS/2019061518/LBCS``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. diff --git a/docs/UsersGuide/source/Non-ContainerQS.rst b/docs/UsersGuide/source/Non-ContainerQS.rst index d135c30c3f..30b719d161 100644 --- a/docs/UsersGuide/source/Non-ContainerQS.rst +++ b/docs/UsersGuide/source/Non-ContainerQS.rst @@ -56,7 +56,7 @@ For a detailed explanation of how to build and run the SRW App on any supported ./devbuild.sh --platform= - where is replaced with the name of the platform the user is working on. Valid values are: cheyenne | gaea | hera | jet | macos | odin | orion | singularity | wcoss_dell_p3 + where is replaced with the name of the platform the user is working on. Valid values are: ``cheyenne`` | ``gaea`` | ``hera`` | ``jet`` | ``macos`` | ``odin`` | ``orion`` | ``singularity`` | ``wcoss_dell_p3`` * **Option 2:** From b66689964729e48d6d7685418ac8ca5a4e913a57 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 20 May 2022 14:01:02 -0400 Subject: [PATCH 155/158] update error in non-container QS --- docs/UsersGuide/source/Non-ContainerQS.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/UsersGuide/source/Non-ContainerQS.rst b/docs/UsersGuide/source/Non-ContainerQS.rst index 30b719d161..90bb7bda17 100644 --- a/docs/UsersGuide/source/Non-ContainerQS.rst +++ b/docs/UsersGuide/source/Non-ContainerQS.rst @@ -84,11 +84,6 @@ For a detailed explanation of how to build and run the SRW App on any supported #. Download and stage data (both the fix files and the :term:`IC/LBC` files) according to the instructions in :numref:`Chapter %s ` (if on a Level 3-4 system). - .. code-block:: console - - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#fix/ - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/FV3GFS/grib2/2019061518/ - #. Configure the experiment parameters. .. code-block:: console From 90e355e87931a6063deaa5f37b1c3b5409c8063c Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 20 May 2022 14:16:41 -0400 Subject: [PATCH 156/158] add warning for users w/o Rocoto --- docs/UsersGuide/source/BuildRunSRW.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 89ed68e6bf..629210ec27 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -921,6 +921,11 @@ In addition to the baseline tasks described in :numref:`Table %s `__ systems, such as MacOS), they should follow the process outlined in :numref:`Section %s ` instead of the instructions in this section. + The information in this section assumes that Rocoto is available on the desired platform. All official HPC platforms for the UFS SRW App release make use of the Rocoto workflow management software for running experiments. However, Rocoto cannot be used when running the workflow within a container. If Rocoto is not available, it is still possible to run the workflow using stand-alone scripts according to the process outlined in :numref:`Section %s `. There are two main ways to run the workflow with Rocoto: (1) with the ``launch_FV3LAM_wflow.sh`` script, and (2) by manually calling the ``rocotorun`` command. Users can also automate the workflow using a crontab. .. note:: From 5250e86a0c7821301088592798af175f5719ff49 Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 20 May 2022 16:05:35 -0400 Subject: [PATCH 157/158] add UPP Satellite Product instructions --- docs/UsersGuide/source/InputOutputFiles.rst | 35 +++++++++++++++++++-- docs/UsersGuide/source/Introduction.rst | 3 -- 2 files changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/UsersGuide/source/InputOutputFiles.rst b/docs/UsersGuide/source/InputOutputFiles.rst index c6da0633df..8e56abd42a 100644 --- a/docs/UsersGuide/source/InputOutputFiles.rst +++ b/docs/UsersGuide/source/InputOutputFiles.rst @@ -179,6 +179,9 @@ For the SRW Application, the weather model netCDF output files are written to th The default setting for the output file names uses ``rrfs`` for ``{domain}``. This may be overridden by the user in the ``config.sh`` settings. +Modifying the UPP Output +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + If users wish to modify the fields or levels that are output from the UPP, they will need to make modifications to ``fv3lam.xml``, which resides in the UPP repository distributed with the UFS SRW Application. If the code was cloned into the directory ``ufs-srweather-app``, the file will be located in ``ufs-srweather-app/src/UPP/parm``. .. note:: @@ -195,13 +198,41 @@ Once you have created the new flat text file reflecting your changes, you will n .. code-block:: console - USE_CUSTOM_POST_CONFIG_FILE=”TRUE” - CUSTOM_POST_CONFIG_PATH=”” + USE_CUSTOM_POST_CONFIG_FILE="TRUE" + CUSTOM_POST_CONFIG_PATH="" which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If this is set to true, and the file path is not found, then an error will occur when trying to generate the SRW Application workflow. Users may then start their experiment workflow as usual and the UPP will use the new flat ``*.txt`` file. +.. _SatelliteProducts: + +Outputting Satellite Products from UPP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Synthetic satellite products for several instruments and channels (e.g. GOES 16/17) may be output through the UPP using the Community Radiative Transfer Model (:term:`CRTM`). External CRTM coefficient files, available through the UPP stand-alone release, will need to be manually downloaded before running the workflow. These instructions assume that the UPP configuration file has already been set up to output satellite products. + +Download and unpack the external files: + +.. code-block:: console + + mkdir crtm && cd crtm + wget https://github.com/NOAA-EMC/EMC_post/releases/download/upp_v10.1.0/fix.tar.gz + tar -xzf fix.tar.gz + +Modify the ``config.sh`` file to include the following lines: + +.. code-block:: console + + USE_CRTM="TRUE" + CRTM_DIR="/path/to/top/crtm/dir" + +By setting ``USE_CRTM`` to "TRUE", the workflow will use the path defined in ``CRTM_DIR`` to link the necessary coefficient files to the working directory at runtime. Otherwise, it is assumed that no satellite fields are being requested in the UPP configuration. ``CRTM_DIR`` should point to the top CRTM directory where the fix files are located. + +.. note:: + Dependencies for outputting synthetic satellite products may exist based on model configuration (e.g. model physics). + + .. _DownloadingStagingInput: Downloading and Staging Input Data diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index c66f39b391..603236cce3 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -124,9 +124,6 @@ The following software is also required to run the SRW Application, but the :ter * libPNG * zlib -.. - COMMENT: Update version of ESMF? Need other version updates? - For MacOS systems, some additional software is needed. It is recommended that users install this software using the `Homebrew `__ package manager for MacOS: * brew install gcc@11 From a2cb4b79a4733844065f309f913b5e023c3ffddd Mon Sep 17 00:00:00 2001 From: gspetro Date: Fri, 20 May 2022 16:22:58 -0400 Subject: [PATCH 158/158] Xlink for UPP satellite output info --- docs/UsersGuide/source/ConfigWorkflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index ee42848779..9fcfbd8b11 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -1276,7 +1276,7 @@ Customized Post Configuration Parameters Community Radiative Transfer Model (CRTM) Parameters ======================================================= -These variables set parameters associated with outputting satellite fields in the :term:`UPP` :term:`grib2` files using the Community Radiative Transfer Model (:term:`CRTM`). +These variables set parameters associated with outputting satellite fields in the :term:`UPP` :term:`grib2` files using the Community Radiative Transfer Model (:term:`CRTM`). :numref:`Section %s ` includes further instructions on how to do this. .. COMMENT: What actually happens here? Where are the satellite fields outputted to? When/why would this be used? What kind of satellites?