From ff80851db49586cab9626c67d82355688fff8229 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 5 Jul 2023 10:15:47 -0400 Subject: [PATCH 001/116] update FAQ --- docs/UsersGuide/source/FAQ.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/UsersGuide/source/FAQ.rst b/docs/UsersGuide/source/FAQ.rst index 35d60797ec..ac981081b2 100644 --- a/docs/UsersGuide/source/FAQ.rst +++ b/docs/UsersGuide/source/FAQ.rst @@ -11,6 +11,8 @@ FAQ * :ref:`How do I restart a DEAD task? ` * :ref:`How can I clean up the SRW App code if something went wrong? ` * :ref:`How do I run a new experiment? ` +* :ref:`How can I add a physics scheme (e.g., YSU PBL) to the UFS SRW App? ` +* :ref:`How can I troubleshoot issues related to ICS/LBCS generation for a predefined 3-km grid? ` .. _DefineExptName: @@ -171,3 +173,29 @@ To run a new experiment at a later time, users need to rerun the commands in :nu Follow any instructions output by the console. Then, users can configure a new experiment by updating the environment variables in ``config.yaml`` to reflect the desired experiment configuration. Detailed instructions can be viewed in :numref:`Section %s `. Parameters and valid values are listed in :numref:`Chapter %s `. After adjusting the configuration file, generate the new experiment by running ``./generate_FV3LAM_wflow.py``. Check progress by navigating to the ``$EXPTDIR`` and running ``rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10``. + +.. _AddPhys: + +==================================================================== +How can I add a physics scheme (e.g., YSU PBL) to the UFS SRW App? +==================================================================== + +At this time, there are ten physics suites available in the SRW App, :ref:`five of which are fully supported `. However, several additional physics schemes are available in the UFS Weather Model (WM) and can be enabled in the SRW App. +To enable an additional physics scheme, such as the YSU PBL scheme, users must modify ``ufs-srweather-app/parm/FV3.input.yml`` and set the variable corresponding to the desired physics scheme to True under the physics suite they would like to use (e.g., ``do_ysu = True``). + +It may be necessary to disable another physics scheme, too. For example, when using the YSU PBL scheme, users should disable the default SATMEDMF PBL scheme (*satmedmfvdifq*) by setting the ``satmedmf`` variable to False in the ``FV3.input.yml`` file. +Regardless, users will need to modify the suite definition file (SDF) and recompile the code. For example, to activate the YSU PBL scheme, users should replace the line ``satmedmfvdifq`` with ``ysuvdif`` and recompile the code. + +Users must ensure that they are using the same physics suite in their ``config.yaml`` file as the one they modified in ``FV3.input.yml``. Then, the user can run the ``generate_FV3LAM_wflow.py`` script to generate an experiment and navigate to the experiment directory. They should see ``do_ysu = .true.`` in the namelist file (or a similar statement, depending on the physics scheme selected), which indicates that the YSU PBL scheme is enabled. + +.. _IC-LBC-gen-issue: + +========================================================================================================== +How can I troubleshoot issues related to :term:`ICS`/:term:`LBCS` generation for a predefined 3-km grid? +========================================================================================================== + +If you encounter issues while generating ICS and LBCS for a predefined 3-km grid using the UFS SRW App, there are a number of troubleshooting options. The first step is always to check the log file for a failed task. This file will provide information on what went wrong. A log file for each task appears in the ``log`` subdirectory of the experiment directory (e.g., ``$EXPTDIR/log/make_ics``). + +Additionally, users can try increasing the number of processors or the wallclock time requested for the jobs. Sometimes jobs may fail without errors because the process is cut short. These settings can be adusted in one of the ``ufs-srweather-app/parm/wflow`` files. For ICs/LBCs tasks, these parameters are set in the ``coldstart.yaml`` file. + +Users can also update the hash of UFS_UTILS in the ``Externals.cfg`` file to the HEAD of that repository. There was a known memory issue with how ``chgres_cube`` was handling regridding of the 3-D wind field for large domains at high resolutions (see `UFS_UTILS PR #766 `__ and the associated issue for more information). If changing the hash in ``Externals.cfg``, users will need to rerun ``manage_externals`` and rebuild the code (see :numref:`Chapter %s `). \ No newline at end of file From 82b2e52e2a7cf9af1f62c527e407286335109b4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 5 Jul 2023 16:08:21 -0400 Subject: [PATCH 002/116] split up/revise Intro; reorg chapters --- docs/UsersGuide/source/Introduction.rst | 424 ++----------------- docs/UsersGuide/source/TechnicalOverview.rst | 368 ++++++++++++++++ docs/UsersGuide/source/index.rst | 11 +- 3 files changed, 419 insertions(+), 384 deletions(-) create mode 100644 docs/UsersGuide/source/TechnicalOverview.rst diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index d8dd8e68a8..0c874c757d 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -6,415 +6,81 @@ 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` (including 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 v2.1.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 the `GitHub Discussions `__ forum. New and improved capabilities for the v2.0.0 release included the addition of a verification package (METplus) for both deterministic and ensemble simulations and support for four stochastically perturbed physics schemes. Additions for the v2.1.0 release included: +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 most recent SRW Application 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 the `GitHub Discussions `__ forum. The SRW App also includes support for a verification package (METplus) for both deterministic and ensemble simulations and support for four stochastically perturbed physics schemes. - * Bug fixes since the v2.0.0 release - * Conversion to a Python workflow (from the former shell workflow) - * Improved container support, including the option to run across compute nodes using Rocoto (see :numref:`Chapter %s `) - * Updates to :term:`CCPP` that target the top of the ``main`` branch (which is ahead of CCPP v6.0.0). See :ref:`this page ` for a detailed summary of updates. +Since the v2.1.0 release, developers have added a variety of features: + + * Bug fixes since the v2.1.0 release + * Rapid Refresh Forecast System (RRFS) capabilities + * Air Quality Modeling (AQM) capabilities + * Updates to :term:`CCPP` that target the top of the ``main`` branch (which is ahead of CCPP v6.0.0). See :ref:`this page ` for a detailed summary of updates that came in ahead of the v2.1.0 release. * Support for the :term:`UPP` inline post option (see :ref:`here `) - * Addition of a multi-purpose code clean-up script (``devclean.sh``) (see :numref:`Section %s `) * Documentation updates to reflect the changes above -This documentation provides: - - * A :ref:`Quick Start Guide ` designed for use on `Level 1 systems `__ or as an overview of the workflow - * A :ref:`Container-Based Quick Start Guide ` for running the SRW Application in a container - * Detailed chapters on :ref:`building ` and :ref:`running ` the SRW App on any supported platform - * An overview of the :ref:`release components ` and details on how to customize or modify different portions of the workflow - The SRW App v2.1.0 citation is as follows and should be used when presenting results based on research conducted with the App: UFS Development Team. (2022, Nov. 17). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.1.0). Zenodo. https://doi.org/10.5281/zenodo.7277602 -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 `GitHub Discussions `__ forum. - -.. code-block:: console - - Throughout the guide, this presentation style indicates shell commands and options, code examples, etc. +Organization of SRW App Documentation +======================================== -Variables presented as ``AaBbCc123`` in this User's Guide typically refer to variables in scripts, names of files, or directories. - -File paths and code that include angle brackets (e.g., ``build__``) indicate that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). +The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Technical Information*; and *Reference*. .. hint:: - * To get started with the SRW App, users have a few options: + * To get started with the SRW App, users can try one of the following options: #. View :numref:`Chapter %s ` for a quick overview of the workflow steps. #. To build the application in a container, which provides a more uniform work environment, users can refer to the :ref:`Container-Based Quick Start Guide `. #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Chapter %s: Building the SRW App ` and :numref:`Chapter %s: Running the SRW App `. - * 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. - - -.. _SRWPrerequisites: - -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 (concepts of parameterizations: physical, microphysical, convective) -* Meteorology (in particular, meteorology at the scales being predicted: 25km, 13km, and 3km resolutions) - -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. SRW App `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 - -* >82 GB disk space - - * 53 GB input data for a standard collection of global data, or "fix" file data (topography, climatology, observational data) for a short 12-hour test forecast on the :term:`CONUS` 25km domain. See data download instructions in :numref:`Section %s `. - * 8 GB for full :term:`HPC-Stack` installation - * 3 GB for ``ufs-srweather-app`` installation - * 1 GB for boundary conditions for a short 12-hour test forecast on the CONUS 25km domain. See data download instructions in :numref:`Section %s `. - * 17 GB for a 12-hour test forecast on the CONUS 25km domain, with model output saved hourly. - -* Fortran compiler released since 2018 - - * 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, LLVM clang, GNU) 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 v2.12+ - -* curl - -* wget - -* Lmod - +Background Information +------------------------ -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: + * This **Introduction** chapter explains how the SRW App documentation is organized, how to use this guide, and where to find user support/documentation. + * :numref:`Chapter %s: Technical Overview ` provides a technical overview, including SRW App prerequisites, code overview/directory structure, and summary of components. + * :numref:`Chapter %s: Components ` provides a more detailed description of the application components, including optional application components. -* CMake v3.20+ +Building, Running, and Testing the SRW App +-------------------------------------------- -* :term:`MPI` (MPICH, OpenMPI, or other implementation) + * :numref:`Chapter %s: Quick Start Guide ` is designed for use on `Level 1 systems `__ or as an overview of the workflow. + * :numref:`Chapter %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers come with SRW App prerequisites already installed and run on a broad range of systems. + * :numref:`Chapter %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. + * :numref:`Chapter %s: Running the SRW App ` provides a *detailed* explanation of how to run the App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. + * :numref:`Chapter %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. + * :numref:`Chapter %s ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. + * :numref:`Chapter %s ` explains how to run METplus verification as part of the workflow. + * :numref:`Chapter %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this chapter is a starting point for those interested in AQM. - * Only **MPICH** or **OpenMPI** can be built with HPC-Stack. Other implementations must be installed separately by the user (if desired). +Technical Information for Users +--------------------------------- -For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew `__ package manager for MacOS. See :doc:`HPC-Stack Documentation: Chapter 3 ` and :numref:`Chapter %s ` for further guidance on installing these prerequisites on MacOS. + * :numref:`Chapter %s ` documents all of the user-configurable experiment parameters that can be set in ``config.yaml``. + * :numref:`Chapter %s ` provides information on application input and output files, as well as information on where to get publicly available data. + * :numref:`Chapter %s ` describes the SRW App predefined grids in detail and explains how to create a custom user-generated grid. + * :numref:`Chapter %s ` explains how to build or alter the SRW App workflow XML file. + * :numref:`Chapter %s ` explains how to use template variables. -* bash v4.x -* GNU compiler suite v11 or higher with gfortran -* cmake -* make -* coreutils -* gsed +Reference Information +----------------------- -Optional but recommended prerequisites for all systems: + * :numref:`Chapter %s: Rocoto Introductory Information ` provides an introduction to standard Rocoto commands with examples. + * :numref:`Chapter %s: FAQ ` answers users' frequently asked questions. + * :numref:`Chapter %s: Glossary ` defines important terms related to the SRW App. -* 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 -.. _ComponentsOverview: - -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. Additional information about the pre-processor utilities can be found in :numref:`Chapter %s `, in the `UFS_UTILS Technical Documentation `__, and in the `UFS_UTILS Scientific Documentation `__. - -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 (:term:`LAM`) capability (:cite:t:`BlackEtAl2021`). The :term:`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 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 most recent SRW App release includes four supported physics suites. - -Data Format -^^^^^^^^^^^^^^^^^^^^^^ - -The SRW App supports the use of external model data in :term:`GRIB2`, :term:`NEMSIO`, and :term:`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 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 `__. - -METplus Verification Suite ------------------------------- - -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 `__. - -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 the `Rocoto documentation `__ for more on workflow management). Individual workflow tasks 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 used for the simulation. More information on how to do this is available in :numref:`Section %s `. - -The SRW Application 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 available in a central location (via :term:`HPC-Stack`). 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 (Levels 2-4), the SRW App can be :ref:`run within a container ` that includes the prerequisite software; otherwise, 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. - - - -.. _SRWStructure: - -Code Repositories and Directory Structure -========================================= - -.. _HierarchicalRepoStr: - -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 tags the appropriate versions of the external repositories associated with the SRW App (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 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, which are documented `here `__. - -.. note:: - The prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The `HPC-Stack `__ repository assembles these prerequisite libraries. The HPC-Stack has already been built on `preconfigured (Level 1) platforms `__. However, it must be built on other systems. See the :doc:`HPC-Stack Documentation ` for details on installing the HPC-Stack. - - -.. _TopLevelDirStructure: +How to Use This Document +======================== -Directory Structure ----------------------- -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 (see :numref:`Section %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. +This guide instructs both novice and experienced users on downloading, building, and running the SRW Application. Please post questions in the `GitHub Discussions `__ forum. .. code-block:: console - ufs-srweather-app - ├── (build) - ├── docs - │ └── UsersGuide - ├── etc - ├── (exec) - ├── (include) - ├── jobs - ├── (lib) - ├── manage_externals - ├── modulefiles - ├── parm - ├── (share) - ├── scripts - ├── sorc - │ ├── CMakeLists.txt - │ ├── (gsi) - │ ├── (rrfs_utl) - │ ├── (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 - ├── tests/WE2E - ├── ush - │ ├── bash_utils - │ ├── machine - │ ├── Python - │ ├── python_utils - │ ├── test_data - │ └── wrappers - └── versions - -SRW App SubDirectories -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:numref:`Table %s ` describes the contents of the most important subdirectories. :numref:`Table %s ` provides an in-depth explanation of the ``ufs-srweather-app`` directories. - -.. _Subdirectories: - -.. table:: Subdirectories of the regional workflow - - +-------------------------+----------------------------------------------------+ - | **Directory Name** | **Description** | - +=========================+====================================================+ - | jobs | J-job scripts launched by Rocoto | - +-------------------------+----------------------------------------------------+ - | modulefiles | Files used to load modules needed for building and | - | | running the workflow | - +-------------------------+----------------------------------------------------+ - | scripts | Scripts launched by the J-jobs | - +-------------------------+----------------------------------------------------+ - | tests | Tests for baseline experiment configurations | - +-------------------------+----------------------------------------------------+ - | ush | Utility scripts used by the workflow | - +-------------------------+----------------------------------------------------+ - -.. _ExperimentDirSection: - -Experiment Directory Structure --------------------------------- -When the user generates an experiment using the ``generate_FV3LAM_wflow.py`` script (:numref:`Step %s `), a user-defined experiment directory (``$EXPTDIR``) is created based on information specified in the ``config.yaml`` file. :numref:`Table %s ` shows the contents of the experiment directory before running the experiment workflow. - -.. _ExptDirStructure: - -.. table:: Files and subdirectory initially created in the experiment directory - :widths: 33 67 - - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | **File Name** | **Description** | - +===========================+==============================================================================================================+ - | config.yaml | User-specified configuration file, see :numref:`Section %s ` | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | data_table | :term:`Cycle-independent` input file (empty) | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | field_table | :term:`Tracers ` in the `forecast model | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | input.nml | :term:`Namelist` for the `UFS Weather Model | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | launch_FV3LAM_wflow.sh | Symlink to the ``ufs-srweather-app/ush/launch_FV3LAM_wflow.sh`` shell script, | - | | which can be used to (re)launch the Rocoto workflow. | - | | Each time this script is called, it appends information 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.py``) | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | nems.configure | See `NEMS configuration file | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | suite_{CCPP}.xml | :term:`CCPP` suite definition file (:term:`SDF`) 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, running the SRW App in *community* mode creates the ``fix_am`` and ``fix_lam`` directories (see :numref:`Table %s `) 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 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 symlinks | - | | 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 Rocoto workflow is launched, several files and directories are generated. A log file named ``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_lbcs``) are preprocessing tasks, and these tasks also result in the creation of new files and subdirectories, 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 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 in the ``config.yaml`` file, more than one cycle | - | | directory will be created under the experiment directory. | - +---------------------------+--------------------------------------------------------------------+ - | 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 by its | - | | various tasks. View the files in this directory to determine 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 | The ``launch_FV3LAM_wflow.sh`` script appends its output to this | - | | log file each time it is called. View the last several | - | | 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 `. + Throughout the guide, this presentation style indicates shell commands and options, code examples, etc. + +Variables presented as ``AaBbCc123`` in this User's Guide typically refer to variables in scripts, names of files, or directories. +File paths and code that include angle brackets (e.g., ``build__``) indicate that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). User Support, Documentation, and Contributions to Development =============================================================== diff --git a/docs/UsersGuide/source/TechnicalOverview.rst b/docs/UsersGuide/source/TechnicalOverview.rst new file mode 100644 index 0000000000..4504b8cbf8 --- /dev/null +++ b/docs/UsersGuide/source/TechnicalOverview.rst @@ -0,0 +1,368 @@ +.. _TechOverview: + +==================== +Technical Overview +==================== + +.. _SRWPrerequisites: + +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 (concepts of parameterizations: physical, microphysical, convective) +* Meteorology (in particular, meteorology at the scales being predicted: 25km, 13km, and 3km resolutions) + +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. SRW App `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 + +* >82 GB disk space + + * 53 GB input data for a standard collection of global data, or "fix" file data (topography, climatology, observational data) for a short 12-hour test forecast on the :term:`CONUS` 25km domain. See data download instructions in :numref:`Section %s `. + * 8 GB for full :term:`HPC-Stack` installation + * 3 GB for ``ufs-srweather-app`` installation + * 1 GB for boundary conditions for a short 12-hour test forecast on the CONUS 25km domain. See data download instructions in :numref:`Section %s `. + * 17 GB for a 12-hour test forecast on the CONUS 25km domain, with model output saved hourly. + +* Fortran compiler released since 2018 + + * 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, LLVM clang, GNU) 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 v2.12+ + +* curl + +* wget + +* Lmod + + +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.20+ + +* :term:`MPI` (MPICH, OpenMPI, or other implementation) + + * Only **MPICH** or **OpenMPI** can be built with HPC-Stack. Other implementations must be installed separately by the user (if desired). + +For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew `__ package manager for MacOS. See :doc:`HPC-Stack Documentation: Chapter 3 ` and :numref:`Chapter %s ` for further guidance on installing these prerequisites on MacOS. + +* bash v4.x +* GNU compiler suite v11 or higher with gfortran +* cmake +* make +* coreutils +* gsed + +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 + +.. _ComponentsOverview: + +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. Additional information about the pre-processor utilities can be found in :numref:`Chapter %s `, in the `UFS_UTILS Technical Documentation `__, and in the `UFS_UTILS Scientific Documentation `__. + +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 (:term:`LAM`) capability (:cite:t:`BlackEtAl2021`). The :term:`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 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 most recent SRW App release includes four supported physics suites. + +Data Format +^^^^^^^^^^^^^^^^^^^^^^ + +The SRW App supports the use of external model data in :term:`GRIB2`, :term:`NEMSIO`, and :term:`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 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 `__. + +METplus Verification Suite +------------------------------ + +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 `__. + +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 the `Rocoto documentation `__ for more on workflow management). Individual workflow tasks 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 used for the simulation. More information on how to do this is available in :numref:`Section %s `. + +The SRW Application 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 available in a central location (via :term:`HPC-Stack`). 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 (Levels 2-4), the SRW App can be :ref:`run within a container ` that includes the prerequisite software; otherwise, 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. + +.. _SRWStructure: + +Code Repositories and Directory Structure +========================================= + +.. _HierarchicalRepoStr: + +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 tags the appropriate versions of the external repositories associated with the SRW App (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 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, which are documented `here `__. + +.. note:: + The prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The `HPC-Stack `__ repository assembles these prerequisite libraries. The HPC-Stack has already been built on `preconfigured (Level 1) platforms `__. However, it must be built on other systems. See the :doc:`HPC-Stack Documentation ` for details on installing the HPC-Stack. + + +.. _TopLevelDirStructure: + +Directory Structure +---------------------- +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 (see :numref:`Section %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 + ├── (build) + ├── docs + │ └── UsersGuide + ├── etc + ├── (exec) + ├── (include) + ├── jobs + ├── (lib) + ├── manage_externals + ├── modulefiles + ├── parm + ├── (share) + ├── scripts + ├── sorc + │ ├── CMakeLists.txt + │ ├── (gsi) + │ ├── (rrfs_utl) + │ ├── (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 + ├── tests/WE2E + ├── ush + │ ├── bash_utils + │ ├── machine + │ ├── Python + │ ├── python_utils + │ ├── test_data + │ └── wrappers + └── versions + +SRW App SubDirectories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:numref:`Table %s ` describes the contents of the most important subdirectories. :numref:`Table %s ` provides an in-depth explanation of the ``ufs-srweather-app`` directories. + +.. _Subdirectories: + +.. table:: Subdirectories of the regional workflow + + +-------------------------+----------------------------------------------------+ + | **Directory Name** | **Description** | + +=========================+====================================================+ + | jobs | J-job scripts launched by Rocoto | + +-------------------------+----------------------------------------------------+ + | modulefiles | Files used to load modules needed for building and | + | | running the workflow | + +-------------------------+----------------------------------------------------+ + | scripts | Scripts launched by the J-jobs | + +-------------------------+----------------------------------------------------+ + | tests | Tests for baseline experiment configurations | + +-------------------------+----------------------------------------------------+ + | ush | Utility scripts used by the workflow | + +-------------------------+----------------------------------------------------+ + +.. _ExperimentDirSection: + +Experiment Directory Structure +-------------------------------- +When the user generates an experiment using the ``generate_FV3LAM_wflow.py`` script (:numref:`Step %s `), a user-defined experiment directory (``$EXPTDIR``) is created based on information specified in the ``config.yaml`` file. :numref:`Table %s ` shows the contents of the experiment directory before running the experiment workflow. + +.. _ExptDirStructure: + +.. table:: Files and subdirectory initially created in the experiment directory + :widths: 33 67 + + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | **File Name** | **Description** | + +===========================+==============================================================================================================+ + | config.yaml | User-specified configuration file, see :numref:`Section %s ` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | data_table | :term:`Cycle-independent` input file (empty) | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | field_table | :term:`Tracers ` in the `forecast model | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | input.nml | :term:`Namelist` for the `UFS Weather Model | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | launch_FV3LAM_wflow.sh | Symlink to the ``ufs-srweather-app/ush/launch_FV3LAM_wflow.sh`` shell script, | + | | which can be used to (re)launch the Rocoto workflow. | + | | Each time this script is called, it appends information 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.py``) | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | nems.configure | See `NEMS configuration file | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | suite_{CCPP}.xml | :term:`CCPP` suite definition file (:term:`SDF`) 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, running the SRW App in *community* mode creates the ``fix_am`` and ``fix_lam`` directories (see :numref:`Table %s `) 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 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 symlinks | + | | 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 Rocoto workflow is launched, several files and directories are generated. A log file named ``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_lbcs``) are preprocessing tasks, and these tasks also result in the creation of new files and subdirectories, 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 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 in the ``config.yaml`` file, more than one cycle | + | | directory will be created under the experiment directory. | + +---------------------------+--------------------------------------------------------------------+ + | 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 by its | + | | various tasks. View the files in this directory to determine 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 | The ``launch_FV3LAM_wflow.sh`` script appends its output to this | + | | log file each time it is called. View the last several | + | | 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/index.rst b/docs/UsersGuide/source/index.rst index 1a51b34552..ffdc5dae13 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -12,20 +12,21 @@ UFS Short-Range Weather App Users Guide Introduction + TechnicalOverview + Components Quickstart ContainerQuickstart BuildSRW RunSRW Tutorial + WE2Etests + VXCases AQM - Components + ConfigWorkflow InputOutputFiles LAMGrids - ConfigWorkflow - RocotoInfo DefineWorkflow - WE2Etests TemplateVars - VXCases + RocotoInfo FAQ Glossary From b905241591d82fc1c8a91891d074608639fb24c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 5 Jul 2023 17:13:38 -0400 Subject: [PATCH 003/116] update components section; also monor updates to intro, tech ov, glossary --- docs/UsersGuide/source/Components.rst | 69 +++++++++++++++----- docs/UsersGuide/source/Glossary.rst | 4 +- docs/UsersGuide/source/Introduction.rst | 14 ++-- docs/UsersGuide/source/TechnicalOverview.rst | 51 +-------------- 4 files changed, 62 insertions(+), 76 deletions(-) diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index b5e03eec85..621ff91edd 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 t 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 :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3`-:term:`LAM`. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS Technical Documentation `__ and in the `UFS_UTILS Scientific Documentation `__. +The SRW Application includes a number of pre-processing utilities (UFS_UTILS) that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), these utilities 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 :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3`-:term:`LAM`. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS Technical Documentation `__ and in the `UFS_UTILS Scientific Documentation `__. 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. @@ -30,30 +30,33 @@ The SRW Application can be initialized from a range of operational initial condi 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:`BlackEtAl2021`. The :term:`dynamical core` is the computational part of a model that solves the equations of fluid motion. A User's Guide for the UFS Weather Model can be accessed `here `__. +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:t:`BlackEtAl2021`). The :term:`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 accessed `here `__. Supported model resolutions in this release include 3-, 13-, and 25-km predefined contiguous U.S. (:term:`CONUS`) domains, each with 127 vertical levels. Preliminary tools for users to define their own domain are also available in the release with full, formal support of these tools to be provided in future releases. The Extended Schmidt Gnomonic (ESG) grid is used with the FV3-LAM, which features relatively uniform grid cells across the entirety of the domain. Additional information about the FV3 dynamical core can be found in the `scientific documentation `__, the `technical documentation `__, and on the `NOAA Geophysical Fluid Dynamics Laboratory website `__. -Interoperable atmospheric physics, along with various land surface model options, are supported through the Common Community Physics Package (CCPP), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There are four physics suites supported as of the SRW App v2.1.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 (:term:`RRFS`) planned for 2023-2024, and the second is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. Additionally, FV3_WoFS_v0, FV3_HRRR, and FV3_RAP are supported. A detailed list of CCPP updates since the SRW App v2.0.0 release is available :ref:`here `. A full scientific description of CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. Additionally, a CCPP single-column model (`CCPP-SCM `__) option has also been developed as a child repository. Users can refer to the `CCPP Single Column Model User and Technical Guide `__ for more details. This CCPP-SCM user guide contains a Quick Start Guide with instructions for obtaining the code, compiling, and running test cases, which include five standard test cases and two additional FV3 replay cases (refer to section 5.2 in the CCPP-SCM user guide for more details). Moreover, the CCPP-SCM supports a precompiled version in a docker container, allowing it to be easily executed on NOAA's cloud computing platforms without any issues (see section 2.5 in the CCPP-SCM user guide for more details). +Model Physics +--------------- + +The Common Community Physics Package (CCPP), described `here `__, 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 most recent SRW App release (v2.1.0) included four supported physics suites, and a fifth has since been added: FV3_RRFS_v1beta, FV3_GFS_v16, FV3_WoFS_v0, FV3_HRRR, and FV3_RAP (new!). The FV3_RRFS_v1beta physics suite is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (:term:`RRFS`) planned for 2023-2024, and the FV3_GFS_v16 is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. A detailed list of CCPP updates since the SRW App v2.0.0 release is available :ref:`here `. A full scientific description of CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. Additionally, a CCPP single-column model (`CCPP-SCM `__) option has also been developed as a child repository. Users can refer to the `CCPP Single Column Model User and Technical Guide `__ for more details. This CCPP-SCM user guide contains a Quick Start Guide with instructions for obtaining the code, compiling, and running test cases, which include five standard test cases and two additional FV3 replay cases (refer to section 5.2 in the CCPP-SCM user guide for more details). Moreover, the CCPP-SCM supports a precompiled version in a docker container, allowing it to be easily executed on NOAA's cloud computing platforms without any issues (see section 2.5 in the CCPP-SCM user guide for more details). .. note:: SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which physics suite definition file (:term:`SDF`) is chosen when turning this option on. Among the supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. 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 `__. +Unified Post Processor (UPP) +============================== -Output from UPP can be used with visualization, plotting, and verification packages or in 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, the UPP converts model output data from the model's native :term:`netCDF` format 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). .. _MetplusComponent: 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) `__. +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. + +The METplus verification framework 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) `__. METplus *installation* is not included as part of the build process for the most recent release of the SRW App. However, METplus is preinstalled on many `Level 1 & 2 `__ systems; existing builds can be viewed `here `__. @@ -63,24 +66,54 @@ The core components of the METplus framework include the statistical driver, MET 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 (which include conventional point-based surface and upper-air data) in `prepBUFR format `__ 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 (:term:`EMC`), and it is open to community contributions. +METplus is being actively developed by :term:`NCAR`/Research Applications Laboratory (RAL), NOAA/Earth Systems Research Laboratories (ESRL), and NOAA/Environmental Modeling Center (:term:`EMC`), and it is open to community contributions. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. + +AQM Utilities +=============== + +https://github.com/NOAA-EMC/AQM-utils + +NOAA Emission and Exchange Unified System (NEXUS) +=================================================== + +https://github.com/noaa-oar-arl/NEXUS + +Gridpoint Statistical Interpolation (GSI) +============================================ + +https://github.com/NOAA-EMC/GSI + +RRFS Utilities +================ + +https://github.com/NOAA-GSL/rrfs_utl + +Unified Workflow Tools +======================== + +https://github.com/ufs-community/workflow-tools + 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, CMake-based build system that packages together all the components required to build the SRW Application. This build system collects the components necessary for running the end-to-end SRW Application, including the UFS Weather Model and the pre- and post-processing software. Additional libraries necessary for the application (e.g., :term:`NCEPLIBS-external` and :term:`NCEPLIBS`) are not included in the SRW Application build system but are available pre-built on pre-configured platforms. On other systems, they can be installed via the HPC-Stack (see :doc:`HPC-Stack Documentation `). There is a small set of system libraries and utilities that are assumed to be present on the target computer: the CMake build software; a Fortran, C, and C++ compiler; and an :term:`MPI` library. -An umbrella CMake-based build system is used for building the components necessary for running the end-to-end SRW Application, including the UFS Weather Model and the pre- and post-processing software. Additional libraries necessary for the application (e.g., :term:`NCEPLIBS-external` and :term:`NCEPLIBS`) are not included in the SRW Application build system but are available pre-built on pre-configured platforms. On other systems, they can be installed via the HPC-Stack (see :doc:`HPC-Stack Documentation `). There is a small set of system libraries and utilities that are assumed to be present on the target computer: the CMake build software; a Fortran, C, and C++ compiler; and an :term:`MPI` library. +Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see :numref:`Chapter %s ` or the `Rocoto documentation `__ for more information on Rocoto and workflow management). 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. -Once built, the provided experiment generator script can be used to create a Rocoto-based -workflow file that will run each task in the system in the proper sequence (see :numref:`Chapter %s ` or the `Rocoto documentation `__ for more information on Rocoto). If Rocoto and/or a batch system is not present on the available platform, the individual components can be run in a stand-alone, command line fashion with provided run scripts. The generated namelist for the atmospheric model can be modified in order to vary settings such as forecast starting and ending dates, forecast length hours, the :term:`CCPP` physics suite, integration time step, history file output frequency, and more. It also allows for configuration of other elements of the workflow; for example, users can choose whether to run some or all of the pre-processing, forecast model, and post-processing steps. +The SRW Application allows users to configure various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, integration time step, and the physics suite used for the simulation. It also allows for configuration of other elements of the workflow; for example, users can choose whether to run some or all of the pre-processing, forecast model, and post-processing steps. More information on how to configure the workflow is available in :numref:`Section %s `. An optional Python plotting task is also included to create basic visualizations of the model output. The task outputs graphics in PNG format for several standard meteorological variables on the pre-defined :term:`CONUS` domain. A difference plotting option is also included to visually compare two runs for the same domain and resolution. These plots may be used to perform a visual check to verify that the application is producing reasonable results. Configuration instructions are provided in :numref:`Section %s `. -The latest 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; the National Center for Atmospheric Research (:term:`NCAR`) Cheyenne 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 (Level 3), and build-only (Level 4) platforms. Each level is further described below. +The SRW Application has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g., Hera, Orion, Jet); the National Center for Atmospheric Research (:term:`NCAR`) Cheyenne system; cloud environment, 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 (Level 3), and build-only (Level 4) platforms. + +Preconfigured (Level 1) systems already have the required external libraries available in a central location (via :term:`HPC-Stack` or :term:`spack-stack`). 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. + +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. Users will need to install the required libraries as part of the :ref:`SRW Application build ` process. Applications and models are expected to build and run once the required libraries are built. Release testing is conducted on these systems to ensure that the SRW App runs smoothly there. + +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. 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. -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. +On all platforms, the SRW App can be :ref:`run within a container ` that includes the prerequisite software. -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. +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 `__. -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 `__. diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 81dd82adb7..3dbecebbb2 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -245,8 +245,8 @@ Glossary Helicity measures the rotation in a storm's updraft (rising) air. Significant rotation increases the probability that the storm will produce severe weather, including tornadoes. See http://ww2010.atmos.uiuc.edu/(Gh)/guides/mtr/svr/modl/fcst/params/hel.rxml for more details on updraft helicity. 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 :term:`NWP` models, including the :term:`FV3`. + 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 :term:`NWP` models, including the :term:`FV3`. See https://epic.noaa.gov/unified-post-processor/ for more information. 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. diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 0c874c757d..a210c6f57d 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -48,18 +48,18 @@ Building, Running, and Testing the SRW App * :numref:`Chapter %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. * :numref:`Chapter %s: Running the SRW App ` provides a *detailed* explanation of how to run the App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. * :numref:`Chapter %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. - * :numref:`Chapter %s ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. - * :numref:`Chapter %s ` explains how to run METplus verification as part of the workflow. + * :numref:`Chapter %s: ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. + * :numref:`Chapter %s: ` explains how to run METplus verification as part of the workflow. * :numref:`Chapter %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this chapter is a starting point for those interested in AQM. Technical Information for Users --------------------------------- - * :numref:`Chapter %s ` documents all of the user-configurable experiment parameters that can be set in ``config.yaml``. - * :numref:`Chapter %s ` provides information on application input and output files, as well as information on where to get publicly available data. - * :numref:`Chapter %s ` describes the SRW App predefined grids in detail and explains how to create a custom user-generated grid. - * :numref:`Chapter %s ` explains how to build or alter the SRW App workflow XML file. - * :numref:`Chapter %s ` explains how to use template variables. + * :numref:`Chapter %s: ` documents all of the user-configurable experiment parameters that can be set in ``config.yaml``. + * :numref:`Chapter %s: ` provides information on application input and output files, as well as information on where to get publicly available data. + * :numref:`Chapter %s: ` describes the SRW App predefined grids in detail and explains how to create a custom user-generated grid. + * :numref:`Chapter %s: ` explains how to build or alter the SRW App workflow XML file. + * :numref:`Chapter %s: ` explains how to use template variables. Reference Information ----------------------- diff --git a/docs/UsersGuide/source/TechnicalOverview.rst b/docs/UsersGuide/source/TechnicalOverview.rst index 4504b8cbf8..4eb03e3c7a 100644 --- a/docs/UsersGuide/source/TechnicalOverview.rst +++ b/docs/UsersGuide/source/TechnicalOverview.rst @@ -4,6 +4,8 @@ Technical Overview ==================== +This chapter provides information on SRW App prerequistes, code repositories, and directory structure. + .. _SRWPrerequisites: Prerequisites for Using the SRW Application @@ -92,55 +94,6 @@ Optional but recommended prerequisites for all systems: * Rocoto Workflow Management System (1.3.1) * Python packages ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``, and ``pillow`` for graphics -.. _ComponentsOverview: - -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. Additional information about the pre-processor utilities can be found in :numref:`Chapter %s `, in the `UFS_UTILS Technical Documentation `__, and in the `UFS_UTILS Scientific Documentation `__. - -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 (:term:`LAM`) capability (:cite:t:`BlackEtAl2021`). The :term:`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 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 most recent SRW App release includes four supported physics suites. - -Data Format -^^^^^^^^^^^^^^^^^^^^^^ - -The SRW App supports the use of external model data in :term:`GRIB2`, :term:`NEMSIO`, and :term:`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 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 `__. - -METplus Verification Suite ------------------------------- - -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 `__. - -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 the `Rocoto documentation `__ for more on workflow management). Individual workflow tasks 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 used for the simulation. More information on how to do this is available in :numref:`Section %s `. - -The SRW Application 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 available in a central location (via :term:`HPC-Stack`). 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 (Levels 2-4), the SRW App can be :ref:`run within a container ` that includes the prerequisite software; otherwise, 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. - .. _SRWStructure: Code Repositories and Directory Structure From fd9efc82b8a17b9d9810bdc0264d75532687e15d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 6 Jul 2023 10:43:34 -0400 Subject: [PATCH 004/116] restructure SRW docs --- .../BackgroundInformation/Components.rst | 119 ++ .../BackgroundInformation/Introduction.rst | 150 ++ .../TechnicalOverview.rst | 321 +++++ .../source/BackgroundInformation/index.rst | 15 + .../source/BuildingRunningTesting/AQM.rst | 259 ++++ .../BuildingRunningTesting/BuildSRW.rst | 480 +++++++ .../ContainerQuickstart.rst | 390 +++++ .../BuildingRunningTesting/Quickstart.rst | 98 ++ .../source/BuildingRunningTesting/RunSRW.rst | 1262 +++++++++++++++++ .../BuildingRunningTesting/Tutorial.rst | 586 ++++++++ .../source/BuildingRunningTesting/VXCases.rst | 313 ++++ .../BuildingRunningTesting/WE2Etests.rst | 412 ++++++ .../source/BuildingRunningTesting/index.rst | 20 + docs/UsersGuide/source/Reference/FAQ.rst | 201 +++ docs/UsersGuide/source/Reference/Glossary.rst | 260 ++++ .../source/Reference/RocotoInfo.rst | 236 +++ docs/UsersGuide/source/Reference/index.rst | 14 + .../TechnicalDetails/ConfigWorkflow.rst | 1248 ++++++++++++++++ .../TechnicalDetails/DefineWorkflow.rst | 242 ++++ .../TechnicalDetails/InputOutputFiles.rst | 411 ++++++ .../source/TechnicalDetails/LAMGrids.rst | 204 +++ .../source/TechnicalDetails/TemplateVars.rst | 77 + .../source/TechnicalDetails/index.rst | 17 + 23 files changed, 7335 insertions(+) create mode 100644 docs/UsersGuide/source/BackgroundInformation/Components.rst create mode 100644 docs/UsersGuide/source/BackgroundInformation/Introduction.rst create mode 100644 docs/UsersGuide/source/BackgroundInformation/TechnicalOverview.rst create mode 100644 docs/UsersGuide/source/BackgroundInformation/index.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/AQM.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/index.rst create mode 100644 docs/UsersGuide/source/Reference/FAQ.rst create mode 100644 docs/UsersGuide/source/Reference/Glossary.rst create mode 100644 docs/UsersGuide/source/Reference/RocotoInfo.rst create mode 100644 docs/UsersGuide/source/Reference/index.rst create mode 100644 docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst create mode 100644 docs/UsersGuide/source/TechnicalDetails/DefineWorkflow.rst create mode 100644 docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst create mode 100644 docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst create mode 100644 docs/UsersGuide/source/TechnicalDetails/TemplateVars.rst create mode 100644 docs/UsersGuide/source/TechnicalDetails/index.rst diff --git a/docs/UsersGuide/source/BackgroundInformation/Components.rst b/docs/UsersGuide/source/BackgroundInformation/Components.rst new file mode 100644 index 0000000000..3802c384d3 --- /dev/null +++ b/docs/UsersGuide/source/BackgroundInformation/Components.rst @@ -0,0 +1,119 @@ +.. _Components: + +============================ +SRW Application Components +============================ + +The SRW Application assembles a variety of components, including: + +* Pre-processor Utilities & Initial Conditions +* 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 the `GitHub Discussions `__ forum. + +.. _Utils: + +UFS Preprocessing Utilities (UFS_UTILS) +========================================== + +The SRW Application includes a number of pre-processing utilities (UFS_UTILS) that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), these utilities 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 :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3`-:term:`LAM`. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS Technical Documentation `__ and in the `UFS_UTILS Scientific Documentation `__. + +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 `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 (:term:`LAM`) capability (:cite:t:`BlackEtAl2021`). The :term:`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 accessed `here `__. + +Supported model resolutions in this release include 3-, 13-, and 25-km predefined contiguous U.S. (:term:`CONUS`) domains, each with 127 vertical levels. Preliminary tools for users to define their own domain are also available in the release with full, formal support of these tools to be provided in future releases. The Extended Schmidt Gnomonic (ESG) grid is used with the FV3-LAM, which features relatively uniform grid cells across the entirety of the domain. Additional information about the FV3 dynamical core can be found in the `scientific documentation `__, the `technical documentation `__, and on the `NOAA Geophysical Fluid Dynamics Laboratory website `__. + +Model Physics +--------------- + +The Common Community Physics Package (CCPP), described `here `__, 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 most recent SRW App release (v2.1.0) included four supported physics suites, and a fifth has since been added: FV3_RRFS_v1beta, FV3_GFS_v16, FV3_WoFS_v0, FV3_HRRR, and FV3_RAP (new!). The FV3_RRFS_v1beta physics suite is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (:term:`RRFS`) planned for 2023-2024, and the FV3_GFS_v16 is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. A detailed list of CCPP updates since the SRW App v2.0.0 release is available :ref:`here `. A full scientific description of CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. Additionally, a CCPP single-column model (`CCPP-SCM `__) option has also been developed as a child repository. Users can refer to the `CCPP Single Column Model User and Technical Guide `__ for more details. This CCPP-SCM user guide contains a Quick Start Guide with instructions for obtaining the code, compiling, and running test cases, which include five standard test cases and two additional FV3 replay cases (refer to section 5.2 in the CCPP-SCM user guide for more details). Moreover, the CCPP-SCM supports a precompiled version in a docker container, allowing it to be easily executed on NOAA's cloud computing platforms without any issues (see section 2.5 in the CCPP-SCM user guide for more details). + +.. note:: + SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which physics suite definition file (:term:`SDF`) is chosen when turning this option on. Among the supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. + +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. + +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 App, the UPP converts model output data from the model's native :term:`netCDF` format 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). + +.. _MetplusComponent: + +METplus Verification Suite +============================= + +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. + +The METplus verification framework 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) `__. + +METplus *installation* is not included as part of the build process for the most recent release of the SRW App. However, METplus is preinstalled on many `Level 1 & 2 `__ systems; existing builds can be viewed `here `__. + +METplus can be installed on other systems individually or as part of :term:`HPC-Stack` installation. Users on systems without a previous installation of METplus can follow the `MET Installation Guide `__ and `METplus Installation Guide `__ 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. + +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. + +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 (which include conventional point-based surface and upper-air data) in `prepBUFR format `__ 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 (:term:`EMC`), and it is open to community contributions. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. + +AQM Utilities +=============== + +https://github.com/NOAA-EMC/AQM-utils + +NOAA Emission and Exchange Unified System (NEXUS) +=================================================== + +https://github.com/noaa-oar-arl/NEXUS + +Gridpoint Statistical Interpolation (GSI) +============================================ + +https://github.com/NOAA-EMC/GSI + +RRFS Utilities +================ + +https://github.com/NOAA-GSL/rrfs_utl + +Unified Workflow Tools +======================== + +https://github.com/ufs-community/workflow-tools + + +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. This build system collects the components necessary for running the end-to-end SRW Application, including the UFS Weather Model and the pre- and post-processing software. Additional libraries necessary for the application (e.g., :term:`NCEPLIBS-external` and :term:`NCEPLIBS`) are not included in the SRW Application build system but are available pre-built on pre-configured platforms. On other systems, they can be installed via the HPC-Stack (see :doc:`HPC-Stack Documentation `). There is a small set of system libraries and utilities that are assumed to be present on the target computer: the CMake build software; a Fortran, C, and C++ compiler; and an :term:`MPI` library. + +Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see :numref:`Chapter %s ` or the `Rocoto documentation `__ for more information on Rocoto and workflow management). 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 SRW Application allows users to configure various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, integration time step, and the physics suite used for the simulation. It also allows for configuration of other elements of the workflow; for example, users can choose whether to run some or all of the pre-processing, forecast model, and post-processing steps. More information on how to configure the workflow is available in :numref:`Section %s `. + +An optional Python plotting task is also included to create basic visualizations of the model output. The task outputs graphics in PNG format for several standard meteorological variables on the pre-defined :term:`CONUS` domain. A difference plotting option is also included to visually compare two runs for the same domain and resolution. These plots may be used to perform a visual check to verify that the application is producing reasonable results. Configuration instructions are provided in :numref:`Section %s `. + +The SRW Application has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g., Hera, Orion, Jet); the National Center for Atmospheric Research (:term:`NCAR`) Cheyenne system; cloud environment, 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 (Level 3), and build-only (Level 4) platforms. + +Preconfigured (Level 1) systems already have the required external libraries available in a central location (via :term:`HPC-Stack` or :term:`spack-stack`). 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. + +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. Users will need to install the required libraries as part of the :ref:`SRW Application build ` process. Applications and models are expected to build and run once the required libraries are built. Release testing is conducted on these systems to ensure that the SRW App runs smoothly there. + +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. 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. + +On all platforms, the SRW App can be :ref:`run within a container ` that includes the prerequisite software. + +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 `__. + diff --git a/docs/UsersGuide/source/BackgroundInformation/Introduction.rst b/docs/UsersGuide/source/BackgroundInformation/Introduction.rst new file mode 100644 index 0000000000..e46f134177 --- /dev/null +++ b/docs/UsersGuide/source/BackgroundInformation/Introduction.rst @@ -0,0 +1,150 @@ +.. _Introduction: + +============== +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` (including 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 most recent SRW Application 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 the `GitHub Discussions `__ forum. The SRW App also includes support for a verification package (METplus) for both deterministic and ensemble simulations and support for four stochastically perturbed physics schemes. + +Since the v2.1.0 release, developers have added a variety of features: + + * Bug fixes since the v2.1.0 release + * Rapid Refresh Forecast System (RRFS) capabilities + * Air Quality Modeling (AQM) capabilities + * Updates to :term:`CCPP` that target the top of the ``main`` branch (which is ahead of CCPP v6.0.0). See :ref:`this page ` for a detailed summary of updates that came in ahead of the v2.1.0 release. + * Support for the :term:`UPP` inline post option (see :ref:`here `) + * Documentation updates to reflect the changes above + +The SRW App v2.1.0 citation is as follows and should be used when presenting results based on research conducted with the App: + +UFS Development Team. (2022, Nov. 17). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.1.0). Zenodo. https://doi.org/10.5281/zenodo.7277602 + +Organization of SRW App Documentation +======================================== + +The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Technical Information*; and *Reference*. + +.. hint:: + * To get started with the SRW App, users can try one of the following options: + + #. View :numref:`Chapter %s ` for a quick overview of the workflow steps. + #. To build the application in a container, which provides a more uniform work environment, users can refer to the :ref:`Container-Based Quick Start Guide `. + #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Chapter %s: Building the SRW App ` and :numref:`Chapter %s: Running the SRW App `. + +Background Information +------------------------ + + * This **Introduction** chapter explains how the SRW App documentation is organized, how to use this guide, and where to find user support/documentation. + * :numref:`Chapter %s: Technical Overview ` provides a technical overview, including SRW App prerequisites, code overview/directory structure, and summary of components. + * :numref:`Chapter %s: Components ` provides a more detailed description of the application components, including optional application components. + +Building, Running, and Testing the SRW App +-------------------------------------------- + + * :numref:`Chapter %s: Quick Start Guide ` is designed for use on `Level 1 systems `__ or as an overview of the workflow. + * :numref:`Chapter %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers come with SRW App prerequisites already installed and run on a broad range of systems. + * :numref:`Chapter %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. + * :numref:`Chapter %s: Running the SRW App ` provides a *detailed* explanation of how to run the App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. + * :numref:`Chapter %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. + * :numref:`Chapter %s: ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. + * :numref:`Chapter %s: ` explains how to run METplus verification as part of the workflow. + * :numref:`Chapter %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this chapter is a starting point for those interested in AQM. + +Technical Information for Users +--------------------------------- + + * :numref:`Chapter %s: ` documents all of the user-configurable experiment parameters that can be set in ``config.yaml``. + * :numref:`Chapter %s: ` provides information on application input and output files, as well as information on where to get publicly available data. + * :numref:`Chapter %s: ` describes the SRW App predefined grids in detail and explains how to create a custom user-generated grid. + * :numref:`Chapter %s: ` explains how to build or alter the SRW App workflow XML file. + * :numref:`Chapter %s: ` explains how to use template variables. + +Reference Information +----------------------- + + * :numref:`Chapter %s: Rocoto Introductory Information ` provides an introduction to standard Rocoto commands with examples. + * :numref:`Chapter %s: FAQ ` answers users' frequently asked questions. + * :numref:`Chapter %s: Glossary ` defines important terms related to the SRW App. + + +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 `GitHub Discussions `__ forum. + +.. code-block:: console + + Throughout the guide, this presentation style indicates shell commands and options, code examples, etc. + +Variables presented as ``AaBbCc123`` in this User's Guide typically refer to variables in scripts, names of files, or directories. + +File paths and code that include angle brackets (e.g., ``build__``) indicate that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). + +User Support, Documentation, and Contributions to Development +=============================================================== + +The SRW App's `GitHub Discussions `__ forum provides online support 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 | https://ufs-srweather-app.readthedocs.io/en/develop/ | + | User's Guide | | + +----------------------------+---------------------------------------------------------------------------------+ + | UFS_UTILS Technical | https://noaa-emcufs-utils.readthedocs.io/en/latest | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | UFS_UTILS Scientific | https://ufs-community.github.io/UFS_UTILS/index.html | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | UFS Weather Model | https://ufs-weather-model.readthedocs.io/en/latest | + | User's Guide | | + +----------------------------+---------------------------------------------------------------------------------+ + | HPC-Stack Documentation | https://hpc-stack.readthedocs.io/en/latest/ | + +----------------------------+---------------------------------------------------------------------------------+ + | FV3 Scientific | https://repository.library.noaa.gov/view/noaa/30725 | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | FV3 Technical | https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | CCPP Scientific | https://dtcenter.ucar.edu/GMTB/v6.0.0/sci_doc/index.html | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | CCPP Technical | https://ccpp-techdoc.readthedocs.io/en/latest/ | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | Stochastic Physics | https://stochastic-physics.readthedocs.io/en/latest/ | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | ESMF manual | https://earthsystemmodeling.org/docs/release/latest/ESMF_usrdoc/ | + +----------------------------+---------------------------------------------------------------------------------+ + | Unified Post Processor | https://upp.readthedocs.io/en/latest/ | + +----------------------------+---------------------------------------------------------------------------------+ + +The UFS community is encouraged to contribute to the development effort of all related +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 into the authoritative repositories, users must follow the code management rules of each UFS component repository. These rules are usually outlined in the User's Guide (see :numref:`Table %s `) or wiki for each respective repository (see :numref:`Table %s `). Contributions to the `ufs-srweather-app `__ repository should follow the guidelines contained in the `SRW App Contributor's Guide `__. + +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: + +* 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. + + +.. bibliography:: ../references.bib + + + diff --git a/docs/UsersGuide/source/BackgroundInformation/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInformation/TechnicalOverview.rst new file mode 100644 index 0000000000..4eb03e3c7a --- /dev/null +++ b/docs/UsersGuide/source/BackgroundInformation/TechnicalOverview.rst @@ -0,0 +1,321 @@ +.. _TechOverview: + +==================== +Technical Overview +==================== + +This chapter provides information on SRW App prerequistes, code repositories, and directory structure. + +.. _SRWPrerequisites: + +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 (concepts of parameterizations: physical, microphysical, convective) +* Meteorology (in particular, meteorology at the scales being predicted: 25km, 13km, and 3km resolutions) + +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. SRW App `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 + +* >82 GB disk space + + * 53 GB input data for a standard collection of global data, or "fix" file data (topography, climatology, observational data) for a short 12-hour test forecast on the :term:`CONUS` 25km domain. See data download instructions in :numref:`Section %s `. + * 8 GB for full :term:`HPC-Stack` installation + * 3 GB for ``ufs-srweather-app`` installation + * 1 GB for boundary conditions for a short 12-hour test forecast on the CONUS 25km domain. See data download instructions in :numref:`Section %s `. + * 17 GB for a 12-hour test forecast on the CONUS 25km domain, with model output saved hourly. + +* Fortran compiler released since 2018 + + * 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, LLVM clang, GNU) 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 v2.12+ + +* curl + +* wget + +* Lmod + + +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.20+ + +* :term:`MPI` (MPICH, OpenMPI, or other implementation) + + * Only **MPICH** or **OpenMPI** can be built with HPC-Stack. Other implementations must be installed separately by the user (if desired). + +For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew `__ package manager for MacOS. See :doc:`HPC-Stack Documentation: Chapter 3 ` and :numref:`Chapter %s ` for further guidance on installing these prerequisites on MacOS. + +* bash v4.x +* GNU compiler suite v11 or higher with gfortran +* cmake +* make +* coreutils +* gsed + +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 + +.. _SRWStructure: + +Code Repositories and Directory Structure +========================================= + +.. _HierarchicalRepoStr: + +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 tags the appropriate versions of the external repositories associated with the SRW App (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 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, which are documented `here `__. + +.. note:: + The prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The `HPC-Stack `__ repository assembles these prerequisite libraries. The HPC-Stack has already been built on `preconfigured (Level 1) platforms `__. However, it must be built on other systems. See the :doc:`HPC-Stack Documentation ` for details on installing the HPC-Stack. + + +.. _TopLevelDirStructure: + +Directory Structure +---------------------- +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 (see :numref:`Section %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 + ├── (build) + ├── docs + │ └── UsersGuide + ├── etc + ├── (exec) + ├── (include) + ├── jobs + ├── (lib) + ├── manage_externals + ├── modulefiles + ├── parm + ├── (share) + ├── scripts + ├── sorc + │ ├── CMakeLists.txt + │ ├── (gsi) + │ ├── (rrfs_utl) + │ ├── (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 + ├── tests/WE2E + ├── ush + │ ├── bash_utils + │ ├── machine + │ ├── Python + │ ├── python_utils + │ ├── test_data + │ └── wrappers + └── versions + +SRW App SubDirectories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:numref:`Table %s ` describes the contents of the most important subdirectories. :numref:`Table %s ` provides an in-depth explanation of the ``ufs-srweather-app`` directories. + +.. _Subdirectories: + +.. table:: Subdirectories of the regional workflow + + +-------------------------+----------------------------------------------------+ + | **Directory Name** | **Description** | + +=========================+====================================================+ + | jobs | J-job scripts launched by Rocoto | + +-------------------------+----------------------------------------------------+ + | modulefiles | Files used to load modules needed for building and | + | | running the workflow | + +-------------------------+----------------------------------------------------+ + | scripts | Scripts launched by the J-jobs | + +-------------------------+----------------------------------------------------+ + | tests | Tests for baseline experiment configurations | + +-------------------------+----------------------------------------------------+ + | ush | Utility scripts used by the workflow | + +-------------------------+----------------------------------------------------+ + +.. _ExperimentDirSection: + +Experiment Directory Structure +-------------------------------- +When the user generates an experiment using the ``generate_FV3LAM_wflow.py`` script (:numref:`Step %s `), a user-defined experiment directory (``$EXPTDIR``) is created based on information specified in the ``config.yaml`` file. :numref:`Table %s ` shows the contents of the experiment directory before running the experiment workflow. + +.. _ExptDirStructure: + +.. table:: Files and subdirectory initially created in the experiment directory + :widths: 33 67 + + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | **File Name** | **Description** | + +===========================+==============================================================================================================+ + | config.yaml | User-specified configuration file, see :numref:`Section %s ` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | data_table | :term:`Cycle-independent` input file (empty) | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | field_table | :term:`Tracers ` in the `forecast model | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | input.nml | :term:`Namelist` for the `UFS Weather Model | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | launch_FV3LAM_wflow.sh | Symlink to the ``ufs-srweather-app/ush/launch_FV3LAM_wflow.sh`` shell script, | + | | which can be used to (re)launch the Rocoto workflow. | + | | Each time this script is called, it appends information 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.py``) | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | nems.configure | See `NEMS configuration file | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | suite_{CCPP}.xml | :term:`CCPP` suite definition file (:term:`SDF`) 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, running the SRW App in *community* mode creates the ``fix_am`` and ``fix_lam`` directories (see :numref:`Table %s `) 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 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 symlinks | + | | 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 Rocoto workflow is launched, several files and directories are generated. A log file named ``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_lbcs``) are preprocessing tasks, and these tasks also result in the creation of new files and subdirectories, 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 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 in the ``config.yaml`` file, more than one cycle | + | | directory will be created under the experiment directory. | + +---------------------------+--------------------------------------------------------------------+ + | 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 by its | + | | various tasks. View the files in this directory to determine 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 | The ``launch_FV3LAM_wflow.sh`` script appends its output to this | + | | log file each time it is called. View the last several | + | | 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/BackgroundInformation/index.rst b/docs/UsersGuide/source/BackgroundInformation/index.rst new file mode 100644 index 0000000000..3aead7b5de --- /dev/null +++ b/docs/UsersGuide/source/BackgroundInformation/index.rst @@ -0,0 +1,15 @@ +.. UFS SR Weather App Users Guide, created by + sphinx-quickstart on Tue Feb 12 08:48:32 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Background Information +========================= + +.. toctree:: + :maxdepth: 3 + + + Introduction + TechnicalOverview + Components diff --git a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst new file mode 100644 index 0000000000..4c810f0d69 --- /dev/null +++ b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst @@ -0,0 +1,259 @@ +.. _AQM: + +===================================== +Air Quality Modeling (SRW-AQM) +===================================== + +The standard SRW App distribution uses the uncoupled version of the UFS Weather Model (atmosphere-only). However, users have the option to use a coupled version of the SRW App that includes the standard distribution (atmospheric model) plus the Air Quality Model (AQM). + +The AQM is a UFS Application that dynamically couples the Community Multiscale Air Quality (:term:`CMAQ`) model with the UFS Weather Model (WM) through the :term:`NUOPC` Layer to simulate temporal and spatial variations of atmospheric compositions (e.g., ozone and aerosol compositions). The CMAQ model, treated as a column chemistry model, updates concentrations of chemical species (e.g., ozone and aerosol compositions) at each integration time step. The transport terms (e.g., :term:`advection` and diffusion) of all chemical species are handled by the UFS WM as tracers. + +.. note:: + + Although this chapter is the primary documentation resource for running the AQM configuration, users may need to refer to :numref:`Chapter %s ` and :numref:`Chapter %s ` for additional information on building and running the SRW App, respectively. + +.. attention:: + + These instructions should work smoothly on Hera and WCOSS2, but users on other systems may need to make additional adjustments. + +Quick Start Guide (SRW-AQM) +===================================== + +Download the Code +------------------- + +Clone the ``develop`` branch of the authoritative SRW App repository: + +.. code-block:: console + + git clone -b develop https://github.com/ufs-community/ufs-srweather-app + cd ufs-srweather-app + +Checkout Externals +--------------------- + +Users must run the ``checkout_externals`` script to collect (or "check out") the individual components of the SRW App (AQM version) from their respective GitHub repositories. + +.. code-block:: console + + ./manage_externals/checkout_externals + +Build the SRW App with AQM +----------------------------- + +On Hera and WCOSS2, users can build the SRW App AQM binaries with the following command: + +.. code-block:: console + + ./devbuild.sh -p= -a=ATMAQ + +where ```` is ``hera``, or ``wcoss2``. The ``-a`` argument indicates the configuration/version of the application to build. + +Building the SRW App with AQM on other machines, including other `Level 1 `__ platforms, is not currently guaranteed to work, and users may have to make adjustments to the modulefiles for their system. + +Load the ``workflow_tools`` Environment +-------------------------------------------- + +Load the python environment for the workflow: + +.. code-block:: console + + # On WCOSS2 (do not run on other systems): + source ../versions/run.ver.wcoss2 + # On all systems (including WCOSS2): + module use /path/to/ufs-srweather-app/modulefiles + module load wflow_ + +where ```` is ``hera`` or ``wcoss2``. The workflow should load on other platforms listed under the ``MACHINE`` variable in :numref:`Section %s `, but users may need to adjust other elements of the process when running on those platforms. + +If the console outputs a message, the user should run the commands specified in the message. For example, if the output says: + +.. code-block:: console + + Please do the following to activate conda: + > conda activate workflow_tools + +then the user should run ``conda activate workflow_tools``. Otherwise, the user can continue with configuring the workflow. + +.. _AQMConfig: + +Configure and Experiment +--------------------------- + +Users will need to configure their experiment by setting parameters in the ``config.yaml`` file. To start, users can copy a default experiment setting into ``config.yaml``: + +.. code-block:: console + + cd ush + cp config.aqm.community.yaml config.yaml + +Users may prefer to copy the ``config.aqm.nco.realtime.yaml`` for a default "nco" mode experiment instead. + +Users will need to change the ``MACHINE`` and ``ACCOUNT`` variables in ``config.yaml`` to match their system. They may also wish to adjust other experiment settings. For more information on each task and variable, see :numref:`Chapter %s `. + +Users may also wish to change :term:`cron`-related parameters in ``config.yaml``. In the ``config.aqm.community.yaml`` file, which was copied into ``config.yaml``, cron is used for automatic submission and resubmission of the workflow: + +.. code-block:: console + + workflow: + USE_CRON_TO_RELAUNCH: true + CRON_RELAUNCH_INTVL_MNTS: 3 + +This means that cron will submit the launch script every 3 minutes. Users may choose not to submit using cron or to submit at a different frequency. Note that users should create a crontab by running ``crontab -e`` the first time they use cron. + +Generate the Workflow +------------------------ + +Generate the workflow: + +.. code-block:: console + + ./generate_FV3LAM_wflow.py + +Run the Workflow +------------------ + +If ``USE_CRON_TO_RELAUNCH`` is set to true in ``config.yaml`` (see :numref:`Section %s `), the workflow will run automatically. If it was set to false, users must submit the workflow manually from the experiment directory: + +.. code-block:: console + + cd / + ./launch_FV3LAM_wflow.sh + +Repeat the launch command regularly until a SUCCESS or FAILURE message appears on the terminal window. See :numref:`Section %s ` for more on the ```` and ```` variables. + +Users may check experiment status from the experiment directory with either of the following commands: + +.. code-block:: console + + # Check the experiment status (best for cron jobs) + rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 + + # Check the experiment status and relaunch the workflow (for manual jobs) + ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow + + +WE2E Test for AQM +======================= + +Build the app for AQM: + +.. code-block:: console + + ./devbuild.sh -p=hera -a=ATMAQ + + +Add the WE2E test for AQM to the list file: + +.. code-block:: console + + echo "custom_ESGgrid" > my_tests.txt + echo "aqm_grid_AQM_NA13km_suite_GFS_v16" >> my_tests.txt + + +Run the WE2E test: + +.. code-block:: console + + $ ./run_WE2E_tests.py -t my_tests.txt -m hera -a gsd-fv3 -q + + + +Additional Tasks for AQM +=============================== + +Structure of SRW-AQM +------------------------- + +The flowchart of the non-DA (data assimilation) SRW-AQM (Air Quality Modeling) is illustrated in :numref:`Figure %s `. Compared to the non-coupled (ATM stand-alone) FV3-LAM, SRW-AQM has additional tasks for pre- and post-processing. For pre-processing, multiple emission data such as NEXUS, fire, and point-source emission are retrieved or created for air quality modeling. Moreover, the chemical initial conditions (ICs) are extracted from the restart files of the previous cycle and added to the existing IC files. The chemical lateral boundary conditions (LBCs) and the GEFS aerosol data are also adeded to the existing LBC files. For post-processing, air quality forecast products for O3 and PM2.5 are generated and the bias-correction technique is applied to improve the accuracy of the results. + +.. _FlowProcAQM: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW-AQM_workflow.png + :alt: Flowchart of the SRW-AQM tasks. + + *Workflow structure of SRW-AQM (non-DA)* + + + +Pre-processing Tasks of SRW-AQM +------------------------------------ + +The pre-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. + +.. _TasksPrepAQM: + +.. table:: Tasks for pre-processing of AQM + + +-----------------------+--------------------------------------------------------------------+ + | **Task name** | **Description** | + +=======================+====================================================================+ + | nexus_gfs_sfc | This task retrieves the GFS surface files from the previous cycle | + | | in NRT (Near-Real-Time) or current cycle in retrospective cases. | + | | The surface radiation, soil moisture and temperature fields are | + | | needed for the MEGAN biogenics emissions within nexus_emission. | + +-----------------------+--------------------------------------------------------------------+ + | nexus_emission | This task prepares the run directory with gridded emission inputs, | + | | run nexus to create model ready emission for the given simulation | + | | day, and post processes nexus output to make it more readable. The | + | | task will also split the task into multiple jobs set by the user. | + +-----------------------+--------------------------------------------------------------------+ + | nexus_post_split | This task combines the nexus_emission outputs into a single job. | + +-----------------------+--------------------------------------------------------------------+ + | fire_emission | This tasks is used to convert both satellite-retrieved gas and | + | | aerosol species emissions (RAVE) from mass (kg) to emission rates | + | | (kg/m2/s) and create 3-day hourly model-ready fire emission input | + | | files. | + +-----------------------+--------------------------------------------------------------------+ + | point_source | This task aggregates the anthropogenic point source sectors of the | + | | National Emission Inventory(NEI) into a ready-to-input point-source| + | | emission file based on the weekday/weekend/holiday patterns of each| + | | sector and date/time of the simulation. | + +-----------------------+--------------------------------------------------------------------+ + | aqm_ics | This task creates a chemical initial condition file by using the | + | | previous cycle restart files. | + +-----------------------+--------------------------------------------------------------------+ + | aqm_lbcs | This task adds the chemical lateral boundary condition (LBC) upon | + | | the meteorological lateral boundary condition to form the full-set | + | | ready-to-input LBC for the simulation. It includes two sub-tasks: | + | | the gaseous species LBC and dynamic aerosol LBC. The former adds | + | | static gaseous LBC using monthly mean global data. The latter is | + | | the parallel job, which extracts the GEFS-Aerosol Model's output | + | | along the regional domain, and performs the species conversion | + | | from GOCART aerosols to CMAQ aerosols. | + +-----------------------+--------------------------------------------------------------------+ + + +Post-processing Tasks of SRW-AQM +------------------------------------ + +The post-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. Since the module required to run these tasks is available only on WCOSS2, these tasks should not be defined in the configuration file ``config.yaml`` on other platforms. + +.. _TasksPostAQM: + +.. table:: Tasks for post-processing of AQM + + +-----------------------+--------------------------------------------------------------------+ + | **Task name** | **Description** | + +=======================+====================================================================+ + | pre_post_stat | This task creates surface (i.e., model 1st level) meteorological | + | | and chemical files to support air quality product generation and | + | | generate training data to support bias correction tasks. | + +-----------------------+--------------------------------------------------------------------+ + | post_stat_o3 | This task generates air quality forecast products including hourly | + | | -average and statistical products for O3 (e.g., daily 8-hour | + | | average maximum O3). | + +-----------------------+--------------------------------------------------------------------+ + | post_stat_pm25 | This task generates air quality forecast products including hourly | + | | -average and statistical products for PM2.5 (e.g., 24-hour average | + | | PM2.5). | + +-----------------------+--------------------------------------------------------------------+ + | bias_correction_o3 | This task applies a bias-correction technique (e.g., analog | + | | ensemble) to improve model raw forecast for O3 and generates the | + | | bias-corrected O3 products. | + +-----------------------+--------------------------------------------------------------------+ + | bias_correction_pm25 | This task applies a bias-correction technique (e.g., analog | + | | ensemble) to improve model raw forecast for PM2.5 and generates the| + | | bias-corrected PM2.5 products. | + +-----------------------+--------------------------------------------------------------------+ + diff --git a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst new file mode 100644 index 0000000000..33450085f6 --- /dev/null +++ b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst @@ -0,0 +1,480 @@ +.. _BuildSRW: + +========================== +Building 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 built, users can configure experiments and generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. + +.. attention:: + + The SRW Application has `four levels of support `__. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. This chapter can also serve as a starting point for running the SRW App on other systems (including generic Linux/Mac systems), but the user may need to perform additional troubleshooting. + +.. note:: + The :ref:`container approach ` is recommended for a smoother first-time build and run experience. Building without a container may allow for more customization. However, the non-container approach requires more in-depth system-based knowledge, especially on Level 3 and 4 systems, so it is less appropriate for beginners. + +To build the SRW App, users will complete the following steps: + + #. :ref:`Install prerequisites ` + #. :ref:`Clone the SRW App from GitHub ` + #. :ref:`Check out the external repositories ` + #. :ref:`Set up the build environment and build the executables ` + +.. _AppBuildProc: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW_build_process.png + :alt: Flowchart describing the SRW App build process. + + *Overview of the SRW App Build Process* + + +.. _HPCstackInfo: + +Install the Prerequisite Software Stack +========================================== + +Currently, installation of the prerequisite software stack is supported via HPC-Stack. :term:`HPC-Stack` is a repository that provides a unified, shell script-based system to build the software stack required for `UFS `__ applications such as the SRW App. + +.. Attention:: + Skip the HPC-Stack installation if working on a `Level 1 system `__ (e.g., Cheyenne, Hera, Orion, NOAA Cloud), and :ref:`continue to the next section `. + +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) 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) 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 `. + +.. attention:: + Although HPC-Stack is the fully-supported option as of the v2.1.0 release, UFS applications are gradually shifting to :term:`spack-stack`, which is a :term:`Spack`-based method for installing UFS prerequisite software libraries. The spack-stack is currently used on NOAA Cloud platforms and in containers, while HPC-Stack is still used on other Level 1 systems and is the software stack validated by the UFS Weather Model as of the v2.1.0 release. Users are encouraged to check out `spack-stack `__ to prepare for the upcoming shift in support from HPC-Stack to spack-stack. + +After completing installation, continue to the next section (:numref:`Section %s: Download the UFS SRW Application Code `). + +.. _DownloadSRWApp: + +Download the UFS SRW Application Code +====================================== +The SRW Application source code is publicly available on GitHub. To download the SRW App code, clone the ``develop`` branch of the repository: + +.. code-block:: console + + git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git + +The cloned repository contains the configuration files and sub-directories shown in +:numref:`Table %s `. The user may set an ``$SRW`` environment variable to point to the location of the new ``ufs-srweather-app`` repository. For example, if ``ufs-srweather-app`` was cloned into the ``$HOME`` directory, the following commands will set an ``$SRW`` environment variable in a bash or csh shell, respectively: + +.. code-block:: console + + export SRW=$HOME/ufs-srweather-app + setenv SRW $HOME/ufs-srweather-app + +.. _FilesAndSubDirs: + +.. table:: Files and sub-directories of the ufs-srweather-app repository + + +--------------------------------+-----------------------------------------------------------+ + | **File/Directory Name** | **Description** | + +================================+===========================================================+ + | CMakeLists.txt | Main CMake file for SRW App | + +--------------------------------+-----------------------------------------------------------+ + | devbuild.sh | SRW App build script | + +--------------------------------+-----------------------------------------------------------+ + | docs | Contains release notes, documentation, and User's Guide | + +--------------------------------+-----------------------------------------------------------+ + | environment.yml | Contains information on the package versions required for | + | | the regional workflow environment. | + +--------------------------------+-----------------------------------------------------------+ + | etc | Contains Lmod startup scripts | + +--------------------------------+-----------------------------------------------------------+ + | Externals.cfg | Includes tags pointing to the correct version of the | + | | external GitHub repositories/branches used in the SRW | + | | App. | + +--------------------------------+-----------------------------------------------------------+ + | jobs | Contains the *j-job* script for each workflow task. These | + | | scripts set up the environment variables and call an | + | | *ex-script* script located in the ``scripts`` | + | | subdirectory. | + +--------------------------------+-----------------------------------------------------------+ + | LICENSE.md | CC0 license information | + +--------------------------------+-----------------------------------------------------------+ + | manage_externals | Utility for checking out external repositories | + +--------------------------------+-----------------------------------------------------------+ + | modulefiles | Contains build and workflow modulefiles | + +--------------------------------+-----------------------------------------------------------+ + | parm | Contains parameter files. Includes UFS Weather Model | + | | configuration files such as ``model_configure``, | + | | ``diag_table``, and ``field_table``. | + +--------------------------------+-----------------------------------------------------------+ + | README.md | Contains SRW App introductory information | + +--------------------------------+-----------------------------------------------------------+ + | rename_model.sh | Used to rename the model before it is transitioned into | + | | operations. The SRW App is a generic app that is the base | + | | for models such as :term:`AQM` and :term:`RRFS`. When | + | | these models become operational, variables like | + | | ``HOMEdir`` and ``PARMdir`` will be renamed to | + | | ``HOMEaqm``/``HOMErrfs``, ``PARMaqm``/``PARMrrfs``, etc. | + | | using this script. | + +--------------------------------+-----------------------------------------------------------+ + | scripts | Contains the *ex-script* for each workflow task. | + | | These scripts are where the script logic and executables | + | | are contained. | + +--------------------------------+-----------------------------------------------------------+ + | sorc | Contains CMakeLists.txt; external repositories | + | | will be cloned into this directory. | + +--------------------------------+-----------------------------------------------------------+ + | tests | Contains SRW App tests, including workflow end-to-end | + | | (WE2E) tests. | + +--------------------------------+-----------------------------------------------------------+ + | 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 | + +--------------------------------+-----------------------------------------------------------+ + | ush | Contains utility scripts. Includes the experiment | + | | configuration file and the experiment generation file. | + +--------------------------------+-----------------------------------------------------------+ + | versions | Contains ``run.ver`` and ``build.ver`` files, which track | + | | package versions at run time and compile time, | + | | respectively. | + +--------------------------------+-----------------------------------------------------------+ + +.. COMMENT: Is environment.yml deprecated? Remove? + +.. _CheckoutExternals: + +Check Out External Components +================================ + +The SRW App relies on a variety of components (e.g., UFS_UTILS, ufs-weather-model, and UPP) detailed in :numref:`Chapter %s ` of this User's Guide. Each component has its own repository. Users must run the ``checkout_externals`` script to collect the individual components of the SRW App from their respective GitHub 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 (e.g., ``ush``, ``sorc``). + +Run the executable that pulls in SRW App components from external repositories: + +.. code-block:: console + + cd + ./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. + +To see more options for the ``checkout_externals`` script, users can run ``./manage_externals/checkout_externals -h``. For example: + + * ``-S``: Outputs the status of the repositories managed by ``checkout_externals``. By default only summary information is provided. Use with the ``-v`` (verbose) option to see details. + * ``-x [EXCLUDE [EXCLUDE ...]]``: allows users to exclude components when checking out externals. + * ``-o``: By default only the required externals are checked out. This flag will also check out the optional externals. + +Generally, users will not need to use the options and can simply run the script, but the options are available for those who are curious. + +.. _BuildExecutables: + +Set Up the Environment and Build the Executables +=================================================== + +.. _DevBuild: + +``devbuild.sh`` Approach +----------------------------- + +On Level 1 systems for which a modulefile is provided under the ``modulefiles`` directory, users can build the SRW App binaries with the following command: + +.. code-block:: console + + ./devbuild.sh --platform= + +where ```` is replaced with the name of the platform the user is working on. Valid values include: ``cheyenne`` | ``gaea`` | ``hera`` | ``jet`` | ``linux`` | ``macos`` | ``noaacloud`` | ``orion`` + +.. note:: + Although build modulefiles exist for generic Linux and MacOS machines, users will need to alter these according to the instructions in Sections :numref:`%s ` & :numref:`%s `. Users on these systems may have more success building the SRW App with the :ref:`CMake Approach ` instead. + +If compiler auto-detection fails for some reason, specify it using the ``--compiler`` argument. For example: + +.. code-block:: console + + ./devbuild.sh --platform=hera --compiler=intel + +where valid values are ``intel`` or ``gnu``. + +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. + +If users want to build the optional ``GSI`` and ``rrfs_utl`` components for :term:`RRFS`, they can pass the ``gsi`` and ``rrfs_utils`` arguments to ``devbuild.sh``. For example: + +.. code-block:: console + + ./devbuild.sh -p=hera gsi rrfs_utils + +.. note:: + RRFS capabilities are currently build-only features. They are not yet available for use at runtime. + +The last few lines of the RRFS console output should be: + +.. code-block:: console + + [100%] Built target RRFS_UTILS + Install the project... + -- Install configuration: "RELEASE" + -- Installing: /path/to/ufs-srweather-app/exec/ufs_srweather_app.settings + +After running ``devbuild.sh``, the executables listed in :numref:`Table %s ` should appear in the ``ufs-srweather-app/exec`` directory. If users choose to build the ``GSI`` and ``rrfs_utils`` components, the executables listed in :numref:`Table %s ` will also appear there. If the ``devbuild.sh`` build method does not work, or if users are not on a supported machine, they will have to manually set up the environment and build the SRW App binaries with CMake as described in :numref:`Section %s `. + +.. _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 | + +------------------------+---------------------------------------------------------------------------------+ + | 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 | + +------------------------+---------------------------------------------------------------------------------+ + | filter_topo | Filters topography based on resolution | + +------------------------+---------------------------------------------------------------------------------+ + | fregrid | Remaps data from the input mosaic grid to the output mosaic grid | + +------------------------+---------------------------------------------------------------------------------+ + | fvcom_to_FV3 | Determines lake surface conditions for the Great Lakes | + +------------------------+---------------------------------------------------------------------------------+ + | global_cycle | Updates the GFS surface conditions using external snow and sea ice analyses | + +------------------------+---------------------------------------------------------------------------------+ + | global_equiv_resol | Calculates a global, uniform, cubed-sphere equivalent resolution for the | + | | regional Extended Schmidt Gnomonic (ESG) grid | + +------------------------+---------------------------------------------------------------------------------+ + | inland | Creates an inland land mask by determining inland (i.e., non-coastal) points | + | | and assigning a value of 1. Default value is 0. | + +------------------------+---------------------------------------------------------------------------------+ + | lakefrac | Calculates the ratio of the lake area to the grid cell area at each atmospheric | + | | grid point. | + +------------------------+---------------------------------------------------------------------------------+ + | make_hgrid | Computes geo-referencing parameters (e.g., latitude, longitude, grid cell area) | + | | for global uniform grids | + +------------------------+---------------------------------------------------------------------------------+ + | make_solo_mosaic | Creates mosaic files with halos | + +------------------------+---------------------------------------------------------------------------------+ + | orog | Generates orography, land mask, and gravity wave drag files from fixed files | + +------------------------+---------------------------------------------------------------------------------+ + | orog_gsl | Creates orographic statistics fields required for the orographic drag suite | + | | developed by NOAA's Global Systems Laboratory (GSL) | + +------------------------+---------------------------------------------------------------------------------+ + | 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 lateral boundary | + | | conditions (LBCs) in the orography and grid files | + +------------------------+---------------------------------------------------------------------------------+ + | upp.x | Post processor for the model output | + +------------------------+---------------------------------------------------------------------------------+ + | ufs_model | UFS Weather Model executable | + +------------------------+---------------------------------------------------------------------------------+ + | vcoord_gen | Generates hybrid coordinate interface profiles | + +------------------------+---------------------------------------------------------------------------------+ + +.. _RRFSexec: + +.. table:: Names and descriptions of the executables produced when the RRFS option is enabled + + +----------------------------+-----------------------------------------------------------------------------+ + | **Executable Name** | **Description** | + +============================+=============================================================================+ + | gsi.x | Runs the Gridpoint Statistical Interpolation (GSI). | + +----------------------------+-----------------------------------------------------------------------------+ + | enkf.x | Runs the Ensemble Kalman Filter. | + +----------------------------+-----------------------------------------------------------------------------+ + | adjust_soiltq.exe | Uses the lowest-level temperature and moisture analysis increments to | + | | adjust the soil moisture and soil temperature after analysis. | + +----------------------------+-----------------------------------------------------------------------------+ + | check_imssnow_fv3lam.exe | This is a tool used to read snow and ice fields from surface files and | + | | check those fields. | + +----------------------------+-----------------------------------------------------------------------------+ + | fv3lam_nonvarcldana.exe | Runs the non-variational cloud and precipitable hydrometeor analysis based | + | | on the METAR cloud observations, satellite retrieved cloud top products, | + | | and radar reflectivity. | + +----------------------------+-----------------------------------------------------------------------------+ + | gen_annual_maxmin_GVF.exe | Generates maximum and minimum greenness vegetation fraction (GVF) files | + | | based on year-long GVF observations for the ``update_GVF`` process. | + +----------------------------+-----------------------------------------------------------------------------+ + | gen_cs.exe | NCL scripts to do cross section plotting. | + +----------------------------+-----------------------------------------------------------------------------+ + | gen_ensmean_recenter.exe | Runs the ensemble mean/recentering calculation for FV3LAM ensemble files. | + +----------------------------+-----------------------------------------------------------------------------+ + | lakesurgery.exe | Replaces the existing lake depth with the GLOBathy bathymetry. It is | + | | designed to work with the HRRR model. | + +----------------------------+-----------------------------------------------------------------------------+ + | nc_diag_cat.x | Performs :term:`NetCDF` Diagnostic Concatenation. Reads metadata while | + | | allocating necessary space, defines variables with the metadata (no | + | | attributes are stored), then finally add data to the output file. | + | | This is the MPI executable. | + +----------------------------+-----------------------------------------------------------------------------+ + | process_imssnow_fv3lam.exe | Uses FV3LAM snow and ice fields based on the snow and ice information from | + | | imssnow. | + +----------------------------+-----------------------------------------------------------------------------+ + | process_larccld.exe | Processes NASA Langley cloud top product, which reads the cloud top | + | | pressure, temperature, etc. and maps them to the ESG grid. | + +----------------------------+-----------------------------------------------------------------------------+ + | process_Lightning.exe | Processes lightning data. Reads NLDN NetCDF observation files and map the | + | | lightning observations into FV3LAM ESG grid. | + +----------------------------+-----------------------------------------------------------------------------+ + | process_metarcld.exe | Processes METAR ceilometer cloud observations. Reads the cloud base and | + | | coverage observations from PrepBUFR and distributes the cloud, weather, | + | | and visibility observations to the ESG grid. | + +----------------------------+-----------------------------------------------------------------------------+ + | process_NSSL_mosaic.exe | Processes :term:`NSSL` MRMS radar reflectivity mosaic observations. Reads | + | | 33-level NSSL MRMS radar reflectivity grib2 files and then interpolates the | + | | reflectivity horizontally to the ESG grid. | + +----------------------------+-----------------------------------------------------------------------------+ + | process_updatesst.exe | Updates Sea Surface Temperature (SST) field based on the SST analysis from | + | | NCEP. | + +----------------------------+-----------------------------------------------------------------------------+ + | ref2tten.exe | Calculates temperature tendency based on the radar reflectivity observation | + | | at each grid point. This temperature tendency can be used by the model | + | | during integration as latent heating initialization for ongoing | + | | precipitation systems, especially convection. | + +----------------------------+-----------------------------------------------------------------------------+ + | test_nc_unlimdims.x | Checks to see the number of fields with unlimited dimensions in NetCDF | + | | files. | + +----------------------------+-----------------------------------------------------------------------------+ + | ufs_srweather_app.settings | | + +----------------------------+-----------------------------------------------------------------------------+ + | update_bc.exe | Adjusts 0-h boundary conditions based on the analysis results during data | + | | assimilation cycling. | + +----------------------------+-----------------------------------------------------------------------------+ + | update_GVF.exe | Updates the GVF in the surface file based on the real-time observation | + | | files. | + +----------------------------+-----------------------------------------------------------------------------+ + | update_ice.exe | Replaces ice fields in warm start surface files based on the forecast from | + | | cold start forecast using the GFS as the initial file. | + +----------------------------+-----------------------------------------------------------------------------+ + | use_raphrrr_sfc.exe | Uses RAP and HRRR surface fields to replace the surface fields in FV3LAM. | + | | This is only used for starting the RRFS surface cycling. | + +----------------------------+-----------------------------------------------------------------------------+ + +.. COMMENT: What does ufs_srweather_app.settings do? + - precipitable hydrometeor analysis? + - What does the update_ice.exe description mean? + + +.. _CMakeApproach: + +CMake Approach +----------------- + +Set Up the Build Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. attention:: + * If users successfully built the executables in :numref:`Table %s `, they should skip to step :numref:`Chapter %s `. + * Users who want to build the SRW App on MacOS or generic Linux systems should skip to :numref:`Section %s ` and follow the approach there. + +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, users can run one of the following two commands depending on whether they have a bash or csh shell, respectively: + +.. code-block:: console + + source etc/lmod-setup.sh gaea + source etc/lmod-setup.csh gaea + +.. note:: + + If users execute one of the above commands on systems that don't need it, it will not cause any problems (it will simply do a ``module purge``). + +From here, ``Lmod`` is ready to load the modulefiles needed by the SRW App. These modulefiles are located in the ``modulefiles`` directory. To load the necessary modulefile for a specific ```` using a given ````, 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 (including generic Linux/MacOS 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, depending on whether they are using a bash or csh/tcsh shell, respectively: + +.. code-block:: + + export = + setenv + +Note that building the SRW App without Lmod is not supported at this time. It should be possible to do so, but it has not been tested. Users are encouraged to install Lmod on their system. + +.. _BuildCMake: + +Build the Executables Using CMake +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After setting up the build environment in the preceding section (by loading the ``build__`` modulefile), users need to build the executables required to run the SRW App. 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=.. -DCMAKE_INSTALL_BINDIR=exec .. + make -j 4 >& build.out & + +``-DCMAKE_INSTALL_PREFIX`` specifies the location where the ``exec``, ``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`` 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., ``-j 8``, ``-j 2``), 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/exec`` directory. These executables are described in :numref:`Table %s `. + +.. hint:: + + If you see the ``build.out`` file, but there is no ``ufs-srweather-app/exec`` directory, wait a few more minutes for the build to complete. + +.. _MacLinuxDetails: + +Additional Details for Building on MacOS or Generic Linux +------------------------------------------------------------ + +.. note:: + Users who are **not** building the SRW App on MacOS or generic Linux platforms may skip to :numref:`Section %s ` to finish building the SRW App or continue to :numref:`Chapter %s ` to configure and run an experiment. + +The SRW App can be built on MacOS and generic Linux machines after the prerequisite software has been installed on these systems (via :term:`HPC-Stack` or :term:`spack-stack`). The installation for MacOS is architecture-independent and has been tested using both x86_64 and M1 chips (running natively). The following configurations for MacOS have been tested: + + #. MacBookPro 2019, 2.4 GHz 8-core Intel Core i9 (x86_64), Monterey Sur 12.1, GNU compiler suite v.11.3.0 (gcc, gfortran, g++); mpich 3.3.2 or openmpi/4.1.2 + #. MacBookAir 2020, M1 chip (arm64, running natively), 4+4 cores, Big Sur 11.6.4, GNU compiler suite v.11.3.0 (gcc, gfortran, g++); mpich 3.3.2 or openmpi/4.1.2 + #. MacBook Pro 2015, 2.8 GHz Quad-Core Intel Core i7 (x86_64), Catalina OS X 10.15.7, GNU compiler suite v.11.2.0_3 (gcc, gfortran, g++); mpich 3.3.2 or openmpi/4.1.2 + +Several Linux builds have been tested on systems with x86_64 architectures. + +The ``./modulefiles/build__gnu.lua`` modulefile (where ```` is ``macos`` or ``linux``) is written as a Lmod module in the Lua language, and it can be loaded once the Lmod module environment has been initialized (which should have happened even prior to :ref:`installing HPC-Stack `). This module lists the location of the HPC-Stack modules, loads the meta-modules and modules, sets serial and parallel compilers, additional flags, and any environment variables needed for building the SRW App. The modulefile must be modified to include the absolute path to the user's HPC-Stack installation: + +.. code-block:: console + + - This path should point to your HPCstack installation directory + local HPCstack="/Users/username/hpc-stack/install" + +Linux users need to configure the ``ufs-srweather-app/etc/lmod-setup.sh`` file for the ``linux`` case and set the ``BASH_ENV`` variable to point to the Lmod initialization script. There is no need to modify this script for the ``macos`` case presuming that Lmod followed a standard installation procedure using the Homebrew package manager for MacOS. + +Next, users must source the Lmod setup file, just as they would on other systems, and load the modulefiles needed for building and running the SRW App: + +.. code-block:: console + + source etc/lmod-setup.sh + module use + module load build__gnu + export LDFLAGS+=" -L${MPI_ROOT}/lib " + +In a csh/tcsh shell, users would run ``source etc/lmod-setup.csh `` in place of the first line in the code block above. The last line is primarily needed for the MacOS platforms. + +Proceed to building the executables using the process outlined in :numref:`Step %s `. + +Run an Experiment +===================== + +To configure and run an experiment, users should proceed to :numref:`Chapter %s `. diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst new file mode 100644 index 0000000000..8515e097a3 --- /dev/null +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -0,0 +1,390 @@ +.. _QuickstartC: + +==================================== +Container-Based Quick Start Guide +==================================== + +This Container-Based Quick Start Guide will help users build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a `Singularity `__ container. The :term:`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:`MPIs `, and package versions available. Installation via Singularity container reduces this variability and allows for a smoother SRW App build experience. Normally, containers can only run on a single compute node and are not compatible with the `Rocoto workflow manager `__, so users must run each task in the workflow manually. However, the Singularity container described in this chapter has been adapted such that it is able to run across multiple nodes using Rocoto. This makes it an excellent starting point for beginners. The :ref:`non-container build approach ` may still be more appropriate for 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 16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. + +.. attention:: + + * The SRW Application has `four levels of support `__. 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. + * This chapter of the User's Guide should **only** be used for container builds. For non-container builds, see :numref:`Chapter %s ` for a Quick Start Guide or :numref:`Chapter %s ` for a detailed guide to building the SRW App **without** a container. + +.. _DownloadCodeC: + +Download the Container +=========================================== + +Prerequisites: +------------------- + +Users must have an **Intel** compiler and :term:`MPI` (available for free `here `__) in order to run the SRW App in the container provided using the method described in this chapter. Additionally, it is recommended that users install the `Rocoto workflow manager `__ on their system in order to take advantage of automated workflow options. Although it is possible to run an experiment without Rocoto, and some tips are provided, the only fully-supported and tested container option for the ``develop`` branch assumes that Rocoto is pre-installed. + +.. COMMENT: Remove "for the develop branch"? + +Install Singularity +^^^^^^^^^^^^^^^^^^^^^^^ + +To build and run the SRW App using a Singularity container, first install the Singularity package according to the `Singularity Installation Guide `__. This will include the installation of dependencies and the installation of the Go programming language. SingularityCE Version 3.7 or above is recommended. + +.. warning:: + Docker containers can only be run with root privileges, and users cannot have root privileges on :term:`HPCs `. Therefore, it is not possible to build the SRW App, which uses the HPC-Stack, inside a Docker container on an HPC system. However, a Singularity image may be built directly from a Docker image for use on the system. + +Working in the Cloud or on HPC Systems +----------------------------------------- + +For users working on systems with limited disk space in their ``/home`` directory, it is recommended to set the ``SINGULARITY_CACHEDIR`` and ``SINGULARITY_TMPDIR`` environment variables to point to a location with adequate disk space. For example: + +.. code-block:: + + export SINGULARITY_CACHEDIR= + export SINGULARITY_TMPDIR= + +where ``/absolute/path/to/writable/directory/`` refers to a writable directory (usually a project or user directory within ``/lustre``, ``/work``, ``/scratch``, or ``/glade`` on NOAA Level 1 systems). If the ``cache`` and ``tmp`` directories do not exist already, they must be created with a ``mkdir`` command. + +On NOAA Cloud systems, the ``sudo su`` command may also be required: + +.. code-block:: + + mkdir /lustre/cache + mkdir /lustre/tmp + sudo su + export SINGULARITY_CACHEDIR=/lustre/cache + export SINGULARITY_TMPDIR=/lustre/tmp + exit + +.. 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. + +.. _BuildC: + +Build the Container +------------------------ + +.. hint:: + If a ``singularity: command not found`` error message appears in any of the following steps, try running: ``module load singularity``. + +Level 1 Systems +^^^^^^^^^^^^^^^^^^ + +On most Level 1 systems, a container named ``ubuntu20.04-intel-srwapp-develop.img`` has already been built at the following locations: + +.. table:: Locations of pre-built containers + + +--------------+--------------------------------------------------------+ + | Machine | File location | + +==============+========================================================+ + | Cheyenne | /glade/scratch/epicufsrt/containers | + +--------------+--------------------------------------------------------+ + | Hera | /scratch1/NCEPDEV/nems/role.epic/containers | + +--------------+--------------------------------------------------------+ + | Jet | /mnt/lfs4/HFIP/hfv3gfs/role.epic/containers | + +--------------+--------------------------------------------------------+ + | NOAA Cloud | /contrib/EPIC/containers | + +--------------+--------------------------------------------------------+ + | Orion | /work/noaa/epic-ps/role-epic-ps/containers | + +--------------+--------------------------------------------------------+ + +.. note:: + Singularity is not available on Gaea, and therefore container use is not supported on Gaea. + +Users can simply copy the container to their local working directory. For example, on Hera: + +.. code-block:: console + + cp /scratch1/NCEPDEV/nems/role.epic/containers/ubuntu20.04-intel-srwapp-develop.img . + +Users may convert the container ``.img`` file to a writable sandbox. This step is required when running on Cheyenne but is optional on other systems: + +.. code-block:: console + + singularity build --sandbox ubuntu20.04-intel-srwapp ubuntu20.04-intel-srwapp-develop.img + +When making a writable sandbox on Level 1 systems, the following warnings commonly appear and can be ignored: + +.. code-block:: console + + INFO: Starting build... + INFO: Verifying bootstrap image ubuntu20.04-intel-srwapp-develop.img + WARNING: integrity: signature not found for object group 1 + WARNING: Bootstrap image could not be verified, but build will continue. + +Level 2-4 Systems +^^^^^^^^^^^^^^^^^^^^^ + +On non-Level 1 systems, users should build the container in a writable sandbox: + +.. code-block:: console + + sudo singularity build --sandbox ubuntu20.04-intel-srwapp docker://noaaepic/ubuntu20.04-intel-srwapp:develop + +Some users may prefer to issue the command without the ``sudo`` prefix. Whether ``sudo`` is required is system-dependent. + +.. note:: + Users can choose to build a release version of the container (SRW App v2.1.0) using a similar command: + + .. code-block:: console + + sudo singularity build --sandbox ubuntu20.04-intel-srwapp docker://noaaepic/ubuntu20.04-intel-srwapp:release-public-v2.1.0 + + +.. _WorkOnHPC: + +Allocate a Compute Node +-------------------------- + +Users working on HPC systems that do **not** have Rocoto installed must `install Rocoto `__ or allocate a compute node. All other users may skip to the :ref:`next step `. + +.. note:: + + All NOAA Level 1 systems have Rocoto pre-installed. + +The appropriate commands for allocating a compute node will vary based on the user's system and resource manager (e.g., Slurm, PBS). If the user's system has the Slurm resource manager, the allocation command will follow this pattern: + +.. code-block:: console + + salloc -N 1 -n -A -t file -c -t + +where + +* ``-c`` is the cycle to query in YYYYMMDDHHmm format +* ``-t`` is the task name (e.g., ``make_grid``, ``get_extrn_ics``, ``run_fcst``). + +The cycle and task names appear in the first and second columns of the table output by ``rocotostat``. + +A specific example is: + +.. code-block:: console + + rocotocheck -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201907010000 -t run_fcst + +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/ush/load_modules_run_task.sh "run_fcst" "/scratch2/BMC/det/$USER/ufs-srweather-app/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: - + + Job: 513615 + State: DEAD (FAILED) + Exit Status: 1 + Tries: 3 + Unknown count: 0 + Duration: 58.0 + +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 (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 +dependency "is NOT satisfied". + +rocotorewind +============= +``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 for ``rocotocheck`` +(in :numref:`Section %s `), and the general usage statement looks like this: + +.. code-block:: console + + 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 the ``rocotorewind`` +command to rerun the forecast task from ``$EXPTDIR`` is: + +.. code-block:: console + + 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 the ``$EXPTDIR`` is: + +.. code-block:: console + + rocotoboot -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201907010000 -t make_ics + diff --git a/docs/UsersGuide/source/Reference/index.rst b/docs/UsersGuide/source/Reference/index.rst new file mode 100644 index 0000000000..df3659a4d6 --- /dev/null +++ b/docs/UsersGuide/source/Reference/index.rst @@ -0,0 +1,14 @@ +.. UFS SR Weather App Users Guide, created by + sphinx-quickstart on Tue Feb 12 08:48:32 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +UFS Short-Range Weather App Users Guide +======================================= + +.. toctree:: + :maxdepth: 3 + + RocotoInfo + FAQ + Glossary diff --git a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst new file mode 100644 index 0000000000..fc7b5e1391 --- /dev/null +++ b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst @@ -0,0 +1,1248 @@ +.. _ConfigWorkflow: + +================================================================================================ +Workflow Parameters: Configuring the Workflow in ``config.yaml`` and ``config_defaults.yaml`` +================================================================================================ +To create the experiment directory and workflow when running the SRW Application, the user must create an experiment configuration file (usually named ``config.yaml``). This file contains experiment-specific information, such as forecast dates, grid and physics suite choices, data directories, and other relevant settings. To help the user, two sample configuration files have been included in the ``ush`` directory: ``config.community.yaml`` and ``config.nco.yaml``. The first is for running experiments in *community* mode (``RUN_ENVIR`` set to "community"), and the second is for running experiments in *nco* mode (``RUN_ENVIR`` set to "nco"). The content of these files can be copied into ``config.yaml`` and used as the starting point from which to generate a variety of experiment configurations for the SRW App. Note that for this release, only *community* mode is supported. + +There is an extensive list of experiment parameters that a user can set when configuring the experiment. Not all of these parameters need to be set explicitly by the user in ``config.yaml``. If a user does not define a variable in the ``config.yaml`` script, its value in ``config_defaults.yaml`` will be used, or the value will be reset depending on other parameters, such as the platform (``MACHINE``) selected for the experiment. + +.. note:: + The ``config_defaults.yaml`` file contains the full list of experiment parameters that a user may set in ``config.yaml``. The user cannot set parameters in ``config.yaml`` that are not initialized in ``config_defaults.yaml``, with the notable exception in the ``rocoto`` section, described in :numref:`Chapter %s `. + +The following is a list of the parameters in the ``config_defaults.yaml`` file. For each parameter, the default value and a brief description is provided. + +.. _user: + +USER Configuration Parameters +================================= + +If non-default parameters are selected for the variables in this section, they should be added to the ``user:`` section of the ``config.yaml`` file. + +``RUN_ENVIR``: (Default: "nco") + This variable determines the workflow mode. The user can choose between two options: "nco" and "community". The "nco" mode uses a directory structure that mimics what is used in operations at NOAA/NCEP Central Operations (NCO) and at the NOAA/NCEP/Environmental Modeling Center (EMC), which works with NCO on pre-implementation testing. Specifics of the conventions used in "nco" mode can be found in the following `WCOSS Implementation Standards `__ document: + + | NCEP Central Operations + | WCOSS Implementation Standards + | January 19, 2022 + | Version 11.0.0 + + Setting ``RUN_ENVIR`` to "community" is recommended in most cases for users who are not planning to implement their code into operations at NCO. Valid values: ``"nco"`` | ``"community"`` + +``MACHINE``: (Default: "BIG_COMPUTER") + The machine (a.k.a. platform or system) on which the workflow will run. Currently supported platforms are listed on the `SRW App Wiki page `__. When running the SRW App on any ParellelWorks/NOAA Cloud system, use "NOAACLOUD" regardless of the underlying system (AWS, GCP, or Azure). Valid values: ``"HERA"`` | ``"ORION"`` | ``"JET"`` | ``"CHEYENNE"`` | ``"GAEA"`` | ``"NOAACLOUD"`` | ``"STAMPEDE"`` | ``"ODIN"`` | ``"MACOS"`` | ``"LINUX"`` | ``"SINGULARITY"`` | ``"WCOSS2"`` + + .. hint:: + Users who are NOT on a named, supported Level 1 or 2 platform will need to set the ``MACHINE`` variable to ``LINUX`` or ``MACOS``; to combine use of a Linux or MacOS platform with the Rocoto workflow manager, users will also need to set ``WORKFLOW_MANAGER: "rocoto"`` in the ``platform:`` section of ``config.yaml``. This combination will assume a Slurm batch manager when generating the XML. + +``MACHINE_FILE``: (Default: "") + Path to a configuration file with machine-specific settings. If none is provided, ``setup.py`` will attempt to set the path to a configuration file for a supported platform. + +``ACCOUNT``: (Default: "project_name") + The account under which users submit jobs to the queue on the specified ``MACHINE``. To determine an appropriate ``ACCOUNT`` field for `Level 1 `__ systems, users may run the ``groups`` command, which will return a list of projects that the user has permissions for. Not all of the listed projects/groups have an HPC allocation, but those that do are potentially valid account names. On some systems, the ``saccount_params`` command will display additional account details. + +.. _PlatformConfig: + +PLATFORM Configuration Parameters +===================================== + +If non-default parameters are selected for the variables in this section, they should be added to the ``platform:`` section of the ``config.yaml`` file. + +``WORKFLOW_MANAGER``: (Default: "none") + The workflow manager to use (e.g., "rocoto"). This is set to "none" by default, but if the machine name is set to a platform that supports Rocoto, this will be overwritten and set to "rocoto." If set explicitly to "rocoto" along with the use of the ``MACHINE: "LINUX"`` target, the configuration layer assumes a Slurm batch manager when generating the XML. Valid values: ``"rocoto"`` | ``"none"`` + +``NCORES_PER_NODE``: (Default: "") + The number of cores available per node on the compute platform. Set for supported platforms in ``setup.py``, but it is now also configurable for all platforms. + +``BUILD_MOD_FN``: (Default: "") + Name of an alternative build module file to use if running on an unsupported platform. It is set automatically for supported machines. + +``WFLOW_MOD_FN``: (Default: "") + Name of an alternative workflow module file to use if running on an unsupported platform. It is set automatically for supported machines. + +``BUILD_VER_FN``: (Default: "") + File name containing the version of the modules used for building the app. Currently, WCOSS2 only uses this file. + +``RUN_VER_FN``: (Default: "") + File name containing the version of the modules used for running the app. Currently, WCOSS2 only uses this file. + +.. _sched: + +``SCHED``: (Default: "") + The job scheduler to use (e.g., Slurm) on the specified ``MACHINE``. Leaving this an empty string allows the experiment generation script to set it automatically depending on the machine the workflow is running on. Valid values: ``"slurm"`` | ``"pbspro"`` | ``"lsf"`` | ``"lsfcray"`` | ``"none"`` + +``SCHED_NATIVE_CMD``: (Default: "") + Allows an extra parameter to be passed to the job scheduler (Slurm or PBSPRO) via XML Native command. + +``DOMAIN_PREGEN_BASEDIR``: (Default: "") + For use in NCO mode only (``RUN_ENVIR: "nco"``). The base directory containing pregenerated grid, orography, and surface climatology files. This is an alternative for setting ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` individually. For the pregenerated grid specified by ``PREDEF_GRID_NAME``, these "fixed" files are located in: + + .. code-block:: console + + ${DOMAIN_PREGEN_BASEDIR}/${PREDEF_GRID_NAME} + + The workflow scripts will create a symlink in the experiment directory that will point to a subdirectory (having the same name as the experiment grid) under this directory. This variable should be set to a null string in ``config_defaults.yaml``, but it can be changed in the user-specified workflow configuration file set by ``EXPT_CONFIG_FN`` (usually ``config.yaml``). + +``PRE_TASK_CMDS``: (Default: "") + Pre-task commands such as ``ulimit`` needed by tasks. For example: ``'{ ulimit -s unlimited; ulimit -a; }'`` + +Machine-Dependent Parameters +------------------------------- +These parameters vary depending on machine. On `Level 1 and 2 `__ systems, the appropriate values for each machine can be viewed in the ``ush/machine/.sh`` scripts. To specify a value other than the default, add these variables and the desired value in the ``config.yaml`` file so that they override the ``config_defaults.yaml`` and machine default values. + +``PARTITION_DEFAULT``: (Default: "") + This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). This is the default partition to which Slurm submits workflow tasks. When a variable that designates the partition (e.g., ``PARTITION_HPSS``, ``PARTITION_FCST``; see below) is **not** specified, the task will be submitted to the default partition indicated in the ``PARTITION_DEFAULT`` variable. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"hera"`` | ``"normal"`` | ``"orion"`` | ``"sjet"`` | ``"vjet"`` | ``"kjet"`` | ``"xjet"`` | ``"workq"`` + +``QUEUE_DEFAULT``: (Default: "") + The default queue or QOS to which workflow tasks are submitted (QOS is Slurm's term for queue; it stands for "Quality of Service"). If the task's ``QUEUE_HPSS`` or ``QUEUE_FCST`` parameters (see below) are not specified, the task will be submitted to the queue indicated by this variable. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` + +``PARTITION_HPSS``: (Default: "") + This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). Tasks that get or create links to external model files are submitted to the partition specified in this variable. These links are needed to generate initial conditions (:term:`ICs`) and lateral boundary conditions (:term:`LBCs`) for the experiment. If this variable is not set or is set to an empty string, it will be (re)set to the ``PARTITION_DEFAULT`` value (if set) or to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"normal"`` | ``"service"`` | ``"workq"`` + +``QUEUE_HPSS``: (Default: "") + Tasks that get or create links to external model files are submitted to this queue, or QOS (QOS is Slurm's term for queue; it stands for "Quality of Service"). These links are needed to generate initial conditions (:term:`ICs`) and lateral boundary conditions (:term:`LBCs`) for the experiment. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev_transfer"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` + +``PARTITION_FCST``: (Default: "") + This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). The task that runs forecasts is submitted to this partition. If this variable is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"hera"`` | ``"normal"`` | ``"orion"`` | ``"sjet"`` | ``"vjet"`` | ``"kjet"`` | ``"xjet"`` | ``"workq"`` + +``QUEUE_FCST``: (Default: "") + The task that runs a forecast is submitted to this queue, or QOS (QOS is Slurm's term for queue; it stands for "Quality of Service"). If this variable is not set or set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` + +Parameters for Running Without a Workflow Manager +----------------------------------------------------- +These settings define the run commands for the platform. + +``RUN_CMD_UTILS``: (Default: "mpirun -np 1") + 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``). 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. + +``RUN_CMD_POST``: (Default: "mpirun -np 1") + The run command for post-processing (via the :term:`UPP`). Can be left blank for smaller domains, in which case UPP will run without :term:`MPI`. + + +METplus Parameters +---------------------- + +:ref:`METplus ` is a scientific verification framework that spans a wide range of temporal and spatial scales. Many of the METplus parameters are described below, but additional documentation for the METplus components is available on the `METplus website `__. + +``MODEL``: (Default: "") + A descriptive name of the user's choice for the model being verified. + +``MET_INSTALL_DIR``: (Default: "") + Path to top-level directory of MET installation. + +``METPLUS_PATH``: (Default: "") + Path to top-level directory of METplus installation. + +``MET_BIN_EXEC``: (Default: "") + Name of subdirectory where METplus executables are installed. + +.. _METParamNote: + +.. note:: + Where a date field is required: + * ``YYYY`` refers to the 4-digit valid year + * ``MM`` refers to the 2-digit valid month + * ``DD`` refers to the 2-digit valid day of the month + * ``HH`` refers to the 2-digit valid hour of the day + * ``mm`` refers to the 2-digit valid minutes of the hour + * ``SS`` refers to the two-digit valid seconds of the hour + +``CCPA_OBS_DIR``: (Default: "") + 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_CCPA`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify.yaml``). + + METplus configuration files require the use of a 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 (``scripts/exregional_get_obs_ccpa.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_obs_ccpa.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 :term:`HPSS` (if the user has access) via the ``GET_OBS_MRMS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify.yaml``). 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 that retrieves 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: ``scripts/exregional_get_obs_mrms.sh``. This script calls the script used to identify the MRMS file closest to the valid time: ``ush/mrms_pull_topofhour.py``. + +``NDAS_OBS_DIR``: (Default: "") + User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_NDAS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. Please note, this path must be defined as ``//ndas/proc``. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. + + METplus configuration files require the use of predetermined file names. Therefore, if the NDAS files are user-provided, they need to follow the anticipated naming structure: ``prepbufr.ndas.{YYYYMMDDHH}``, where YYYYMMDDHH is as described in the note :ref:`above `. The script to pull the NDAS data from the NOAA HPSS (``scripts/exregional_get_obs_ndas.sh``) has an example of how to rename the NDAS data into a more intuitive format with the valid time listed in the file name. + +Test Directories +---------------------- + +These directories are used only by the ``run_WE2E_tests.py`` script, so they are not used unless the user runs a Workflow End-to-End (WE2E) test (see :numref:`Chapter %s `). Their function corresponds to the same variables without the ``TEST_`` prefix. Users typically should not modify these variables. For any alterations, the logic in the ``run_WE2E_tests.py`` script would need to be adjusted accordingly. + +``TEST_EXTRN_MDL_SOURCE_BASEDIR``: (Default: "") + This parameter allows testing of user-staged files in a known location on a given platform. This path contains a limited dataset and likely will not be useful for most user experiments. + +``TEST_PREGEN_BASEDIR``: (Default: "") + Similar to ``DOMAIN_PREGEN_BASEDIR``, this variable sets the base directory containing pregenerated grid, orography, and surface climatology files for WE2E tests. This is an alternative for setting ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` individually. + +``TEST_ALT_EXTRN_MDL_SYSBASEDIR_ICS``: (Default: "") + This parameter is used to test the mechanism that allows users to point to a data stream on disk. It sets up a sandbox location that mimics the stream in a more controlled way and tests the ability to access :term:`ICS`. + +``TEST_ALT_EXTRN_MDL_SYSBASEDIR_LBCS``: (Default: "") + This parameter is used to test the mechanism that allows users to point to a data stream on disk. It sets up a sandbox location that mimics the stream in a more controlled way and tests the ability to access :term:`LBCS`. + + +.. _workflow: + +WORKFLOW Configuration Parameters +===================================== + +If non-default parameters are selected for the variables in this section, they should be added to the ``workflow:`` section of the ``config.yaml`` file. + +.. _Cron: + +Cron-Associated Parameters +------------------------------ + +Cron is a job scheduler accessed through the command-line on UNIX-like operating systems. It is useful for automating tasks such as the ``rocotorun`` command, which launches each workflow task in the SRW App. Cron periodically checks a cron table (aka crontab) to see if any tasks are are ready to execute. If so, it runs them. + +``USE_CRON_TO_RELAUNCH``: (Default: false) + Flag that determines whether or not a line is added to the user's cron table, which calls the experiment launch script every ``CRON_RELAUNCH_INTVL_MNTS`` minutes. Valid values: ``True`` | ``False`` + +``CRON_RELAUNCH_INTVL_MNTS``: (Default: 3) + The interval (in minutes) between successive calls of the experiment launch script by a cron job to (re)launch the experiment (so that the workflow for the experiment kicks off where it left off). This is used only if ``USE_CRON_TO_RELAUNCH`` is set to true. + +.. _DirParams: + +Directory Parameters +----------------------- + +``EXPT_BASEDIR``: (Default: "") + The full path to the base directory in which the experiment directory (``EXPT_SUBDIR``) will be created. If this is not specified or if it is set to an empty string, it will default to ``${HOMEdir}/../expt_dirs``, where ``${HOMEdir}`` contains the full path to the ``ufs-srweather-app`` directory. If set to a relative path, the provided path will be appended to the default value ``${HOMEdir}/../expt_dirs``. For example, if ``EXPT_BASEDIR=some/relative/path`` (i.e. a path that does not begin with ``/``), the value of ``EXPT_BASEDIR`` used by the workflow will be ``EXPT_BASEDIR=${HOMEdir}/../expt_dirs/some/relative/path``. + +``EXPT_SUBDIR``: (Default: "") + The user-designated name of the experiment directory (*not* its full path). The full path to the experiment directory, which will be contained in the variable ``EXPTDIR``, will be: + + .. code-block:: console + + EXPTDIR="${EXPT_BASEDIR}/${EXPT_SUBDIR}" + + This parameter cannot be left as a null string. It must be set to a non-null value in the user-defined experiment configuration file (i.e., ``config.yaml``). + +``EXEC_SUBDIR``: (Default: "exec") + The name of the subdirectory of ``ufs-srweather-app`` where executables are installed. + +Pre-Processing File Separator Parameters +-------------------------------------------- + +``DOT_OR_USCORE``: (Default: "_") + This variable sets the separator character(s) to use in the names of the grid, mosaic, and orography fixed files. Ideally, the same separator should be used in the names of these fixed files as in the surface climatology fixed files. Valid values: ``"_"`` | ``"."`` + + +Set File Name Parameters +---------------------------- + +``EXPT_CONFIG_FN``: (Default: "config.yaml") + Name of the user-specified configuration file for the forecast experiment. + +``CONSTANTS_FN``: (Default: "constants.yaml") + Name of the file containing definitions of various mathematical, physical, and SRW App contants. + +``RGNL_GRID_NML_FN``: (Default: "regional_grid.nml") + Name of the file containing namelist settings for the code that generates an "ESGgrid" regional grid. + +``FV3_NML_BASE_SUITE_FN``: (Default: "input.nml.FV3") + Name of the Fortran file containing the forecast model's base suite namelist (i.e., the portion of the namelist that is common to all physics suites). + +``FV3_NML_YAML_CONFIG_FN``: (Default: "FV3.input.yml") + Name of YAML configuration file containing the forecast model's namelist settings for various physics suites. + +``FV3_NML_BASE_ENS_FN``: (Default: "input.nml.base_ens") + Name of the Fortran file containing the forecast model's base ensemble namelist (i.e., the original namelist file from which each of the ensemble members' namelist files is generated). + +``FV3_EXEC_FN``: (Default: "ufs_model") + Name to use for the forecast model executable. + +``DIAG_TABLE_TMPL_FN``: (Default: "") + Name of a template file that specifies the output fields of the forecast model. The selected physics suite is appended to this file name in ``setup.py``, taking the form ``{DIAG_TABLE_TMPL_FN}.{CCPP_PHYS_SUITE}``. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``diag_table.{CCPP_PHYS_SUITE}``), and users should **not** specify a value for ``DIAG_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the names of the ``diag_table`` options in the ``ufs-srweather-app/parm`` directory. + +``FIELD_TABLE_TMPL_FN``: (Default: "") + Name of a template file that specifies the :term:`tracers ` that the forecast model will read in from the :term:`IC/LBC ` files. The selected physics suite is appended to this file name in ``setup.py``, taking the form ``{FIELD_TABLE_TMPL_FN}.{CCPP_PHYS_SUITE}``. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``field_table.{CCPP_PHYS_SUITE}``), and users should **not** specify a different value for ``FIELD_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the names of the ``field_table`` options in the ``ufs-srweather-app/parm`` directory. + +``DATA_TABLE_TMPL_FN``: (Default: "") + Name of a template file that contains the data table read in by the forecast model. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``data_table``), and users should **not** specify a different value for ``DATA_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``data_table`` in the ``ufs-srweather-app/parm`` directory. + +``MODEL_CONFIG_TMPL_FN``: (Default: "") + Name of a template file that contains settings and configurations for the :term:`NUOPC`/:term:`ESMF` main component. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``model_configure``), and users should **not** specify a different value for ``MODEL_CONFIG_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``model_configure`` in the ``ufs-srweather-app/parm`` directory. + +``NEMS_CONFIG_TMPL_FN``: (Default: "") + Name of a template file that contains information about the various :term:`NEMS` components and their run sequence. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``nems.configure``), and users should **not** specify a different value for ``NEMS_CONFIG_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``nems.configure`` in the ``ufs-srweather-app/parm`` directory. + +``FCST_MODEL``: (Default: "ufs-weather-model") + Name of forecast model. Valid values: ``"ufs-weather-model"`` | ``"fv3gfs_aqm"`` + +``WFLOW_XML_FN``: (Default: "FV3LAM_wflow.xml") + Name of the Rocoto workflow XML file that the experiment generation script creates. This file defines the workflow for the experiment. + +``GLOBAL_VAR_DEFNS_FN``: (Default: "var_defns.sh") + Name of the file (a shell script) containing definitions of the primary and secondary experiment variables (parameters). This file is sourced by many scripts (e.g., the J-job scripts corresponding to each workflow task) in order to make all the experiment variables available in those scripts. The primary variables are defined in the default configuration script (``config_defaults.yaml``) and in ``config.yaml``. The secondary experiment variables are generated by the experiment generation script. + +``EXTRN_MDL_VAR_DEFNS_FN``: (Default: "extrn_mdl_var_defns") + Name of the file (a shell script) containing the definitions of variables associated with the external model from which :term:`ICs` or :term:`LBCs` are generated. This file is created by the ``GET_EXTRN_*`` task because the values of the variables it contains are not known before this task runs. The file is then sourced by the ``MAKE_ICS`` and ``MAKE_LBCS`` tasks. + +``WFLOW_LAUNCH_SCRIPT_FN``: (Default: "launch_FV3LAM_wflow.sh") + Name of the script that can be used to (re)launch the experiment's Rocoto workflow. + +``WFLOW_LAUNCH_LOG_FN``: (Default: "log.launch_FV3LAM_wflow") + Name of the log file that contains the output from successive calls to the workflow launch script (``WFLOW_LAUNCH_SCRIPT_FN``). + +.. _CCPP_Params: + +CCPP Parameter +------------------ + +``CCPP_PHYS_SUITE``: (Default: "FV3_GFS_v16") + This parameter indicates which :term:`CCPP` (Common Community Physics Package) physics suite to use for the forecast(s). The choice of physics suite determines the forecast model's namelist file, the diagnostics table file, the field table file, and the XML physics suite definition file, which are staged in the experiment directory or the :term:`cycle` directories under it. + + .. note:: + For information on *stochastic physics* parameters, see :numref:`Section %s `. + + **Current supported settings for the CCPP parameter are:** + + | ``"FV3_GFS_v16"`` + | ``"FV3_RRFS_v1beta"`` + | ``"FV3_HRRR"`` + | ``"FV3_WoFS_v0"`` + | ``"FV3_RAP"`` + + Other valid values can be found in the ``ush/valid_param_vals.yaml`` file, but users can not expect full support for these schemes. + + +.. _GridGen: + +Grid Generation Parameters +------------------------------ + +``GRID_GEN_METHOD``: (Default: "") + This variable specifies which method to use to generate a regional grid in the horizontal plane. The values that it can take on are: + + * ``"ESGgrid"``: The "ESGgrid" method will generate a regional version of the Extended Schmidt Gnomonic (ESG) grid using the map projection developed by Jim Purser of EMC (:cite:t:`Purser_2020`). "ESGgrid" is the preferred grid option. + + * ``"GFDLgrid"``: The "GFDLgrid" method first generates a "parent" global cubed-sphere grid. Then a portion from tile 6 of the global grid is used as the regional grid. This regional grid is referred to in the grid generation scripts as "tile 7," even though it does not correspond to a complete tile. The forecast is run only on the regional grid (i.e., on tile 7, not on tiles 1 through 6). Note that the "GFDLgrid" method is the legacy grid generation method. It is not supported in *all* predefined domains. + +.. attention:: + + If the experiment uses a **predefined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to the name of a valid predefined grid), then ``GRID_GEN_METHOD`` will be reset to the value of ``GRID_GEN_METHOD`` for that grid. This will happen regardless of whether ``GRID_GEN_METHOD`` is assigned a value in the experiment configuration file; any value assigned will be overwritten. + +.. note:: + + If the experiment uses a **user-defined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to a null string), then ``GRID_GEN_METHOD`` must be set in the experiment configuration file. Otherwise, the experiment generation will fail because the generation scripts check to ensure that the grid name is set to a non-empty string before creating the experiment directory. + +Forecast Parameters +---------------------- +``DATE_FIRST_CYCL``: (Default: "YYYYMMDDHH") + Starting date of the first forecast in the set of forecasts to run. Format is "YYYYMMDDHH". + +``DATE_LAST_CYCL``: (Default: "YYYYMMDDHH") + Starting date of the last forecast in the set of forecasts to run. Format is "YYYYMMDDHH". + +``INCR_CYCL_FREQ``: (Default: 24) + Increment in hours for Rocoto cycle frequency. The default is 24, which means cycl_freq=24:00:00. + +``FCST_LEN_HRS``: (Default: 24) + The length of each forecast, in integer hours. + +Pre-Existing Directory Parameter +------------------------------------ +``PREEXISTING_DIR_METHOD``: (Default: "delete") + This variable determines how to deal with pre-existing directories (resulting from previous calls to the experiment generation script using the same experiment name [``EXPT_SUBDIR``] as the current experiment). This variable must be set to one of three valid values: ``"delete"``, ``"rename"``, or ``"quit"``. The behavior for each of these values is as follows: + + * **"delete":** The preexisting directory is deleted and a new directory (having the same name as the original preexisting directory) is created. + + * **"rename":** The preexisting directory is renamed and a new directory (having the same name as the original pre-existing directory) is created. The new name of the preexisting directory consists of its original name and the suffix "_old###", where ``###`` is a 3-digit integer chosen to make the new name unique. + + * **"quit":** The preexisting directory is left unchanged, but execution of the currently running script is terminated. In this case, the preexisting directory must be dealt with manually before rerunning the script. + +Verbose Parameter +--------------------- +``VERBOSE``: (Default: true) + Flag that determines whether the experiment generation and workflow task scripts print out extra informational messages. Valid values: ``True`` | ``False`` + +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 be reset to true if it isn't already. Valid values: ``True`` | ``False`` + +Compiler +----------- + +``COMPILER``: (Default: "intel") + Type of compiler invoked during the build step. Currently, this must be set manually; it is not inherited from the build system in the ``ufs-srweather-app`` directory. Valid values: ``"intel"`` | ``"gnu"`` + +Verification Parameters +--------------------------- + +``GET_OBS``: (Default: "get_obs") + Set the name of the Rocoto workflow task used to load proper module files for ``GET_OBS_*`` tasks. Users typically do not need to change this value. + + +.. _NCOModeParms: + +NCO-Specific Variables +========================= + +A standard set of environment variables has been established for *nco* mode to simplify the production workflow and improve the troubleshooting process for operational and preoperational models. These variables are only used in *nco* mode (i.e., when ``RUN_ENVIR: "nco"``). When non-default parameters are selected for the variables in this section, they should be added to the ``nco:`` section of the ``config.yaml`` file. + +.. note:: + Only *community* mode is fully supported for this release. *nco* mode is used by those at the Environmental Modeling Center (EMC) and Global Systems Laboratory (GSL) who are working on pre-implementation operational testing. Other users should run the SRW App in *community* mode. + +``envir, NET, model_ver, RUN``: + Standard environment variables defined in the NCEP Central Operations WCOSS Implementation Standards document. These variables are used in forming the path to various directories containing input, output, and workflow files. The variables are defined in the `WCOSS Implementation Standards `__ document (pp. 4-5) as follows: + + ``envir``: (Default: "para") + Set to "test" during the initial testing phase, "para" when running in parallel (on a schedule), and "prod" in production. + + ``NET``: (Default: "rrfs") + Model name (first level of ``com`` directory structure) + + ``model_ver``: (Default: "v1.0.0") + Version number of package in three digits (second level of ``com`` directory) + + ``RUN``: (Default: "rrfs") + Name of model run (third level of ``com`` directory structure). In general, same as ``$NET``. + +``OPSROOT``: (Default: "") + The operations root directory in *nco* mode. + +.. _make-grid: + +MAKE_GRID Configuration Parameters +====================================== + +Non-default parameters for the ``make_grid`` task are set in the ``task_make_grid:`` section of the ``config.yaml`` file. + +Basic Task Parameters +-------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. Typically, users do not need to adjust the default values. + + ``GRID_DIR``: (Default: "") + The directory containing pre-generated grid files when the ``MAKE_GRID`` task is not meant to run. + +.. _ESGgrid: + +ESGgrid Settings +------------------- + +The following parameters must be set if using the "ESGgrid" method to generate a regional grid (i.e., when ``GRID_GEN_METHOD: "ESGgrid"``, see :numref:`Section %s `). If a different ``GRID_GEN_METHOD`` is used, these parameters will be ignored. When using a predefined grid with ``GRID_GEN_METHOD: "ESGgrid"``, the values in this section will be set automatically to the assigned values for that grid. + +``ESGgrid_LON_CTR``: (Default: "") + The longitude of the center of the grid (in degrees). + +``ESGgrid_LAT_CTR``: (Default: "") + The latitude of the center of the grid (in degrees). + +``ESGgrid_DELX``: (Default: "") + The cell size in the zonal direction of the regional grid (in meters). + +``ESGgrid_DELY``: (Default: "") + The cell size in the meridional direction of the regional grid (in meters). + +``ESGgrid_NX``: (Default: "") + The number of cells in the zonal direction on the regional grid. + +``ESGgrid_NY``: (Default: "") + The number of cells in the meridional direction on the regional grid. + +``ESGgrid_PAZI``: (Default: "") + The rotational parameter for the "ESGgrid" (in degrees). + +``ESGgrid_WIDE_HALO_WIDTH``: (Default: "") + The width (in number of grid cells) of the :term:`halo` to add around the regional grid before shaving the halo down to the width(s) expected by the forecast model. The user need not specify this variable since it is set automatically in ``set_gridparams_ESGgrid.py`` + +.. _WideHalo: + +.. note:: + A :term:`halo` is the strip of cells surrounding the regional grid; the halo is used to feed in the lateral boundary conditions to the grid. The forecast model requires **grid** files containing 3-cell- and 4-cell-wide halos and **orography** files with 0-cell- and 3-cell-wide halos. In order to generate grid and orography files with appropriately-sized halos, the grid and orography tasks create preliminary files with halos around the regional domain of width ``ESGgrid_WIDE_HALO_WIDTH`` cells. The files are then read in and "shaved" down to obtain grid files with 3-cell-wide and 4-cell-wide halos and orography files with 0-cell-wide and 3-cell-wide halos. The original halo that gets shaved down is referred to as the "wide" halo because it is wider than the 0-cell-wide, 3-cell-wide, and 4-cell-wide halos that users eventually end up with. Note that the grid and orography files with the wide halo are only needed as intermediates in generating the files with 0-cell-, 3-cell-, and 4-cell-wide halos; they are not needed by the forecast model. + +GFDLgrid Settings +--------------------- + +The following parameters must be set if using the "GFDLgrid" method to generate a regional grid (i.e., when ``GRID_GEN_METHOD: "GFDLgrid"``, see :numref:`Section %s `). If a different ``GRID_GEN_METHOD`` is used, these parameters will be ignored. When using a predefined grid with ``GRID_GEN_METHOD: "GFDLgrid"``, the values in this section will be set automatically to the assigned values for that grid. + +Note that the regional grid is defined with respect to a "parent" global cubed-sphere grid. Thus, all the parameters for a global cubed-sphere grid must be specified even though the model equations are integrated only on the regional grid. Tile 6 has arbitrarily been chosen as the tile to use to orient the global parent grid on the sphere (Earth). For convenience, the regional grid is denoted as "tile 7" even though it is embedded within tile 6 (i.e., it doesn't extend beyond the boundary of tile 6). Its exact location within tile 6 is determined by specifying the starting and ending i- and j-indices of the regional grid on tile 6, where ``i`` is the grid index in the x direction and ``j`` is the grid index in the y direction. All of this information is set in the variables below. + +``GFDLgrid_LON_T6_CTR``: (Default: "") + Longitude of the center of tile 6 (in degrees). + +``GFDLgrid_LAT_T6_CTR``: (Default: "") + Latitude of the center of tile 6 (in degrees). + +``GFDLgrid_NUM_CELLS``: (Default: "") + Number of grid cells in either of the two horizontal directions (x and y) on each of the six tiles of the parent global cubed-sphere grid. Valid values: ``48`` | ``96`` | ``192`` | ``384`` | ``768`` | ``1152`` | ``3072`` + + To give an idea of what these values translate to in terms of grid cell size in kilometers, we list below the approximate grid cell size on a uniform global grid having the specified value of ``GFDLgrid_NUM_CELLS``, where by "uniform" we mean with Schmidt stretch factor ``GFDLgrid_STRETCH_FAC: "1"`` (although in regional applications ``GFDLgrid_STRETCH_FAC`` will typically be set to a value greater than ``"1"`` to obtain a smaller grid size on tile 6): + + +---------------------+--------------------+ + | GFDLgrid_NUM_CELLS | Typical Cell Size | + +=====================+====================+ + | 48 | 200 km | + +---------------------+--------------------+ + | 96 | 100 km | + +---------------------+--------------------+ + | 192 | 50 km | + +---------------------+--------------------+ + | 384 | 25 km | + +---------------------+--------------------+ + | 768 | 13 km | + +---------------------+--------------------+ + | 1152 | 8.5 km | + +---------------------+--------------------+ + | 3072 | 3.2 km | + +---------------------+--------------------+ + + Note that these are only typical cell sizes. The actual cell size on the global grid tiles varies somewhat as we move across a tile and is also dependent on ``GFDLgrid_STRETCH_FAC``, which modifies the shape and size of the tile. + +``GFDLgrid_STRETCH_FAC``: (Default: "") + Stretching factor used in the Schmidt transformation applied to the parent cubed-sphere grid. Setting the Schmidt stretching factor to a value greater than 1 shrinks tile 6, while setting it to a value less than 1 (but still greater than 0) expands it. The remaining 5 tiles change shape as necessary to maintain global coverage of the grid. + +``GFDLgrid_REFINE_RATIO``: (Default: "") + Cell refinement ratio for the regional grid. It refers to the number of cells in either the x or y direction on the regional grid (tile 7) that abut one cell on its parent tile (tile 6). + +``GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G``: (Default: "") + i-index on tile 6 at which the regional grid (tile 7) starts. + +``GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G``: (Default: "") + i-index on tile 6 at which the regional grid (tile 7) ends. + +``GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G``: (Default: "") + j-index on tile 6 at which the regional grid (tile 7) starts. + +``GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G``: (Default: "") + j-index on tile 6 at which the regional grid (tile 7) ends. + +``GFDLgrid_USE_NUM_CELLS_IN_FILENAMES``: (Default: "") + Flag that determines the file naming convention to use for grid, orography, and surface climatology files (or, if using pregenerated files, the naming convention that was used to name these files). These files usually start with the string ``"C${RES}_"``, where ``RES`` is an integer. In the global forecast model, ``RES`` is the number of points in each of the two horizontal directions (x and y) on each tile of the global grid (defined here as ``GFDLgrid_NUM_CELLS``). If this flag is set to true, ``RES`` will be set to ``GFDLgrid_NUM_CELLS`` just as in the global forecast model. If it is set to false, we calculate (in the grid generation task) an "equivalent global uniform cubed-sphere resolution" --- call it ``RES_EQUIV`` --- and then set ``RES`` equal to it. ``RES_EQUIV`` is the number of grid points in each of the x and y directions on each tile that a global UNIFORM (i.e., stretch factor of 1) cubed-sphere grid would need to have in order to have the same average grid size as the regional grid. This is a more useful indicator of the grid size because it takes into account the effects of ``GFDLgrid_NUM_CELLS``, ``GFDLgrid_STRETCH_FAC``, and ``GFDLgrid_REFINE_RATIO`` in determining the regional grid's typical grid size, whereas simply setting ``RES`` to ``GFDLgrid_NUM_CELLS`` doesn't take into account the effects of ``GFDLgrid_STRETCH_FAC`` and ``GFDLgrid_REFINE_RATIO`` on the regional grid's resolution. Nevertheless, some users still prefer to use ``GFDLgrid_NUM_CELLS`` in the file names, so we allow for that here by setting this flag to true. + +.. _make-orog: + +MAKE_OROG Configuration Parameters +===================================== + +Non-default parameters for the ``make_orog`` task are set in the ``task_make_orog:`` section of the ``config.yaml`` file. + +``KMP_AFFINITY_MAKE_OROG``: (Default: "disabled") + Intel Thread Affinity Interface for the ``make_orog`` task. See :ref:`this note ` for more information on thread affinity. Settings for the ``make_orog`` task is disabled because this task does not use parallelized code. + +``OMP_NUM_THREADS_MAKE_OROG``: (Default: 6) + The number of OpenMP threads to use for parallel regions. + + + +``OMP_STACKSIZE_MAKE_OROG``: (Default: "2048m") + Controls the size of the stack for threads created by the OpenMP implementation. + +``OROG_DIR``: (Default: "") + The directory containing pre-generated orography files to use when the ``MAKE_OROG`` task is not meant to run. + +.. _make-sfc-climo: + +MAKE_SFC_CLIMO Configuration Parameters +=========================================== + +Non-default parameters for the ``make_sfc_climo`` task are set in the ``task_make_sfc_climo:`` section of the ``config.yaml`` file. + +``KMP_AFFINITY_MAKE_SFC_CLIMO``: (Default: "scatter") + Intel Thread Affinity Interface for the ``make_sfc_climo`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_MAKE_SFC_CLIMO``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_MAKE_SFC_CLIMO``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +``SFC_CLIMO_DIR``: (Default: "") + The directory containing pre-generated surface climatology files to use when the ``MAKE_SFC_CLIMO`` task is not meant to run. + +.. _task_get_extrn_ics: + +GET_EXTRN_ICS Configuration Parameters +========================================= + +Non-default parameters for the ``get_extrn_ics`` task are set in the ``task_get_extrn_ics:`` section of the ``config.yaml`` file. + +.. _basic-get-extrn-ics: + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``EXTRN_MDL_NAME_ICS``: (Default: "FV3GFS") + The name of the external model that will provide fields from which initial condition (IC) files, surface files, and 0-th hour boundary condition files will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` + +``EXTRN_MDL_ICS_OFFSET_HRS``: (Default: 0) + Users may wish to start a forecast using forecast data from a previous cycle of an external model. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should start from a 6-hour forecast of the GFS, then ``EXTRN_MDL_ICS_OFFSET_HRS: "6"``. + +``FV3GFS_FILE_FMT_ICS``: (Default: "nemsio") + If using the FV3GFS model as the source of the :term:`ICs` (i.e., if ``EXTRN_MDL_NAME_ICS: "FV3GFS"``), this variable specifies the format of the model files to use when generating the ICs. Valid values: ``"nemsio"`` | ``"grib2"`` | ``"netcdf"`` + +File and Directory Parameters +-------------------------------- + +``USE_USER_STAGED_EXTRN_FILES``: (Default: false) + Flag that determines whether the workflow will look for the external model files needed for generating :term:`ICs` in user-specified directories (rather than fetching them from mass storage like NOAA :term:`HPSS`). Valid values: ``True`` | ``False`` + +``EXTRN_MDL_SOURCE_BASEDIR_ICS``: (Default: "") + Directory containing external model files for generating ICs. If ``USE_USER_STAGED_EXTRN_FILES`` is set to true, the workflow looks within this directory for a subdirectory named "YYYYMMDDHH", which contains the external model files specified by the array ``EXTRN_MDL_FILES_ICS``. This "YYYYMMDDHH" subdirectory corresponds to the start date and cycle hour of the forecast (see :ref:`above `). These files will be used to generate the :term:`ICs` on the native FV3-LAM grid. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. + +``EXTRN_MDL_SYSBASEDIR_ICS``: (Default: '') + A known location of a real data stream on a given platform. This is typically a real-time data stream as on Hera, Jet, or WCOSS. External model files for generating :term:`ICs` on the native grid should be accessible via this data stream. The way the full path containing these files is constructed depends on the user-specified external model for ICs (defined above in :numref:`Section %s ` ``EXTRN_MDL_NAME_ICS``). + + .. note:: + This variable must be defined as a null string in ``config_defaults.yaml`` so that if it is specified by the user in the experiment configuration file (``config.yaml``), it remains set to those values, and if not, it gets set to machine-dependent values. + +``EXTRN_MDL_FILES_ICS``: (Default: "") + Array containing templates of the file names to search for in the ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` directory. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. A single template should be used for each model file type that is used. Users may use any of the Python-style templates allowed in the ``ush/retrieve_data.py`` script. To see the full list of supported templates, run that script with the ``-h`` option. + + For example, to set FV3GFS nemsio input files: + + .. code-block:: console + + EXTRN_MDL_FILES_ICS=[ gfs.t{hh}z.atmf{fcst_hr:03d}.nemsio , + gfs.t{hh}z.sfcf{fcst_hr:03d}.nemsio ] + + To set FV3GFS grib files: + + .. code-block:: console + + EXTRN_MDL_FILES_ICS=[ gfs.t{hh}z.pgrb2.0p25.f{fcst_hr:03d} ] + +``EXTRN_MDL_DATA_STORES``: (Default: "") + A list of data stores where the scripts should look to find external model data. The list is in priority order. If disk information is provided via ``USE_USER_STAGED_EXTRN_FILES`` or a known location on the platform, the disk location will receive highest priority. Valid values: ``disk`` | ``hpss`` | ``aws`` | ``nomads`` + +NOMADS Parameters +--------------------- + +Set parameters associated with NOMADS online data. + +``NOMADS``: (Default: false) + Flag controlling whether to use NOMADS online data. Valid values: ``True`` | ``False`` + +``NOMADS_file_type``: (Default: "nemsio") + Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"`` + +.. _task_get_extrn_lbcs: + +GET_EXTRN_LBCS Configuration Parameters +========================================== + +Non-default parameters for the ``get_extrn_lbcs`` task are set in the ``task_get_extrn_lbcs:`` section of the ``config.yaml`` file. + +.. _basic-get-extrn-lbcs: + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``EXTRN_MDL_NAME_LBCS``: (Default: "FV3GFS") + The name of the external model that will provide fields from which lateral boundary condition (LBC) files (except for the 0-th hour LBC file) will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` + +``LBC_SPEC_INTVL_HRS``: (Default: "6") + The interval (in integer hours) at which LBC files will be generated. This is also referred to as the *boundary update interval*. Note that the model selected in ``EXTRN_MDL_NAME_LBCS`` must have data available at a frequency greater than or equal to that implied by ``LBC_SPEC_INTVL_HRS``. For example, if ``LBC_SPEC_INTVL_HRS`` is set to "6", then the model must have data available at least every 6 hours. It is up to the user to ensure that this is the case. + +``EXTRN_MDL_LBCS_OFFSET_HRS``: (Default: "") + Users may wish to use lateral boundary conditions from a forecast that was started earlier than the start of the forecast configured here. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should use lateral boundary conditions from the GFS started 6 hours earlier, then ``EXTRN_MDL_LBCS_OFFSET_HRS: "6"``. Note: the default value is model-dependent and is set in ``ush/set_extrn_mdl_params.py``. + +``FV3GFS_FILE_FMT_LBCS``: (Default: "nemsio") + If using the FV3GFS model as the source of the :term:`LBCs` (i.e., if ``EXTRN_MDL_NAME_LBCS: "FV3GFS"``), this variable specifies the format of the model files to use when generating the LBCs. Valid values: ``"nemsio"`` | ``"grib2"`` | ``"netcdf"`` + + +File and Directory Parameters +-------------------------------- + +``USE_USER_STAGED_EXTRN_FILES``: (Default: false) + Analogous to ``USE_USER_STAGED_EXTRN_FILES`` in :term:`ICs` but for :term:`LBCs`. Flag that determines whether the workflow will look for the external model files needed for generating :term:`LBCs` in user-specified directories (rather than fetching them from mass storage like NOAA :term:`HPSS`). Valid values: ``True`` | ``False`` + +``EXTRN_MDL_SOURCE_BASEDIR_LBCS``: (Default: "") + Analogous to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` but for :term:`LBCs` instead of :term:`ICs`. + Directory containing external model files for generating LBCs. If ``USE_USER_STAGED_EXTRN_FILES`` is set to true, the workflow looks within this directory for a subdirectory named "YYYYMMDDHH", which contains the external model files specified by the array ``EXTRN_MDL_FILES_LBCS``. This "YYYYMMDDHH" subdirectory corresponds to the start date and cycle hour of the forecast (see :ref:`above `). These files will be used to generate the :term:`LBCs` on the native FV3-LAM grid. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. + +``EXTRN_MDL_SYSBASEDIR_LBCS``: (Default: '') + Same as ``EXTRN_MDL_SYSBASEDIR_ICS`` but for :term:`LBCs`. A known location of a real data stream on a given platform. This is typically a real-time data stream as on Hera, Jet, or WCOSS. External model files for generating :term:`LBCs` on the native grid should be accessible via this data stream. The way the full path containing these files is constructed depends on the user-specified external model for LBCs (defined above in :numref:`Section %s ` ``EXTRN_MDL_NAME_LBCS`` above). + + .. note:: + This variable must be defined as a null string in ``config_defaults.yaml`` so that if it is specified by the user in the experiment configuration file (``config.yaml``), it remains set to those values, and if not, it gets set to machine-dependent values. + +``EXTRN_MDL_FILES_LBCS``: (Default: "") + Analogous to ``EXTRN_MDL_FILES_ICS`` but for :term:`LBCs` instead of :term:`ICs`. Array containing templates of the file names to search for in the ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` directory. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. A single template should be used for each model file type that is used. Users may use any of the Python-style templates allowed in the ``ush/retrieve_data.py`` script. To see the full list of supported templates, run that script with the ``-h`` option. For examples, see the ``EXTRN_MDL_FILES_ICS`` variable above. + +``EXTRN_MDL_DATA_STORES``: (Default: "") + Analogous to ``EXTRN_MDL_DATA_STORES`` in :term:`ICs` but for :term:`LBCs`. A list of data stores where the scripts should look to find external model data. The list is in priority order. If disk information is provided via ``USE_USER_STAGED_EXTRN_FILES`` or a known location on the platform, the disk location will receive highest priority. Valid values: ``disk`` | ``hpss`` | ``aws`` | ``nomads`` + +NOMADS Parameters +--------------------- + +Set parameters associated with NOMADS online data. Analogus to :term:`ICs` NOMADS Parameters. + +``NOMADS``: (Default: false) + Flag controlling whether to use NOMADS online data. + +``NOMADS_file_type``: (Default: "nemsio") + Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"`` + +MAKE_ICS Configuration Parameters +====================================== + +Non-default parameters for the ``make_ics`` task are set in the ``task_make_ics:`` section of the ``config.yaml`` file. + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``KMP_AFFINITY_MAKE_ICS``: (Default: "scatter") + Intel Thread Affinity Interface for the ``make_ics`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_MAKE_ICS``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_MAKE_ICS``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +FVCOM Parameter +------------------- +``USE_FVCOM``: (Default: false) + Flag that specifies whether to update surface conditions in FV3-:term:`LAM` with fields generated from the Finite Volume Community Ocean Model (:term:`FVCOM`). If set to true, lake/sea surface temperatures, ice surface temperatures, and ice placement will be overwritten using data provided by FVCOM. Setting ``USE_FVCOM`` to true causes the executable ``process_FVCOM.exe`` in the ``MAKE_ICS`` task to run. This, in turn, modifies the file ``sfc_data.nc`` generated by ``chgres_cube`` during the ``make_ics`` task. Note that the FVCOM data must already be interpolated to the desired FV3-LAM grid. Valid values: ``True`` | ``False`` + +``FVCOM_WCSTART``: (Default: "cold") + Define if this is a "warm" start or a "cold" start. Setting this to "warm" will read in ``sfc_data.nc`` generated in a RESTART directory. Setting this to "cold" will read in the ``sfc_data.nc`` generated from ``chgres_cube`` in the ``make_ics`` portion of the workflow. Valid values: ``"cold"`` | ``"COLD"`` | ``"warm"`` | ``"WARM"`` + +``FVCOM_DIR``: (Default: "") + User-defined directory where the ``fvcom.nc`` file containing :term:`FVCOM` data already interpolated to the FV3-LAM native grid is located. The file in this directory must be named ``fvcom.nc``. + +``FVCOM_FILE``: (Default: "fvcom.nc") + Name of the file located in ``FVCOM_DIR`` that has :term:`FVCOM` data interpolated to the FV3-LAM grid. This file will be copied later to a new location, and the name will be changed to ``fvcom.nc`` if a name other than ``fvcom.nc`` is selected. + + +MAKE_LBCS Configuration Parameters +====================================== + +Non-default parameters for the ``make_lbcs`` task are set in the ``task_make_lbcs:`` section of the ``config.yaml`` file. + +``KMP_AFFINITY_MAKE_LBCS``: (Default: "scatter") + Intel Thread Affinity Interface for the ``make_lbcs`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_MAKE_LBCS``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_MAKE_LBCS``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +.. _FcstConfigParams: + +FORECAST Configuration Parameters +===================================== + +Non-default parameters for the ``run_fcst`` task are set in the ``task_run_fcst:`` section of the ``config.yaml`` file. + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``KMP_AFFINITY_RUN_FCST``: (Default: "scatter") + Intel Thread Affinity Interface for the ``run_fcst`` task. + +.. _thread-affinity: + + .. note:: + + **Thread Affinity Interface** + + "Intel's runtime library can bind OpenMP threads to physical processing units. The interface is controlled using the ``KMP_AFFINITY`` environment variable. Thread affinity restricts execution of certain threads to a subset of the physical processing units in a multiprocessor computer. Depending on the system (machine) topology, application, and operating system, thread affinity can have a dramatic effect on the application speed and on the execution speed of a program." Valid values: ``"scatter"`` | ``"disabled"`` | ``"balanced"`` | ``"compact"`` | ``"explicit"`` | ``"none"`` + + For more information, see the `Intel Development Reference Guide `__. + +``OMP_NUM_THREADS_RUN_FCST``: (Default: 2) + The number of OpenMP threads to use for parallel regions. Corresponds to the ``atmos_nthreads`` value in ``model_configure``. + +``OMP_STACKSIZE_RUN_FCST``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +.. _ModelConfigParams: + +Model Configuration Parameters +---------------------------------- + +These parameters set values in the Weather Model's ``model_configure`` file. + +``DT_ATMOS``: (Default: "") + Time step for the outermost atmospheric model loop in seconds. This corresponds to the frequency at which the physics routines and the top level dynamics routine are called. (Note that one call to the top-level dynamics routine results in multiple calls to the horizontal dynamics, :term:`tracer` transport, and vertical dynamics routines; see the `FV3 dycore scientific documentation `__ for details.) Must be set. Takes an integer value. In the SRW App, a default value for ``DT_ATMOS`` appears in the ``set_predef_grid_params.yaml`` script, but a different value can be set in ``config.yaml``. In general, the smaller the grid cell size is, the smaller this value needs to be in order to avoid numerical instabilities during the forecast. + +``RESTART_INTERVAL``: (Default: 0) + Frequency of the output restart files in hours. Using the default interval (0), restart files are produced at the end of a forecast run. When ``RESTART_INTERVAL: 1``, restart files are produced every hour with the prefix "YYYYMMDD.HHmmSS." in the ``RESTART`` directory. + +.. _InlinePost: + +``WRITE_DOPOST``: (Default: false) + Flag that determines whether to use the inline post option. The default ``WRITE_DOPOST: false`` does not use the inline post functionality, and the ``run_post`` tasks are called from outside of the Weather Model. If ``WRITE_DOPOST: true``, the ``WRITE_DOPOST`` flag in the ``model_configure`` file will be set to true, and the post-processing (:term:`UPP`) tasks will be called from within the Weather Model. This means that the post-processed files (in :term:`grib2` format) are output by the Weather Model at the same time that it outputs the ``dynf###.nc`` and ``phyf###.nc`` files. Setting ``WRITE_DOPOST: true`` turns off the separate ``run_post`` task in ``setup.py`` to avoid unnecessary computations. Valid values: ``True`` | ``False`` + +Computational Parameters +---------------------------- + +``LAYOUT_X, LAYOUT_Y``: (Default: "") + The number of :term:`MPI` tasks (processes) to use in the two horizontal directions (x and y) of the regional grid when running the forecast model. + +``BLOCKSIZE``: (Default: "") + The amount of data that is passed into the cache at a time. + +.. note:: + + In ``config_defaults.yaml`` the computational parameters are set to null strings so that: + + #. If the experiment is using a predefined grid and the user sets the parameter in the user-specified experiment configuration file (i.e., ``config.yaml``), that value will be used in the forecast(s). Otherwise, the default value for that predefined grid will be used. + #. If the experiment is *not* using a predefined grid (i.e., it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the parameter in that configuration file. Otherwise, the parameter will remain set to a null string, and the experiment generation will fail because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory. + +.. _WriteComp: + +Write-Component (Quilting) Parameters +----------------------------------------- + +.. note:: + The :term:`UPP` (called by the ``RUN_POST`` 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 use an Earth System Modeling Framework (:term:`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``. + + 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`` (meta)task cannot run because the :term:`UPP` code called by this task cannot process fields on the native grid. In that case, the ``RUN_POST`` (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. Valid values: ``True`` | ``False`` + +``PRINT_ESMF``: (Default: false) + Flag that determines whether to output extra (debugging) information from :term:`ESMF` routines. 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). Valid values: ``True`` | ``False`` + +``WRTCMP_write_groups``: (Default: 1) + The number of write groups (i.e., groups of :term:`MPI` tasks) to use in the write component. Each write group will write 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 ``WRTCMP_write_tasks_per_group`` tasks. Usually, one write group is sufficient. 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. + +``WRTCMP_write_tasks_per_group``: (Default: 20) + 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.yaml`` 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. + +``WRTCMP_cen_lat``: (Default: "") + 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 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 when running an experiment with a user-defined grid. + +**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "rotated_latlon":** + +``WRTCMP_lon_upr_rght``: (Default: "") + Longitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated longitude). + +``WRTCMP_lat_upr_rght``: (Default: "") + Latitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated latitude). + +``WRTCMP_dlon``: (Default: "") + Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated longitude). + +``WRTCMP_dlat``: (Default: "") + Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated latitude). + +**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "lambert_conformal":** + +``WRTCMP_stdlat1``: (Default: "") + First standard latitude (in degrees) in definition of Lambert conformal projection. + +``WRTCMP_stdlat2``: (Default: "") + Second standard latitude (in degrees) in definition of Lambert conformal projection. + +``WRTCMP_nx``: (Default: "") + Number of grid points in the x-coordinate of the Lambert conformal projection. + +``WRTCMP_ny``: (Default: "") + Number of grid points in the y-coordinate of the Lambert conformal projection. + +``WRTCMP_dx``: (Default: "") + Grid cell size (in meters) along the x-axis of the Lambert conformal projection. + +``WRTCMP_dy``: (Default: "") + Grid cell size (in meters) along the y-axis of the Lambert conformal projection. + +.. _PredefGrid: + +Predefined Grid Parameters +------------------------------ + +``PREDEF_GRID_NAME``: (Default: "") + This parameter indicates which (if any) predefined regional grid to use for the experiment. Setting ``PREDEF_GRID_NAME`` provides a convenient method of specifying a commonly used set of grid-dependent parameters. The predefined grid settings can be viewed in the script ``ush/set_predef_grid_params.yaml``. + + **Currently supported options:** + + | ``"RRFS_CONUS_25km"`` + | ``"RRFS_CONUS_13km"`` + | ``"RRFS_CONUS_3km"`` + | ``"SUBCONUS_Ind_3km"`` + + **Other valid values include:** + + | ``"CONUS_25km_GFDLgrid"`` + | ``"CONUS_3km_GFDLgrid"`` + | ``"EMC_AK"`` + | ``"EMC_HI"`` + | ``"EMC_PR"`` + | ``"EMC_GU"`` + | ``"GSL_HAFSV0.A_25km"`` + | ``"GSL_HAFSV0.A_13km"`` + | ``"GSL_HAFSV0.A_3km"`` + | ``"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:: + + * If ``PREDEF_GRID_NAME`` is set to a valid predefined grid name, the grid generation 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.yaml``). 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. + + * If ``PREDEF_GRID_NAME`` is set to an empty string, it implies that the user will provide the native grid parameters in the user-specified experiment configuration file (``config.yaml``). In this case, the grid generation method, the native grid parameters, the write component grid parameters, the main time step (``DT_ATMOS``), and the computational parameters (``LAYOUT_X``, ``LAYOUT_Y``, and ``BLOCKSIZE``) must be set in the configuration file. Otherwise, the values of the parameters in the default experiment configuration file (``config_defaults.yaml``) will be used. + +Aerosol Climatology Parameter +--------------------------------- + +``USE_MERRA_CLIMO``: (Default: false) + Flag that determines whether :term:`MERRA2` aerosol climatology data and lookup tables for optics properties are obtained. Valid values: ``True`` | ``False`` + + .. COMMENT: When would it be appropriate to obtain these files? + +Fixed File Parameters +------------------------- + +These parameters are associated with the fixed (i.e., static) files. On `Level 1 & 2 `__ systems, fixed files are pre-staged with paths defined in the ``setup.py`` script. Because the default values are platform-dependent, they are set to a null string in ``config_defaults.yaml``. Then these null values are overwritten in ``setup.py`` with machine-specific values or with a user-specified value from ``config.yaml``. + +``FIXgsm``: (Default: "") + System directory in which the majority of fixed (i.e., time-independent) files that are needed to run the FV3-LAM model are located. + +``FIXaer``: (Default: "") + System directory where :term:`MERRA2` aerosol climatology files are located. + +``FIXlut``: (Default: "") + System directory where the lookup tables for optics properties are located. + +``FIXshp``: (Default: "") + System directory where the graphics shapefiles are located. On Level 1 systems, these are set within the machine files. Users on other systems will need to provide the path to the directory that contains the *Natural Earth* shapefiles. + +``TOPO_DIR``: (Default: "") + The location on disk of the static input files used by the ``make_orog`` task (i.e., ``orog.x`` and ``shave.x``). Can be the same as ``FIXgsm``. + +``SFC_CLIMO_INPUT_DIR``: (Default: "") + The location on disk of the static surface climatology input fields, used by ``sfc_climo_gen``. These files are only used if the ``MAKE_SFC_CLIMO`` task is meant to run. + +``SYMLINK_FIX_FILES``: (Default: true) + Flag that indicates whether to symlink or copy fix files to the experiment directory. + +RUN_POST Configuration Parameters +===================================== + +Non-default parameters for the ``run_post`` task are set in the ``task_run_post:`` section of the ``config.yaml`` file. + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``KMP_AFFINITY_RUN_POST``: (Default: "scatter") + Intel Thread Affinity Interface for the ``run_post`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_RUN_POST``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_RUN_POST``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + + +Subhourly Post Parameters +----------------------------- +Set parameters associated with subhourly forecast model output and post-processing. + +``SUB_HOURLY_POST``: (Default: false) + 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 valid value between 1 and 59. Valid values: ``True`` | ``False`` + +``DT_SUB_HOURLY_POST_MNTS``: (Default: 0) + Time interval in minutes between the forecast model output files (only used if ``SUB_HOURLY_POST`` is set to true). If ``SUB_HOURLY_POST`` is set to true, this needs to be set to a valid two-digit integer between 1 and 59. Note that if ``SUB_HOURLY_POST`` is set to true but ``DT_SUB_HOURLY_POST_MNTS`` is set to 0, ``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: ``0`` | ``1`` | ``2`` | ``3`` | ``4`` | ``5`` | ``6`` | ``10`` | ``12`` | ``15`` | ``20`` | ``30`` + +Customized Post Configuration Parameters +-------------------------------------------- + +Set parameters for customizing the :term:`UPP`. + +``USE_CUSTOM_POST_CONFIG_FILE``: (Default: false) + Flag that determines whether a user-provided custom configuration file should be used for post-processing the model data. If this is set to true, then the workflow will use the custom post-processing (:term:`UPP`) configuration file specified in ``CUSTOM_POST_CONFIG_FP``. Otherwise, a default configuration file provided in the UPP repository will be used. Valid values: ``True`` | ``False`` + +``CUSTOM_POST_CONFIG_FP``: (Default: "") + The full path to the custom post flat file, including filename, to be used for post-processing. This is only used if ``CUSTOM_POST_CONFIG_FILE`` is set to true. + +``POST_OUTPUT_DOMAIN_NAME``: (Default: "") + Domain name (in lowercase) used to construct the names of the output files generated by the :term:`UPP`. If using a predefined grid, ``POST_OUTPUT_DOMAIN_NAME`` defaults to ``PREDEF_GRID_NAME``. If using a custom grid, ``POST_OUTPUT_DOMAIN_NAME`` must be specified by the user. The post output files are named as follows: + + .. code-block:: console + + $NET.tHHz.[var_name].f###.${POST_OUTPUT_DOMAIN_NAME}.grib2 + + Note that this variable is first changed to lower case before being used to construct the file names. + +RUN_PRDGEN Configuration Parameters +===================================== + +Non-default parameters for the ``run_prdgen`` task are set in the ``task_run_prdgen:`` section of the ``config.yaml`` file. + +Basic Task Parameters +--------------------------------- +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``KMP_AFFINITY_RUN_PRDGEN``: (Default: "scatter") + Intel Thread Affinity Interface for the ``run_prdgen`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_RUN_PRDGEN``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_RUN_PRDGEN``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +``DO_PARALLEL_PRDGEN``: (Default: false) + Flag that determines whether to use CFP to run the product generation job in parallel. CFP is a utility that allows the user to launch a number of small jobs across nodes/cpus in one batch command. This option should be used with the ``RRFS_NA_3km`` grid and ``PPN_RUN_PRDGEN`` should be set to 22. + +``ADDNL_OUTPUT_GRIDS``: (Default: []) + Set additional output grids for wgrib2 remapping, if any. Space-separated list of strings, e.g., ( "130" "242" "clue"). Default is no additional grids. + +``TESTBED_FIELDS_FN``: (Default: "") + The file which lists grib2 fields to be extracted for testbed files. Empty string means no need to generate testbed files. + +.. _PlotVars: + +PLOT_ALLVARS Configuration Parameters +======================================== + +Typically, the following parameters must be set explicitly by the user in the configuration file (``config.yaml``) when executing the plotting tasks. + +``COMOUT_REF``: (Default: "") + The directory where the GRIB2 files from post-processing are located. In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will correspond to the location in the experiment directory where the post-processed output can be found (e.g., ``$EXPTDIR/$DATE_FIRST_CYCL/postprd``). In *nco* mode, this directory should be set to the location of the ``COMOUT`` directory and end with ``$PDY/$cyc``. For more detail on *nco* standards and directory naming conventions, see `WCOSS Implementation Standards `__ (particularly pp. 4-5). + +``PLOT_FCST_START``: (Default: 0) + The starting forecast hour for the plotting task. For example, if a forecast starts at 18h/18z, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. If a forecast starts at 18h/18z, but the user only wants plots from the 6th forecast hour on, "starting forecast hour" should be 6. + +``PLOT_FCST_INC``: (Default: 3) + Forecast hour increment for the plotting task. For example, if the user wants plots for each forecast hour, they should set ``PLOT_FCST_INC: 1``. If the user only wants plots for some of the output (e.g., every 6 hours), they should set ``PLOT_FCST_INC: 6``. + +``PLOT_FCST_END``: (Default: "") + The last forecast hour for the plotting task. For example, if a forecast run for 24 hours, and the user wants plots for each available hour of forecast output, they should set ``PLOT_FCST_END: 24``. If the user only wants plots from the first 12 hours of the forecast, the "last forecast hour" should be 12. + +``PLOT_DOMAINS``: (Default: ["conus"]) + Domains to plot. Currently supported options are ["conus"], ["regional"], or both (i.e., ["conus", "regional"]). + +Global Configuration Parameters +=================================== + +Non-default parameters for the miscellaneous tasks are set in the ``global:`` section of the ``config.yaml`` file. + +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`). :numref:`Section %s ` includes further instructions on how to do this. + +``USE_CRTM``: (Default: false) + Flag that defines whether external :term:`CRTM` coefficient files have been staged by the user in order to output synthetic satellite products available within the :term:`UPP`. If this is set to true, then the workflow will check for these files in the directory ``CRTM_DIR``. Otherwise, it is assumed that no satellite fields are being requested in the UPP configuration. Valid values: ``True`` | ``False`` + +``CRTM_DIR``: (Default: "") + This is the path to the top CRTM fix file directory. This is only used if ``USE_CRTM`` is set to true. + + +Ensemble Model Parameters +----------------------------- + +Set parameters associated with running ensembles. + +``DO_ENSEMBLE``: (Default: false) + Flag that determines whether to run a set of ensemble forecasts (for each set of specified cycles). If this is set to true, ``NUM_ENS_MEMBERS`` forecasts are run for each cycle, each with a different set of stochastic seed values. When false, a single forecast is run for each cycle. Valid values: ``True`` | ``False`` + +``NUM_ENS_MEMBERS``: (Default: 1) + The number of ensemble members to run if ``DO_ENSEMBLE`` is set to true. This variable also controls the naming of the ensemble member directories. For example, if ``NUM_ENS_MEMBERS`` is set to 8, the member directories will be named *mem1, mem2, ..., mem8*. This variable is not used unless ``DO_ENSEMBLE`` is set to true. + +.. _stochastic-physics: + +Stochastic Physics Parameters +---------------------------------- + +Set default ad-hoc stochastic physics options. For the most updated and detailed documentation of these parameters, see the `UFS Stochastic Physics Documentation `__. + +``NEW_LSCALE``: (Default: true) + Use correct formula for converting a spatial legnth scale into spectral space. + +Specific Humidity (SHUM) Perturbation Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``DO_SHUM``: (Default: false) + Flag to turn Specific Humidity (SHUM) perturbations on or off. SHUM perturbations multiply the low-level specific humidity by a small random number at each time-step. The SHUM scheme attempts to address missing physics phenomena (e.g., cold pools, gust fronts) most active in convective regions. Valid values: ``True`` | ``False`` + +``ISEED_SHUM``: (Default: 2) + Seed for setting the SHUM random number sequence. + +``SHUM_MAG``: (Default: 0.006) + Amplitudes of random patterns. Corresponds to the variable ``shum`` in ``input.nml``. + +``SHUM_LSCALE``: (Default: 150000) + Decorrelation spatial scale in meters. + +``SHUM_TSCALE``: (Default: 21600) + Decorrelation timescale in seconds. Corresponds to the variable ``shum_tau`` in ``input.nml``. + +``SHUM_INT``: (Default: 3600) + Interval in seconds to update random pattern (optional). Perturbations still get applied at every time-step. Corresponds to the variable ``shumint`` in ``input.nml``. + +.. _SPPT: + +Stochastically Perturbed Physics Tendencies (SPPT) Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SPPT perturbs full physics tendencies *after* the call to the physics suite, unlike :ref:`SPP ` (below), which perturbs specific tuning parameters within a physics scheme. + +``DO_SPPT``: (Default: false) + Flag to turn Stochastically Perturbed Physics Tendencies (SPPT) on or off. SPPT multiplies the physics tendencies by a random number between 0 and 2 before updating the model state. This addresses error in the physics parameterizations (either missing physics or unresolved subgrid processes). It is most active in the boundary layer and convective regions. Valid values: ``True`` | ``False`` + +``ISEED_SPPT``: (Default: 1) + Seed for setting the SPPT random number sequence. + +``SPPT_MAG``: (Default: 0.7) + Amplitude of random patterns. Corresponds to the variable ``sppt`` in ``input.nml``. + +``SPPT_LOGIT``: (Default: true) + Limits the SPPT perturbations to between 0 and 2. Should be "TRUE"; otherwise the model will crash. + +``SPPT_LSCALE``: (Default: 150000) + Decorrelation spatial scale in meters. + +``SPPT_TSCALE``: (Default: 21600) + Decorrelation timescale in seconds. Corresponds to the variable ``sppt_tau`` in ``input.nml``. + +``SPPT_INT``: (Default: 3600) + Interval in seconds to update random pattern (optional parameter). Perturbations still get applied at every time-step. Corresponds to the variable ``spptint`` in ``input.nml``. + +``SPPT_SFCLIMIT``: (Default: true) + When true, tapers the SPPT perturbations to zero at the model's lowest level, which reduces model crashes. + +``USE_ZMTNBLCK``: (Default: false) + When true, do not apply perturbations below the dividing streamline that is diagnosed by the gravity wave drag, mountain blocking scheme. Valid values: ``True`` | ``False`` + + +Stochastic Kinetic Energy Backscatter (SKEB) Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``DO_SKEB``: (Default: false) + Flag to turn Stochastic Kinetic Energy Backscatter (SKEB) on or off. SKEB adds wind perturbations to the model state. Perturbations are random in space/time, but amplitude is determined by a smoothed dissipation estimate provided by the :term:`dynamical core`. SKEB addresses errors in the dynamics more active in the mid-latitudes. Valid values: ``True`` | ``False`` + +``ISEED_SKEB``: (Default: 3) + Seed for setting the SHUM random number sequence. + +``SKEB_MAG``: (Default: 0.5) + Amplitude of random patterns. Corresponds to the variable ``skeb`` in ``input.nml``. + +``SKEB_LSCALE``: (Default: 150000) + Decorrelation spatial scale in meters. + +``SKEB_TSCALE``: (Default: 21600) + Decorrelation timescale in seconds. Corresponds to the variable ``skeb_tau`` in ``input.nml``. + +``SKEB_INT``: (Default: 3600) + Interval in seconds to update random pattern (optional). Perturbations still get applied every time-step. Corresponds to the variable ``skebint`` in ``input.nml``. + +``SKEBNORM``: (Default: 1) + Patterns: + * 0-random pattern is stream function + * 1-pattern is K.E. norm + * 2-pattern is vorticity + +``SKEB_VDOF``: (Default: 10) + The number of degrees of freedom in the vertical direction for the SKEB random pattern. + + +.. _SPP: + +Parameters for Stochastically Perturbed Parameterizations (SPP) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SPP perturbs specific tuning parameters within a physics :term:`parameterization ` (unlike :ref:`SPPT `, which multiplies overall physics tendencies by a random perturbation field *after* the call to the physics suite). Patterns evolve and are applied at each time step. Each SPP option is an array, applicable (in order) to the :term:`RAP`/:term:`HRRR`-based parameterization listed in ``SPP_VAR_LIST``. Enter each value of the array in ``config.yaml`` as shown below without commas or single quotes (e.g., ``SPP_VAR_LIST: [ "pbl" "sfc" "mp" "rad" "gwd" ]`` ). Both commas and single quotes will be added by Jinja when creating the namelist. + +.. note:: + SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which :term:`SDF` is chosen when turning this option on. Of the four supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. + +``DO_SPP``: (Default: false) + Flag to turn SPP on or off. SPP perturbs parameters or variables with unknown or uncertain magnitudes within the physics code based on ranges provided by physics experts. Valid values: ``True`` | ``False`` + +``ISEED_SPP``: (Default: [ 4, 5, 6, 7, 8 ] ) + Seed for setting the random number sequence for the perturbation pattern. + +``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"`` | ``"mp"`` + +``SPP_MAG_LIST``: (Default: [ 0.2, 0.2, 0.75, 0.2, 0.2 ] ) + SPP perturbation magnitudes used in each parameterization. Corresponds to the variable ``spp_prt_list`` in ``input.nml`` + +``SPP_LSCALE``: (Default: [ 150000.0, 150000.0, 150000.0, 150000.0, 150000.0 ] ) + Decorrelation spatial scales in meters. + +``SPP_TSCALE``: (Default: [ 21600.0, 21600.0, 21600.0, 21600.0, 21600.0 ] ) + Decorrelation timescales in seconds. Corresponds to the variable ``spp_tau`` in ``input.nml``. + +``SPP_SIGTOP1``: (Default: [ 0.1, 0.1, 0.1, 0.1, 0.1 ] ) + Controls vertical tapering of perturbations at the tropopause and corresponds to the lower sigma level at which to taper perturbations to zero. + +``SPP_SIGTOP2``: (Default: [ 0.025, 0.025, 0.025, 0.025, 0.025 ] ) + Controls vertical tapering of perturbations at the tropopause and corresponds to the upper sigma level at which to taper perturbations to zero. + +``SPP_STDDEV_CUTOFF``: (Default: [ 1.5, 1.5, 2.5, 1.5, 1.5 ] ) + Limit for possible perturbation values in standard deviations from the mean. + + +Land Surface Model (LSM) SPP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Land surface perturbations can be applied to land model parameters and land model prognostic variables. The LSM scheme is intended to address errors in the land model and land-atmosphere interactions. LSM perturbations include soil moisture content (SMC) (volume fraction), vegetation fraction (VGF), albedo (ALB), salinity (SAL), emissivity (EMI), surface roughness (ZOL) (in cm), and soil temperature (STC). Perturbations to soil moisture content (SMC) are only applied at the first time step. Only five perturbations at a time can be applied currently, but all seven are shown below. In addition, only one unique *iseed* value is allowed at the moment, and it is used for each pattern. + +The parameters below turn on SPP in Noah or RUC LSM (support for Noah MP is in progress). Please be aware of the :term:`SDF` that you choose if you wish to turn on Land Surface Model (LSM) SPP. SPP in LSM schemes is handled in the ``&nam_sfcperts`` namelist block instead of in ``&nam_sppperts``, where all other SPP is implemented. + +``DO_LSM_SPP``: (Default: false) + Turns on Land Surface Model (LSM) Stochastic Physics Parameterizations (SPP). When true, sets ``lndp_type=2``, which applies land perturbations to the selected paramaters using a newer scheme designed for data assimilation (DA) ensemble spread. LSM SPP perturbs uncertain land surface fields ("smc" "vgf" "alb" "sal" "emi" "zol" "stc") based on recommendations from physics experts. Valid values: ``True`` | ``False`` + +``LSM_SPP_TSCALE``: (Default: [ 21600, 21600, 21600, 21600, 21600, 21600, 21600 ] ) + Decorrelation timescales in seconds. + +``LSM_SPP_LSCALE``: (Default: [ 150000, 150000, 150000, 150000, 150000, 150000, 150000 ] ) + Decorrelation spatial scales in meters. + +``ISEED_LSM_SPP``: (Default: [ 9 ] ) + Seed to initialize the random perturbation pattern. + +``LSM_SPP_VAR_LIST``: (Default: [ "smc", "vgf", "alb", "sal", "emi", "zol", "stc" ] ) + Indicates which LSM variables to perturb. + +``LSM_SPP_MAG_LIST``: (Default: [ 0.017, 0.001, 0.001, 0.001, 0.001, 0.001, 0.2 ] ) + Sets the maximum random pattern amplitude for each of the LSM perturbations. + +.. _HaloBlend: + +Halo Blend Parameter +------------------------ +``HALO_BLEND``: (Default: 10) + Number of cells to use for "blending" the external solution (obtained from the :term:`LBCs`) with the internal solution from the FV3LAM :term:`dycore`. Specifically, it refers to the number of rows into the computational domain that should be blended with the LBCs. Cells at which blending occurs are all within the boundary of the native grid; they don't involve the 4 cells outside the boundary where the LBCs are specified (which is a different :term:`halo`). Blending is necessary to smooth out waves generated due to mismatch between the external and internal solutions. To shut :term:`halo` blending off, set this to zero. + diff --git a/docs/UsersGuide/source/TechnicalDetails/DefineWorkflow.rst b/docs/UsersGuide/source/TechnicalDetails/DefineWorkflow.rst new file mode 100644 index 0000000000..470d04ea95 --- /dev/null +++ b/docs/UsersGuide/source/TechnicalDetails/DefineWorkflow.rst @@ -0,0 +1,242 @@ +.. _DefineWorkflow: + +============================= +Defining an SRW App Workflow +============================= + + +Rocoto is the primary workflow manager software used by the UFS SRW App. Because the SRW App supports a variety of research and operational configurations, it is important to incorporate the ability to build a static Rocoto XML from scratch. This means a user will be able to specify exactly which tasks are included in the workflow definition from a YAML configuration file. While many predefined workflows will exist with optional variants in the SRW App, additional tasks may be added by individuals for their scientific exploration needs. + +This guide explains how the Rocoto XML is built using a Jinja2 template (`Jinja docs here `__) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation `__ with a few exceptions or additions outlined in this documentation. + +The Jinja2 Template +=================== + +In previous versions of the SRW App, the Jinja2 template to create the Rocoto XML was tightly coupled to specific configuration settings of the SRW App. It was built from a limited, pre-defined set of specific tasks, defining switches for those tasks to be included or not in the rendered XML. + +Now, the Jinja2 template is entirely agnostic to Short-Range Weather Application decisions and has been developed to wrap the features of Rocoto in an extensible, configurable format. + + +The ``rocoto`` section of ``config.py`` +======================================= +The structured YAML file that defines the Rocoto XML is meant to reflect the sections required by any Rocoto XML. That structure looks like this, with some example values filled in: + +.. code-block:: console + + rocoto: + attrs: + realtime: F + scheduler: slurm + cyclethrottle: 5 + corethrottle: + taskthrottle: + cycledefs: + groupname: + !startstopfreq ['2022102000', ‘2023102018’, ‘06:00:00’] + groupname2: + !startstopfreq ['2022102000', ‘2023102018’, ‘24:00:00’] + !startstopfreq ['2022102006', ‘2023102018’, ‘24:00:00’] + entities: + foo: 1 + bar: “/some/path” + log: "" + tasks: + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml"]|include }}' + task_*: + metatask_*: + +In addition to the structured YAML itself, the SRW App enables additional functionality in defining a YAML file. Often, PyYAML features are introduced and documented `here `__. In the above example, the ``!startstopfreq`` is an example of a PyYAML constructor. Supported constructors will be outlined :ref:`below `. There are also examples of using PyYAML anchors and aliases in the definition of groups of tasks in the SRW App. Please see `this documentation `__ for the behavior of PyYAML anchors and aliases. + +The use of Jinja2 templates inside the values of entries allows for the reference to other keys, mathematical operations, Jinja2 control structures, and the use of user-defined filters. Here, the ``include`` filter in the ``taskgroups`` entry is a user-defined filter. The supported filters are described in a section :ref:`below `. + +Under the Rocoto section, several subentries are required. They are described here using similar language as in the Rocoto documentation. + +``attrs``: Any of the attributes to the ``workflow`` tag in Rocoto. This is meant to contain a nested dictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. + +``cycledefs``: A dictionary with each key defining a group name for a ``cycledef`` tag, where the key’s value is a list of acceptable ``cycledef`` formatted strings. The PyYAML constructor ``!startstopfreq`` has been included here to help with the automated construction of a tag of that nature. The preferred option for the SRW App is to use the “start, stop, step” method. + +``entities``: A dictionary with each key defining the name of a Rocoto entity and its value. These variables are referenceable throughout the workflow with the ‘&foo;’ notation. + +``log``: The path to the log file. This corresponds to the ```` tag. + +``tasks``: This section is where the defined tasks and metatasks are created. This is the main portion of the workflow that will most commonly differ from experiment to experiment with different configurations. + +.. _tasks: + +The ``tasks`` Subsection +======================== + +``taskgroups``: This entry is not a standard Rocoto entry. It defines a set of files that will be included to build a workflow from predefined groups of tasks. The supported groups are included under ``parm/wflow`` for the SRW App, but the paths can point to any location on your local disk. The resulting order of the tasks will be in the same order as defined in this list. The syntax for the “include” is included as a Jinja2 filter. + +``task_*``: This is a section header to add a task. The task name will be whatever the section key has defined after the first underscore. For example, “task_run_fcst” will be named “run_fcst” in the resulting workflow. More information about defining a task is included :ref:`below `. + +``metatask_*``: This is a section header to add a metatask. The metatask name will be whatever the section key has defined after the first underscore. For example “metatask_run_ensemble” will be named “run_ensemble” in the resulting workflow. More information about defining a metatask is included :ref:`below `. + +.. _defining_tasks: + +Defining a Task +=============== +Each task supports any of the tags that are defined in the Rocoto documentation. Here’s an example of a task: + +.. code-block:: console + + task_make_grid: + account: '&ACCOUNT;' + command: '&LOAD_MODULES_RUN_TASK_FP; "make_grid" + attrs: + cycledefs: at_start + maxtries: '2' + envars: &default_envars + GLOBAL_VAR_DEFNS_FP: '&GLOBAL_VAR_DEFNS_FP;' + USHdir: '&USHdir;' + PDY: !cycstr "@Y@m@d" + cyc: !cycstr "@H" + subcyc: !cycstr "@M" + LOGDIR: !cycstr "&LOGDIR;" + nprocs: '{{ parent.nnodes * parent.ppn }}' + native: '{{ platform.SCHED_NATIVE_CMD }}' + nodes: '{{ nnodes }}:ppn={{ ppn }}' + nnodes: 1 + nodesize: "&NCORES_PER_NODE;" + ppn: 24 + partition: '{% if platform.get("PARTITION_DEFAULT") %}&PARTITION_DEFAULT;{% else %}None{% endif %}' + queue: '&QUEUE_DEFAULT;' + walltime: 00:20:00 + dependency: + + +The following sections are constructs of the interface, while all others are direct translations to tags available in Rocoto. Any tag that allows for attributes to the XML tag will take an ``attrs`` nested dictionary entry. + +``attrs``: Any of the attributes to the task tag in Rocoto. This is meant to be a subdictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. This might include any combination of the following: cycledefs, maxtries, throttle, or final. + +``envars``: A dictionary of keys that map to variable names that will be exported for the job. These will show up as the set of ```` tags in the XML. The value will be the value of the defined variable when it is exported. + + +If the ``command`` entry is not provided, the task won’t show up in the resulting workflow. + +Defining Dependencies +===================== + +The dependency entry will be an arbitrarily deep nested dictionary of key, value pairs. Each level represents entries that must come below it in priority. This is especially relevant for logic files. If an “and” tag must apply to multiple dependencies, those dependencies are all included as a nested dictionary of dependencies. + +Because we are representing these entries as a dictionary, which requires hashable keys (no repeats at the same level), some tags may need to be differentiated where XML may not differentiate at all. In these instances, it is best practice to name them something descriptive. For example, you might have multiple “or” dependencies at the same level that could be named “or_files_exist” and “or_task_ran”. This style can be adopted whether or not differentiation is needed. + +The text entry on some dependencies is for those dependency tags that need the information to come between two flags, as in a data dependency. + +Otherwise, all dependencies follow the same naming conventions as defined in Rocoto with ``attrs`` dictionaries included to define any of the tag attributes that may be accepted by Rocoto. + +Here is an example of a complex dependency that relies on logic, task dependencies, and data dependencies: + +.. code-block:: console + + dependency: + and: + or_get_obs: # Ensure get_obs task is complete if it's turned on + not: + taskvalid: + attrs: + task: get_obs_mrms + and: + taskvalid: + attrs: + task: get_obs_mrms + taskdep: + attrs: + task: get_obs_mrms + or_do_post: &post_files_exist + and_run_post: # If post was meant to run, wait on the whole post metatask + taskvalid: + attrs: + task: run_post_mem#mem#_f000 + metataskdep: + attrs: + metatask: run_ens_post + and_inline_post: # If inline post ran, wait on the forecast task to complete + not: + taskvalid: + attrs: + task: run_post_mem#mem#_f000 + taskdep: + attrs: + task: run_fcst_mem#mem# + +Notice the use of a PyYAML anchor under the ``or_do_post`` section. If other tasks need this same section of the dependency, it can be included like this to reduce the extensive replication: + +.. code-block:: console + + dependency: + or_do_post: + <<: *post_files_exist + datadep: + text: "&CCPA_OBS_DIR;" + +The use of ``#mem#`` here is a Rocoto construct that identifies this task as a part of a metatask that is looping over ensemble members (more on metatasks below). + +.. _defining_metatasks: + +Defining a Metatask +=================== + +A metatask groups together similar tasks and allows for the definition over entries defined by ``var`` tags. To define a metatask, the ``var`` entry with a nested dictionary of keys representing the names of the metatask variables and values indicating the list of values for each iteration is required. + +Multiple var entries may be included, but each entry must have the same number of items. + +The metatask section must include at least one entry defining another metatask or a task. + +Here’s an example of a metatask section (without the task definition): + +.. code-block:: console + + metatask_run_ensemble: + var: + mem: '{% if global.DO_ENSEMBLE %}{%- for m in range(1, global.NUM_ENS_MEMBERS+1) -%}{{ "%03d "%m }}{%- endfor -%} {% else %}{{ "000"|string }}{% endif %}' + task_make_ics_mem#mem#: + +This metatask will be named “run_ensemble” and will loop over all ensemble members or just the deterministic member (“000”) if no ensemble of forecasts is meant to run. + +The ``var`` section defines the metatask variables, here only “mem”. The name of the task represents that variable using ``#mem#`` to indicate that the resulting task name might be ``make_ics_mem000`` if only a deterministic forecast is configured to run. + +When the task or the metatask is referenced in a dependency later on, do not include the ``task_`` or ``metatask_`` portions of the name. The reference to ``#mem#`` can be included if the dependency is included in a metatask that defines the variable, e.g., ``make_ics_mem#mem#``. Otherwise, you can reference a task that includes the value of the metatask var, e.g., ``make_ics_mem000``. More on this distinction is included in the Rocoto documentation. + +.. _J2filters: + +SRW-Defined Jinja2 Filters Used by YAML Interface +================================================= + +``include()`` – given a list of files to other YAML files, load their contents as a nested dictionary under the entry. + +.. _YAMLconstructors: + +SRW-Defined PyYAML Constructors Used by YAML Interface +====================================================== + +``!cycstr`` - Returns a ```` element for use in Rocoto. It does not support the “offset” attribute. + +``!startstopfreq`` – Creates a Rocoto XML-formatted string given a start, stop, and freq value in a list. + +Order of Precedence +=================== +There is a specific order of precedence imposed when the SRW App loads configuration files. + +#. Load ``config_defaults.yaml`` file. +#. Load the user’s ``config.yaml`` file. +#. Load the workflow defaults YAML file. +#. At this point, all anchors and references will be resolved. +#. All PyYAML constructors will also be called for the data provided in that entry. +#. Call ``update_dict`` function to remove any null entries from default tasks using the PyYAML anchors. +#. Load all files from the ``taskgroups:`` entry from the user’s config or from the default if not overridden. This is achieved with a call to the ``extend_yaml()`` function. +#. Add the contents of the files to the ``task:`` section. +#. Update the existing workflow configuration with any user-specified entries (removing the ones that are null entries). +#. Add a ``jobname:`` entry to every task in the workflow definition section. + +#. Incorporate other default configuration settings from machine files, constants, etc. into the default config dictionary in memory. +#. Apply all user settings last to take highest precedence. +#. Call ``extend_yaml()`` to render templates that are available. + NOTE: This is the one that is likely to trip up any settings that ``setup.py`` will make. References to other defaults that get changed during the course of validation may be rendered here earlier than desired. + +At this point, validation and updates for many other configuration settings will be made for a variety of sections. Once complete, ``extend_yaml()`` is called repeatedly, stopping only when all possible Jinja2-templated values have been rendered. + +Just before the ``rocoto:`` section is written to its own file in the experiment directory, ``clean_rocoto_dict()`` is called on that section to remove invalid dictionaries, i.e., metatasks with no tasks, tasks with no associated commands, etc. + +The ``rocoto:`` section is not included in the ``var_defns.sh`` since that file is used primarily to store settings needed at run-time. + diff --git a/docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst b/docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst new file mode 100644 index 0000000000..391affd49c --- /dev/null +++ b/docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst @@ -0,0 +1,411 @@ +.. _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. 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 required files, see :numref:`Section %s `. + +.. _Input: + +Input Files +=========== +The SRW Application requires numerous input files to run: static datasets (fix files +containing climatological information, terrain, and land use data), initial and boundary +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 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. + +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 generates the regional workflow as described in :numref:`Section %s `, 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 `Technical Documentation `__ and `Scientific Documentation `__. + +UFS Weather Model +----------------- +The input files for the UFS Weather Model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix(ed) 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 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) +---------------------------- +Documentation for the UPP input files can be found in the `UPP User's Guide +`__. + +.. _WorkflowTemplates: + +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 SRW 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.yaml`` file are assigned. + +List of Template Files +^^^^^^^^^^^^^^^^^^^^^^^^ +The template files for the SRW Application are located in the ``parm`` directory +and are shown in :numref:`Table %s `. + +.. _TemplateFiles: + +.. 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 | + | | :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 | + | | :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 | + | | ``generate_FV3LAM_wflow.py``. | + +-----------------------------+--------------------------------------------------------------+ + | input.nml.FV3 | Namelist file for the Weather Model. | + +-----------------------------+--------------------------------------------------------------+ + | model_configure | Settings and configurations for the | + | | :term:`NUOPC`/:term:`ESMF` main component. | + +-----------------------------+--------------------------------------------------------------+ + | 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 :term:`ESG` | + | | grid. | + +-----------------------------+--------------------------------------------------------------+ + | README.xml_templating.md | Instructions for Rocoto XML templating with Jinja. | + +-----------------------------+--------------------------------------------------------------+ + +Additional information related to ``diag_table.[CCPP]``, ``field_table.[CCPP]``, ``input.nml.FV3``, ``model_configure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, while information on ``regional_grid.nml`` options can be found in the `UFS_UTILS Technical Documentation `__. + +Migratory Route of the Input Files in the Workflow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:numref:`Figure %s ` shows how the input files in the template directory (``ufs-srweather-app/parm``) 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 ``parm`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. + +.. _MigratoryRoute: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW_wflow_input_path.png + :alt: Flowchart showing how information from the physics suite travels from the configuration file to the setup file to the workflow generation script to the run forecast ex-script. As this information is fed from one file to the next, file paths and variables required for workflow execution are set. + + *Migratory Route of Input Files* + +.. _OutputFiles: + +Output Files +============== + +Output files from each workflow task are written to a subdirectory within the experiment directory (``$EXPTDIR/YYYYMMDDHH``), named based on the settings in ``config.yaml``. + +Initial and boundary condition files +------------------------------------ +The external model data used by ``chgres_cube`` (as part of the pre-processing utilities) are located +in the experiment directory under ``$EXPTDIR/YYYYMMDDHH/EXTRN_MDL_NAME/{for_ICS/for_LBCS}``. + +Pre-processing (UFS_UTILS) +-------------------------- +The files output by the other pre-processing utilities reside in the ``INPUT`` directory under the +experiment directory (``$EXPTDIR/YYYYMMDDHH/INPUT``) and consist of the following: + +* ``C403_grid.tile7.halo3.nc`` +* ``gfs_bndy.tile7.HHH.nc`` +* ``gfs_ctrl.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 User's Guide +`__. ``gfs_bndy.tile7.HHH.nc`` refers to a series of IC/LBC files where ``HHH`` is the 3-digit hour of the forecast. + +UFS Weather Model +------------------ +As stated in :numref:`Section %s `, the workflow can be run in "community" mode or "nco" mode, which determines the location and names of the output files. Weather Model output files can 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 as output for the SRW Application. + +.. note:: + 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`` + +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 +`__. + +Unified Post Processor (UPP) +---------------------------- +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 ``$EXPTDIR/YYYYMMDDHH/postprd`` and have the naming convention (file->linked to): + +* ``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.yaml`` settings. + +.. _ModifyUPPOutput: + +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/sorc/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 instructions in the `UPP User's Guide `__ to make modifications to the ``fv3lam.xml`` file and to remake the flat text file, called ``postxconfig-NT-fv3lam.txt`` (default), that the UPP reads. + +After creating the new flat text file to reflect the changes, users will need to modify their ``config.yaml`` to point the workflow to the new text file. In ``config.yaml``, set the following: + +.. code-block:: console + + USE_CUSTOM_POST_CONFIG_FILE: true + CUSTOM_POST_CONFIG_FP: + +which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If ``USE_CUSTOM_POST_CONFIG_FILE`` is set to true, but 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 (``postxconfig-NT-fv3lam.txt``) has already been set up to output satellite products using the process described above in :numref:`Section %s`. + +Download and unpack the external files: + +.. code-block:: console + + mkdir crtm && cd crtm + wget https://github.com/NOAA-EMC/UPP/releases/download/upp_v11.0.0/fix.tar.gz + tar -xzf fix.tar.gz + +Modify the ``config.yaml`` file to include the following lines: + +.. code-block:: console + + USE_CRTM: true + 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 +================================== +A set of input files, including static (fix) data and raw initial and lateral boundary conditions (:term:`IC/LBCs`), 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. Therefore, users on these systems do not need to stage the fixed files manually because they have been prestaged, and the paths are set in ``ush/setup.sh``. Users on Level 3 & 4 systems can find the most recent SRW App release data in the `UFS SRW Application Data Bucket `__ by clicking on `Browse Bucket `__. + +.. _StaticFixFiles: + +Static Files +-------------- + +Static files are available in the `"fix" directory `__ of the SRW App Data Bucket. Users can download the full set of fix files as a tar file: + +.. code-block:: console + + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/fix_data.tgz + tar -xzf fix_data.tgz + +Alternatively, users can download the static files individually from the `"fix" directory `__ of the SRW Data Bucket using the ``wget`` command for each required file. A list of ``wget`` commands with links is provided :ref:`here ` for the release v2.1.0 fix file data. Users will need to create an appropriate directory structure for the files when downloading them individually. The best solution is to download the files into directories that mirror the structure of the `Data Bucket `__. + +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.yaml``. Add the following code to the ``task_run_fcst:`` section of the ``config.yaml`` file, and alter the variable paths accordingly: + +.. code-block:: console + + FIXgsm: + TOPO_DIR: + SFC_CLIMO_INPUT_DIR: + +.. _InitialConditions: + +Initial 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, GEFS, GDAS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. + +To download the model input data for the 12-hour "out-of-the-box" experiment configuration in ``config.community.yaml`` file, run: + +.. code-block:: console + + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/gst_data.tgz + tar -xzf gst_data.tgz + +To download data for different dates, model types, and formats, users can explore the ``input_model_data`` section of the data bucket and replace the links above with ones that fetch their desired data. + +.. _ICS-LBCS: + +Initial and Lateral Boundary Condition Organization +---------------------------------------------------- + +The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` must be set in the appropriate sections of the ``config.yaml`` file: + +.. code-block:: console + + task_get_extrn_ics: + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_SOURCE_BASEDIR_ICS: + EXTRN_MDL_DATA_STORES: disk + task_get_extrn_lbcs: + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_SOURCE_BASEDIR_LBCS: + EXTRN_MDL_DATA_STORES: disk + +The two ``EXTRN_MDL_SOURCE_BASEDIR_*CS`` variables describe where the :term:`IC ` and :term:`LBC ` file directories are located, respectively. For ease of reusing ``config.yaml`` across experiments, it is recommended that users set up the raw :term:`IC/LBC ` file paths to include the model name (e.g., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path-to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. + +When files are pulled from NOAA :term:`HPSS` (rather than downloaded from the data bucket), the naming convention looks something like: + +* 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`` + +* GDAS (NETCDF): + + * ICs: ``gdas.t{cycle}z.atmf{fhr}.nc`` and ``gdas.t{cycle}z.sfcf{fhr}.nc``; + * LBCs: ``gdas.t{cycle}z.atmf{fhr}.nc`` + +* 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 2- or 3-digit nth hour of the forecast (3-digits for FV3GFS/GDAS data and 2 digits for RAP/HRRR data). + +For example, a forecast using FV3GFS GRIB2 data that starts at 18h00 UTC would have a {cycle} value of 18, which is the 000th forecast hour. The LBCS file for 21h00 UTC would be named ``gfs.t18z.pgrb2.0p25.f003``. + +In some cases, it may be necessary to specify values for ``EXTRN_MDL_FILES_*CS`` variables. This is often the case with HRRR and RAP data. An example ``config.yaml`` excerpt using HRRR and RAP data appears below: + +.. code-block:: console + + task_get_extrn_ics: + EXTRN_MDL_NAME_ICS: HRRR + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_FILES_ICS: + - '{yy}{jjj}{hh}00{fcst_hr:02d}00' + task_get_extrn_lbcs: + EXTRN_MDL_NAME_LBCS: RAP + LBC_SPEC_INTVL_HRS: 3 + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_FILES_LBCS: + - '{yy}{jjj}{hh}00{fcst_hr:02d}00' + +Default Initial and Lateral Boundary Conditions +----------------------------------------------- + +The default initial and lateral boundary condition files are set to be a severe weather case from June 15, 2019 (20190615) at 18 UTC. FV3GFS GRIB2 files are the default model and file format. A tar file +(``gst_data.tgz``) containing the model data for this case is available in the `UFS SRW App Data Bucket `__. + +Running the App for Different Dates +----------------------------------- +If users want to run the SRW Application for dates other than June 15-16, 2019, they will need to modify the ``config.yaml`` settings, including the ``DATE_FIRST_CYCL`` and ``DATE_LAST_CYCL`` 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. + +Staging Initial Conditions Manually +----------------------------------- +If users want to run the SRW Application with raw model files for dates other than those that +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`` (which may be the same directory). The path to these variables can be set in the ``config.yaml`` file as shown :ref:`above `. 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: + +* GFS (GRIB2 or NEMSIO) - available for the last 10 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod/ +* GDAS (NETCDF) sfc files - available for the last 2 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod +* NAM - available for the last 8 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/nam/prod/ +* RAP - available for the last 2 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/rap/prod/ +* HRRR - available for the last 2 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/hrrr/prod/ + +AWS S3 Data Buckets: + +* GFS: https://registry.opendata.aws/noaa-gfs-bdp-pds/ +* GEFS: https://registry.opendata.aws/noaa-gefs/ +* GDAS: https://registry.opendata.aws/noaa-gfs-bdp-pds/ +* HRRR: https://registry.opendata.aws/noaa-hrrr-pds/ (necessary fields for initializing available for dates 2015 and newer) + +Google Cloud: + +* HRRR: https://console.cloud.google.com/marketplace/product/noaa-public/hrrr + +FTP Data Repository (data for SRW Release v1.0.0 & v1.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: + +* University of Utah HRRR archive: http://home.chpc.utah.edu/~u0553130/Brian_Blaylock/cgi-bin/hrrr_download.cgi +* NAM nest archive: https://www.ready.noaa.gov/archives.php +* NAM data older than 6 months can be requested through the Archive Information Request System: https://www.ncei.noaa.gov/has/HAS.FileAppRouter?datasetname=NAM218&subqueryby=STATION&applname=&outdest=FILE +* RAP isobaric data older than 6 months can be requested through the Archive Information Request System: https://www.ncei.noaa.gov/has/HAS.FileAppRouter?datasetname=RAP130&subqueryby=STATION&applname=&outdest=FILE + +Coexistence of Multiple Files for the Same Date +------------------------------------------------- +It is recommended that users have a separate directory for each file format if they choose to store files in multiple formats (e.g., GRIB2, NEMSIO, netCDF) for the same date. For example, the directory structure for a user storing GFS GRIB2 and NEMSIO files might resemble the following: + +.. code-block:: console + + /path-to/input_model_data/FV3GFS/grib2/YYYYMMDDHH + /path-to/input_model_data/FV3GFS/nemsio/YYYYMMDDHH + +Additionally, users must set the following environment variables if they plan to use GRIB2-formatted files for FV3GFS: + +.. code-block:: console + + FV3GFS_FILE_FMT_ICS: grib2 + FV3GFS_FILE_FMT_LBCS: grib2 + +This is ONLY necessary when using FV3GFS GRIB2 files. These settings may be removed when initializing from the default NEMSIO format for 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 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. + +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/TechnicalDetails/LAMGrids.rst b/docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst new file mode 100644 index 0000000000..1c97b4e0bc --- /dev/null +++ b/docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst @@ -0,0 +1,204 @@ +.. _LAMGrids: + +================================================================================= +Limited Area Model (:term:`LAM`) Grids: Predefined and User-Generated Options +================================================================================= +In order to set up the workflow and generate an experiment with the SRW Application, the user +must choose between various predefined :term:`FV3`-:term:`LAM` grids or generate a user-defined grid. +At this time, full support is only provided to those using one of the four predefined +grids supported in the v2.1.0 release, but other predefined grids are available (see :numref:`Section %s ` for more detail). Preliminary information is also provided at the end of this chapter describing 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 SRW App v2.1.0 release includes four predefined limited area model (:term:`LAM`) grids. To select a supported predefined grid, the ``PREDEF_GRID_NAME`` variable within the ``task_run_fcst:`` section of the ``config.yaml`` script must be set to one of the following four options: + +* ``RRFS_CONUS_3km`` +* ``RRFS_CONUS_13km`` +* ``RRFS_CONUS_25km`` +* ``SUBCONUS_Ind_3km`` + +These four options are provided for flexibility related to compute resources and supported physics options. Other predefined grids are listed :ref:`here `. The high-resolution 3-km :term:`CONUS` grid generally requires more compute power and works well with three of the five 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 other supported physics suites: ``FV3_GFS_v16`` and ``FV3_RAP``. + +.. _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 | + | | | + | | FV3_RAP | + +-------------------+------------------+ + | RRFS_CONUS_25km | FV3_GFS_v16 | + | | | + | | FV3_RAP | + +-------------------+------------------+ + +In theory, it is possible to run any of the supported physics suites 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 (:term:`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 3-km 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 parameterizations. 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`` and ``FV3_RAP`` suites generally should *not* be used with the 3-km domain because the cumulus physics used in those physics suites is not configured to run at the 3-km resolution. + +.. _RRFS_CONUS_3km: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_3km.sphr.native_wrtcmp.png + :alt: Map of the continental United States 3 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. + + *The boundary of the RRFS_CONUS_3km computational grid (red) and corresponding write-component grid (blue).* + +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 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 the 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 (such as HRRR or RAP data) that has a resolution similar to that of the native FV3-LAM (predefined) grid. + + +Predefined SUBCONUS Grid Over Indianapolis +-------------------------------------------- + +.. _SUBCONUS_Ind_3km: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/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 the computational grid boundaries in blue. + + *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 :term:`CONUS` centered 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: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_13km.sphr.native_wrtcmp.png + :alt: Map of the continental United States 13 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. + + *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`` or ``FV3_RAP`` physics suites. These suites use 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 25-km and 13-km. + +Predefined 25-km Grid +------------------------ + +.. _RRFS_CONUS_25km: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_25km.sphr.native_wrtcmp.png + :alt: Map of the continental United States 25 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. + + *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 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, 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 +out with the SRW App, more advanced users may wish to create their own predefined 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 (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 predefined 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. + +The steps to add such a grid to the workflow are as follows: + +#. 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/ush/valid_param_vals.yaml`` file. + +#. In ``ufs-srweather-app/ush/predef_grid_params.yaml``, add a stanza describing the parameters for NEW_GRID. An example of such a stanza is given :ref:`below `. For descriptions of the variables that need to be set, see Sections :numref:`%s ` and :numref:`%s `. + +To run a forecast experiment on NEW_GRID, start with a workflow configuration file for a successful experiment (e.g., ``config.community.yaml``, located in the ``ufs-srweather-app/ush`` subdirectory), and change the line for ``PREDEF_GRID_NAME`` in the ``task_run_fcst:`` section to ``NEW_GRID``: + +.. code-block:: console + + PREDEF_GRID_NAME: "NEW_GRID" + +Then, load the regional workflow python environment, specify the other experiment parameters in ``config.community.yaml``, and generate a new experiment/workflow using the ``generate_FV3LAM_wflow.py`` script (see :numref:`Chapter %s ` for details). + +Code Example +--------------- + +The following is an example of a code stanza for "NEW_GRID" to be added to ``predef_grid_params.yaml``: + +.. _NewGridExample: + +.. code-block:: console + + # + #--------------------------------------------------------------------- + # + # Stanza for NEW_GRID. This grid covers [description of the + # domain] with ~[size]-km cells. + # + #--------------------------------------------------------------------- + + "NEW_GRID": + + # The method used to generate the grid. This example is specifically for the "ESGgrid" method. + + GRID_GEN_METHOD: "ESGgrid" + + # ESGgrid parameters: + + ESGgrid_LON_CTR: -97.5 + ESGgrid_LAT_CTR: 38.5 + ESGgrid_DELX: 25000.0 + ESGgrid_DELY: 25000.0 + ESGgrid_NX: 200 + ESGgrid_NY: 112 + ESGgrid_PAZI: 0.0 + ESGgrid_WIDE_HALO_WIDTH: 6 + + # Forecast configuration parameters: + + DT_ATMOS: 40 + LAYOUT_X: 5 + LAYOUT_Y: 2 + BLOCKSIZE: 40 + + # Parameters for the write-component (aka "quilting") grid. + + QUILTING: + WRTCMP_write_groups: 1 + WRTCMP_write_tasks_per_group: 2 + WRTCMP_output_grid: "lambert_conformal" + WRTCMP_cen_lon: -97.5 + WRTCMP_cen_lat: 38.5 + WRTCMP_lon_lwr_left: -121.12455072 + WRTCMP_lat_lwr_left: 23.89394570 + + # Parameters required for the Lambert conformal grid mapping. + + WRTCMP_stdlat1: 38.5 + WRTCMP_stdlat2: 38.5 + WRTCMP_nx: 197 + WRTCMP_ny: 107 + WRTCMP_dx: 25000.0 + WRTCMP_dy: 25000.0 + +.. note:: + The process above explains how to create a new *predefined* grid, which can be used more than once. If a user prefers to create a custom grid for one-time use, the variables above can instead be specified in ``config.yaml``, and ``PREDEF_GRID_NAME`` can be set to a null string. In this case, it is not necessary to modify ``valid_param_vals.yaml`` or ``predef_grid_params.yaml``. Users can view an example configuration file for a custom grid `here `__. diff --git a/docs/UsersGuide/source/TechnicalDetails/TemplateVars.rst b/docs/UsersGuide/source/TechnicalDetails/TemplateVars.rst new file mode 100644 index 0000000000..2677888f5a --- /dev/null +++ b/docs/UsersGuide/source/TechnicalDetails/TemplateVars.rst @@ -0,0 +1,77 @@ +.. _TemplateVars: + +====================== +Template Variables +====================== + +The SRW App's experiment configuration system supports the use of template variables +in ``config_defaults.yaml`` and ``config.yaml``. A template variable --- or "template" --- is an experiment configuration variable that contains references to values of other variables. +These references are **not** set to the values of the referenced variables (or "expanded") when the experiment's variable definitions file (``var_defns.sh``) is generated or sourced. +Instead, they are expanded and evaluated **at run time** when bash's +``eval`` command is used on the template. + +Generic Example +================== + +As an example, consider a hypothetical template variable named ``MY_CMD`` that is defined in ``config_defaults.yaml`` +(or redefined by the user in ``config.yaml``) as follows: + + .. code-block:: console + + MY_CMD: 'cd ${some_dir}' + +Here, ``some_dir`` may be another experiment variable defined in ``var_defns.sh`` or a +local variable defined in a script or function that will evaluate the template. +It is important to use single quotes on the right-hand side of the definition above; +otherwise, bash will try to evaluate ``${some_dir}`` when constructing ``var_defns.sh``, +which may result in an error and/or unexpected behavior (e.g., if ``${some_dir}`` +is not yet defined). The experiment generation system will define ``MY_CMD`` in +``var_defns.sh`` in exactly the same way as in ``config_defaults.yaml`` and/or +``config.yaml``, e.g., ``MY_CMD: 'cd ${some_dir}'``. Then the following code snippet +in a script or function will evaluate the contents of ``MY_CMD`` using a locally-set +value of ``some_dir``: + + .. code-block:: none + + ... + . var_defns.sh # Source the experiment's variable definition file (assuming + # it is in the current directory). This defines the MY_CMD + # template variable (in addition to other variables). + ... + some_dir="20200715" # Set the local variable some_dir. + ... + eval ${MY_CMD} # Use eval to evaluate the contents of MY_CMD. The value of + # some_dir specified in this file a few lines above is substituted + # for ${some_dir} in MY_CMD before MY_CMD is evaluated. + +Graphics Plotting Example +============================ + +When attempting to generate graphics plots from a forecast, users have the option to +produce difference plots from two experiments that are on the same domain and +available for the same cycle starting date/time and forecast hours. +To generate difference plots, users must use the template variable ``COMOUT_REF`` +to indicate where the :term:`GRIB2` files from post-processing are located. + +In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will +take the form ``/path/to/expt_dirs/expt_name/$PDY$cyc/postprd``, where ``$PDY`` refers +to the cycle date in YYYYMMDD format, and ``$cyc`` refers to the starting hour of the cycle. +(These variables are set in previous tasks based on the value of ``DATE_FIRST_CYCL``.) +Given two experiments, ``expt1`` and ``expt2``, users can generate difference plots by +setting ``COMOUT_REF`` in the ``expt2`` configuration file (``config.yaml``) as follows: + +.. code-block:: console + + COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd' + +The ``expt2`` workflow already knows where to find its own post-processed output, so +``COMOUT_REF`` should point to post-processed output for the other experiment (``expt1``). + +In *nco* mode, this directory should be set to the location of the first experiment's +``COMOUT`` directory (``${COMOUT}`` in the example below) and end with ``${PDY}/${cyc}``. +For example: + +.. code-block:: console + + COMOUT_REF: '${COMOUT}/${PDY}/${cyc}/' + diff --git a/docs/UsersGuide/source/TechnicalDetails/index.rst b/docs/UsersGuide/source/TechnicalDetails/index.rst new file mode 100644 index 0000000000..dab9e02a3e --- /dev/null +++ b/docs/UsersGuide/source/TechnicalDetails/index.rst @@ -0,0 +1,17 @@ +.. UFS SR Weather App Users Guide, created by + sphinx-quickstart on Tue Feb 12 08:48:32 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Technical Details +==================== + +.. toctree:: + :maxdepth: 3 + + ConfigWorkflow + InputOutputFiles + LAMGrids + DefineWorkflow + TemplateVars + From 438814f87578d9cdfef6c8bbb6def7e73040628d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 6 Jul 2023 10:46:29 -0400 Subject: [PATCH 005/116] finish restructuring, rm images --- docs/UsersGuide/source/AQM.rst | 259 ---- docs/UsersGuide/source/BuildSRW.rst | 480 ------- docs/UsersGuide/source/Components.rst | 119 -- docs/UsersGuide/source/ConfigWorkflow.rst | 1248 ---------------- .../UsersGuide/source/ContainerQuickstart.rst | 390 ----- docs/UsersGuide/source/DefineWorkflow.rst | 242 ---- docs/UsersGuide/source/FAQ.rst | 201 --- docs/UsersGuide/source/Glossary.rst | 260 ---- docs/UsersGuide/source/InputOutputFiles.rst | 411 ------ docs/UsersGuide/source/Introduction.rst | 150 -- docs/UsersGuide/source/LAMGrids.rst | 204 --- docs/UsersGuide/source/Quickstart.rst | 98 -- docs/UsersGuide/source/RocotoInfo.rst | 236 --- docs/UsersGuide/source/RunSRW.rst | 1262 ----------------- docs/UsersGuide/source/TechnicalOverview.rst | 321 ----- docs/UsersGuide/source/TemplateVars.rst | 77 - docs/UsersGuide/source/Tutorial.rst | 586 -------- docs/UsersGuide/source/VXCases.rst | 313 ---- docs/UsersGuide/source/WE2Etests.rst | 412 ------ .../UsersGuide/source/_static/JenkinsCICD.png | Bin 86714 -> 0 bytes .../RRFS_CONUS_13km.sphr.native_wrtcmp.png | Bin 104826 -> 0 bytes .../RRFS_CONUS_25km.sphr.native_wrtcmp.png | Bin 103357 -> 0 bytes .../RRFS_CONUS_3km.sphr.native_wrtcmp.png | Bin 104950 -> 0 bytes .../source/_static/SRW_build_process.png | Bin 60664 -> 0 bytes .../_static/SRW_regional_workflow_gen.png | Bin 163031 -> 0 bytes .../source/_static/SRW_run_process.png | Bin 81455 -> 0 bytes .../source/_static/SRW_wflow_flowchart.png | Bin 145622 -> 0 bytes .../source/_static/SRW_wflow_input_path.png | Bin 141217 -> 0 bytes .../source/_static/SUBCONUS_Ind_3km.png | Bin 81808 -> 0 bytes docs/UsersGuide/source/index.rst | 23 +- 30 files changed, 4 insertions(+), 7288 deletions(-) delete mode 100644 docs/UsersGuide/source/AQM.rst delete mode 100644 docs/UsersGuide/source/BuildSRW.rst delete mode 100644 docs/UsersGuide/source/Components.rst delete mode 100644 docs/UsersGuide/source/ConfigWorkflow.rst delete mode 100644 docs/UsersGuide/source/ContainerQuickstart.rst delete mode 100644 docs/UsersGuide/source/DefineWorkflow.rst delete mode 100644 docs/UsersGuide/source/FAQ.rst delete mode 100644 docs/UsersGuide/source/Glossary.rst delete mode 100644 docs/UsersGuide/source/InputOutputFiles.rst delete mode 100644 docs/UsersGuide/source/Introduction.rst delete mode 100644 docs/UsersGuide/source/LAMGrids.rst delete mode 100644 docs/UsersGuide/source/Quickstart.rst delete mode 100644 docs/UsersGuide/source/RocotoInfo.rst delete mode 100644 docs/UsersGuide/source/RunSRW.rst delete mode 100644 docs/UsersGuide/source/TechnicalOverview.rst delete mode 100644 docs/UsersGuide/source/TemplateVars.rst delete mode 100644 docs/UsersGuide/source/Tutorial.rst delete mode 100644 docs/UsersGuide/source/VXCases.rst delete mode 100644 docs/UsersGuide/source/WE2Etests.rst delete mode 100644 docs/UsersGuide/source/_static/JenkinsCICD.png delete mode 100644 docs/UsersGuide/source/_static/RRFS_CONUS_13km.sphr.native_wrtcmp.png delete mode 100644 docs/UsersGuide/source/_static/RRFS_CONUS_25km.sphr.native_wrtcmp.png delete mode 100644 docs/UsersGuide/source/_static/RRFS_CONUS_3km.sphr.native_wrtcmp.png delete mode 100644 docs/UsersGuide/source/_static/SRW_build_process.png delete mode 100644 docs/UsersGuide/source/_static/SRW_regional_workflow_gen.png delete mode 100644 docs/UsersGuide/source/_static/SRW_run_process.png delete mode 100644 docs/UsersGuide/source/_static/SRW_wflow_flowchart.png delete mode 100644 docs/UsersGuide/source/_static/SRW_wflow_input_path.png delete mode 100644 docs/UsersGuide/source/_static/SUBCONUS_Ind_3km.png diff --git a/docs/UsersGuide/source/AQM.rst b/docs/UsersGuide/source/AQM.rst deleted file mode 100644 index 4c810f0d69..0000000000 --- a/docs/UsersGuide/source/AQM.rst +++ /dev/null @@ -1,259 +0,0 @@ -.. _AQM: - -===================================== -Air Quality Modeling (SRW-AQM) -===================================== - -The standard SRW App distribution uses the uncoupled version of the UFS Weather Model (atmosphere-only). However, users have the option to use a coupled version of the SRW App that includes the standard distribution (atmospheric model) plus the Air Quality Model (AQM). - -The AQM is a UFS Application that dynamically couples the Community Multiscale Air Quality (:term:`CMAQ`) model with the UFS Weather Model (WM) through the :term:`NUOPC` Layer to simulate temporal and spatial variations of atmospheric compositions (e.g., ozone and aerosol compositions). The CMAQ model, treated as a column chemistry model, updates concentrations of chemical species (e.g., ozone and aerosol compositions) at each integration time step. The transport terms (e.g., :term:`advection` and diffusion) of all chemical species are handled by the UFS WM as tracers. - -.. note:: - - Although this chapter is the primary documentation resource for running the AQM configuration, users may need to refer to :numref:`Chapter %s ` and :numref:`Chapter %s ` for additional information on building and running the SRW App, respectively. - -.. attention:: - - These instructions should work smoothly on Hera and WCOSS2, but users on other systems may need to make additional adjustments. - -Quick Start Guide (SRW-AQM) -===================================== - -Download the Code -------------------- - -Clone the ``develop`` branch of the authoritative SRW App repository: - -.. code-block:: console - - git clone -b develop https://github.com/ufs-community/ufs-srweather-app - cd ufs-srweather-app - -Checkout Externals ---------------------- - -Users must run the ``checkout_externals`` script to collect (or "check out") the individual components of the SRW App (AQM version) from their respective GitHub repositories. - -.. code-block:: console - - ./manage_externals/checkout_externals - -Build the SRW App with AQM ------------------------------ - -On Hera and WCOSS2, users can build the SRW App AQM binaries with the following command: - -.. code-block:: console - - ./devbuild.sh -p= -a=ATMAQ - -where ```` is ``hera``, or ``wcoss2``. The ``-a`` argument indicates the configuration/version of the application to build. - -Building the SRW App with AQM on other machines, including other `Level 1 `__ platforms, is not currently guaranteed to work, and users may have to make adjustments to the modulefiles for their system. - -Load the ``workflow_tools`` Environment --------------------------------------------- - -Load the python environment for the workflow: - -.. code-block:: console - - # On WCOSS2 (do not run on other systems): - source ../versions/run.ver.wcoss2 - # On all systems (including WCOSS2): - module use /path/to/ufs-srweather-app/modulefiles - module load wflow_ - -where ```` is ``hera`` or ``wcoss2``. The workflow should load on other platforms listed under the ``MACHINE`` variable in :numref:`Section %s `, but users may need to adjust other elements of the process when running on those platforms. - -If the console outputs a message, the user should run the commands specified in the message. For example, if the output says: - -.. code-block:: console - - Please do the following to activate conda: - > conda activate workflow_tools - -then the user should run ``conda activate workflow_tools``. Otherwise, the user can continue with configuring the workflow. - -.. _AQMConfig: - -Configure and Experiment ---------------------------- - -Users will need to configure their experiment by setting parameters in the ``config.yaml`` file. To start, users can copy a default experiment setting into ``config.yaml``: - -.. code-block:: console - - cd ush - cp config.aqm.community.yaml config.yaml - -Users may prefer to copy the ``config.aqm.nco.realtime.yaml`` for a default "nco" mode experiment instead. - -Users will need to change the ``MACHINE`` and ``ACCOUNT`` variables in ``config.yaml`` to match their system. They may also wish to adjust other experiment settings. For more information on each task and variable, see :numref:`Chapter %s `. - -Users may also wish to change :term:`cron`-related parameters in ``config.yaml``. In the ``config.aqm.community.yaml`` file, which was copied into ``config.yaml``, cron is used for automatic submission and resubmission of the workflow: - -.. code-block:: console - - workflow: - USE_CRON_TO_RELAUNCH: true - CRON_RELAUNCH_INTVL_MNTS: 3 - -This means that cron will submit the launch script every 3 minutes. Users may choose not to submit using cron or to submit at a different frequency. Note that users should create a crontab by running ``crontab -e`` the first time they use cron. - -Generate the Workflow ------------------------- - -Generate the workflow: - -.. code-block:: console - - ./generate_FV3LAM_wflow.py - -Run the Workflow ------------------- - -If ``USE_CRON_TO_RELAUNCH`` is set to true in ``config.yaml`` (see :numref:`Section %s `), the workflow will run automatically. If it was set to false, users must submit the workflow manually from the experiment directory: - -.. code-block:: console - - cd / - ./launch_FV3LAM_wflow.sh - -Repeat the launch command regularly until a SUCCESS or FAILURE message appears on the terminal window. See :numref:`Section %s ` for more on the ```` and ```` variables. - -Users may check experiment status from the experiment directory with either of the following commands: - -.. code-block:: console - - # Check the experiment status (best for cron jobs) - rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - - # Check the experiment status and relaunch the workflow (for manual jobs) - ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow - - -WE2E Test for AQM -======================= - -Build the app for AQM: - -.. code-block:: console - - ./devbuild.sh -p=hera -a=ATMAQ - - -Add the WE2E test for AQM to the list file: - -.. code-block:: console - - echo "custom_ESGgrid" > my_tests.txt - echo "aqm_grid_AQM_NA13km_suite_GFS_v16" >> my_tests.txt - - -Run the WE2E test: - -.. code-block:: console - - $ ./run_WE2E_tests.py -t my_tests.txt -m hera -a gsd-fv3 -q - - - -Additional Tasks for AQM -=============================== - -Structure of SRW-AQM -------------------------- - -The flowchart of the non-DA (data assimilation) SRW-AQM (Air Quality Modeling) is illustrated in :numref:`Figure %s `. Compared to the non-coupled (ATM stand-alone) FV3-LAM, SRW-AQM has additional tasks for pre- and post-processing. For pre-processing, multiple emission data such as NEXUS, fire, and point-source emission are retrieved or created for air quality modeling. Moreover, the chemical initial conditions (ICs) are extracted from the restart files of the previous cycle and added to the existing IC files. The chemical lateral boundary conditions (LBCs) and the GEFS aerosol data are also adeded to the existing LBC files. For post-processing, air quality forecast products for O3 and PM2.5 are generated and the bias-correction technique is applied to improve the accuracy of the results. - -.. _FlowProcAQM: - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW-AQM_workflow.png - :alt: Flowchart of the SRW-AQM tasks. - - *Workflow structure of SRW-AQM (non-DA)* - - - -Pre-processing Tasks of SRW-AQM ------------------------------------- - -The pre-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. - -.. _TasksPrepAQM: - -.. table:: Tasks for pre-processing of AQM - - +-----------------------+--------------------------------------------------------------------+ - | **Task name** | **Description** | - +=======================+====================================================================+ - | nexus_gfs_sfc | This task retrieves the GFS surface files from the previous cycle | - | | in NRT (Near-Real-Time) or current cycle in retrospective cases. | - | | The surface radiation, soil moisture and temperature fields are | - | | needed for the MEGAN biogenics emissions within nexus_emission. | - +-----------------------+--------------------------------------------------------------------+ - | nexus_emission | This task prepares the run directory with gridded emission inputs, | - | | run nexus to create model ready emission for the given simulation | - | | day, and post processes nexus output to make it more readable. The | - | | task will also split the task into multiple jobs set by the user. | - +-----------------------+--------------------------------------------------------------------+ - | nexus_post_split | This task combines the nexus_emission outputs into a single job. | - +-----------------------+--------------------------------------------------------------------+ - | fire_emission | This tasks is used to convert both satellite-retrieved gas and | - | | aerosol species emissions (RAVE) from mass (kg) to emission rates | - | | (kg/m2/s) and create 3-day hourly model-ready fire emission input | - | | files. | - +-----------------------+--------------------------------------------------------------------+ - | point_source | This task aggregates the anthropogenic point source sectors of the | - | | National Emission Inventory(NEI) into a ready-to-input point-source| - | | emission file based on the weekday/weekend/holiday patterns of each| - | | sector and date/time of the simulation. | - +-----------------------+--------------------------------------------------------------------+ - | aqm_ics | This task creates a chemical initial condition file by using the | - | | previous cycle restart files. | - +-----------------------+--------------------------------------------------------------------+ - | aqm_lbcs | This task adds the chemical lateral boundary condition (LBC) upon | - | | the meteorological lateral boundary condition to form the full-set | - | | ready-to-input LBC for the simulation. It includes two sub-tasks: | - | | the gaseous species LBC and dynamic aerosol LBC. The former adds | - | | static gaseous LBC using monthly mean global data. The latter is | - | | the parallel job, which extracts the GEFS-Aerosol Model's output | - | | along the regional domain, and performs the species conversion | - | | from GOCART aerosols to CMAQ aerosols. | - +-----------------------+--------------------------------------------------------------------+ - - -Post-processing Tasks of SRW-AQM ------------------------------------- - -The post-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. Since the module required to run these tasks is available only on WCOSS2, these tasks should not be defined in the configuration file ``config.yaml`` on other platforms. - -.. _TasksPostAQM: - -.. table:: Tasks for post-processing of AQM - - +-----------------------+--------------------------------------------------------------------+ - | **Task name** | **Description** | - +=======================+====================================================================+ - | pre_post_stat | This task creates surface (i.e., model 1st level) meteorological | - | | and chemical files to support air quality product generation and | - | | generate training data to support bias correction tasks. | - +-----------------------+--------------------------------------------------------------------+ - | post_stat_o3 | This task generates air quality forecast products including hourly | - | | -average and statistical products for O3 (e.g., daily 8-hour | - | | average maximum O3). | - +-----------------------+--------------------------------------------------------------------+ - | post_stat_pm25 | This task generates air quality forecast products including hourly | - | | -average and statistical products for PM2.5 (e.g., 24-hour average | - | | PM2.5). | - +-----------------------+--------------------------------------------------------------------+ - | bias_correction_o3 | This task applies a bias-correction technique (e.g., analog | - | | ensemble) to improve model raw forecast for O3 and generates the | - | | bias-corrected O3 products. | - +-----------------------+--------------------------------------------------------------------+ - | bias_correction_pm25 | This task applies a bias-correction technique (e.g., analog | - | | ensemble) to improve model raw forecast for PM2.5 and generates the| - | | bias-corrected PM2.5 products. | - +-----------------------+--------------------------------------------------------------------+ - diff --git a/docs/UsersGuide/source/BuildSRW.rst b/docs/UsersGuide/source/BuildSRW.rst deleted file mode 100644 index e768372233..0000000000 --- a/docs/UsersGuide/source/BuildSRW.rst +++ /dev/null @@ -1,480 +0,0 @@ -.. _BuildSRW: - -========================== -Building 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 built, users can configure experiments and generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. - -.. attention:: - - The SRW Application has `four levels of support `__. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. This chapter can also serve as a starting point for running the SRW App on other systems (including generic Linux/Mac systems), but the user may need to perform additional troubleshooting. - -.. note:: - The :ref:`container approach ` is recommended for a smoother first-time build and run experience. Building without a container may allow for more customization. However, the non-container approach requires more in-depth system-based knowledge, especially on Level 3 and 4 systems, so it is less appropriate for beginners. - -To build the SRW App, users will complete the following steps: - - #. :ref:`Install prerequisites ` - #. :ref:`Clone the SRW App from GitHub ` - #. :ref:`Check out the external repositories ` - #. :ref:`Set up the build environment and build the executables ` - -.. _AppBuildProc: - -.. figure:: _static/SRW_build_process.png - :alt: Flowchart describing the SRW App build process. - - *Overview of the SRW App Build Process* - - -.. _HPCstackInfo: - -Install the Prerequisite Software Stack -========================================== - -Currently, installation of the prerequisite software stack is supported via HPC-Stack. :term:`HPC-Stack` is a repository that provides a unified, shell script-based system to build the software stack required for `UFS `__ applications such as the SRW App. - -.. Attention:: - Skip the HPC-Stack installation if working on a `Level 1 system `__ (e.g., Cheyenne, Hera, Orion, NOAA Cloud), and :ref:`continue to the next section `. - -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) 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) 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 `. - -.. attention:: - Although HPC-Stack is the fully-supported option as of the v2.1.0 release, UFS applications are gradually shifting to :term:`spack-stack`, which is a :term:`Spack`-based method for installing UFS prerequisite software libraries. The spack-stack is currently used on NOAA Cloud platforms and in containers, while HPC-Stack is still used on other Level 1 systems and is the software stack validated by the UFS Weather Model as of the v2.1.0 release. Users are encouraged to check out `spack-stack `__ to prepare for the upcoming shift in support from HPC-Stack to spack-stack. - -After completing installation, continue to the next section (:numref:`Section %s: Download the UFS SRW Application Code `). - -.. _DownloadSRWApp: - -Download the UFS SRW Application Code -====================================== -The SRW Application source code is publicly available on GitHub. To download the SRW App code, clone the ``develop`` branch of the repository: - -.. code-block:: console - - git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git - -The cloned repository contains the configuration files and sub-directories shown in -:numref:`Table %s `. The user may set an ``$SRW`` environment variable to point to the location of the new ``ufs-srweather-app`` repository. For example, if ``ufs-srweather-app`` was cloned into the ``$HOME`` directory, the following commands will set an ``$SRW`` environment variable in a bash or csh shell, respectively: - -.. code-block:: console - - export SRW=$HOME/ufs-srweather-app - setenv SRW $HOME/ufs-srweather-app - -.. _FilesAndSubDirs: - -.. table:: Files and sub-directories of the ufs-srweather-app repository - - +--------------------------------+-----------------------------------------------------------+ - | **File/Directory Name** | **Description** | - +================================+===========================================================+ - | CMakeLists.txt | Main CMake file for SRW App | - +--------------------------------+-----------------------------------------------------------+ - | devbuild.sh | SRW App build script | - +--------------------------------+-----------------------------------------------------------+ - | docs | Contains release notes, documentation, and User's Guide | - +--------------------------------+-----------------------------------------------------------+ - | environment.yml | Contains information on the package versions required for | - | | the regional workflow environment. | - +--------------------------------+-----------------------------------------------------------+ - | etc | Contains Lmod startup scripts | - +--------------------------------+-----------------------------------------------------------+ - | Externals.cfg | Includes tags pointing to the correct version of the | - | | external GitHub repositories/branches used in the SRW | - | | App. | - +--------------------------------+-----------------------------------------------------------+ - | jobs | Contains the *j-job* script for each workflow task. These | - | | scripts set up the environment variables and call an | - | | *ex-script* script located in the ``scripts`` | - | | subdirectory. | - +--------------------------------+-----------------------------------------------------------+ - | LICENSE.md | CC0 license information | - +--------------------------------+-----------------------------------------------------------+ - | manage_externals | Utility for checking out external repositories | - +--------------------------------+-----------------------------------------------------------+ - | modulefiles | Contains build and workflow modulefiles | - +--------------------------------+-----------------------------------------------------------+ - | parm | Contains parameter files. Includes UFS Weather Model | - | | configuration files such as ``model_configure``, | - | | ``diag_table``, and ``field_table``. | - +--------------------------------+-----------------------------------------------------------+ - | README.md | Contains SRW App introductory information | - +--------------------------------+-----------------------------------------------------------+ - | rename_model.sh | Used to rename the model before it is transitioned into | - | | operations. The SRW App is a generic app that is the base | - | | for models such as :term:`AQM` and :term:`RRFS`. When | - | | these models become operational, variables like | - | | ``HOMEdir`` and ``PARMdir`` will be renamed to | - | | ``HOMEaqm``/``HOMErrfs``, ``PARMaqm``/``PARMrrfs``, etc. | - | | using this script. | - +--------------------------------+-----------------------------------------------------------+ - | scripts | Contains the *ex-script* for each workflow task. | - | | These scripts are where the script logic and executables | - | | are contained. | - +--------------------------------+-----------------------------------------------------------+ - | sorc | Contains CMakeLists.txt; external repositories | - | | will be cloned into this directory. | - +--------------------------------+-----------------------------------------------------------+ - | tests | Contains SRW App tests, including workflow end-to-end | - | | (WE2E) tests. | - +--------------------------------+-----------------------------------------------------------+ - | 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 | - +--------------------------------+-----------------------------------------------------------+ - | ush | Contains utility scripts. Includes the experiment | - | | configuration file and the experiment generation file. | - +--------------------------------+-----------------------------------------------------------+ - | versions | Contains ``run.ver`` and ``build.ver`` files, which track | - | | package versions at run time and compile time, | - | | respectively. | - +--------------------------------+-----------------------------------------------------------+ - -.. COMMENT: Is environment.yml deprecated? Remove? - -.. _CheckoutExternals: - -Check Out External Components -================================ - -The SRW App relies on a variety of components (e.g., UFS_UTILS, ufs-weather-model, and UPP) detailed in :numref:`Chapter %s ` of this User's Guide. Each component has its own repository. Users must run the ``checkout_externals`` script to collect the individual components of the SRW App from their respective GitHub 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 (e.g., ``ush``, ``sorc``). - -Run the executable that pulls in SRW App components from external repositories: - -.. code-block:: console - - cd - ./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. - -To see more options for the ``checkout_externals`` script, users can run ``./manage_externals/checkout_externals -h``. For example: - - * ``-S``: Outputs the status of the repositories managed by ``checkout_externals``. By default only summary information is provided. Use with the ``-v`` (verbose) option to see details. - * ``-x [EXCLUDE [EXCLUDE ...]]``: allows users to exclude components when checking out externals. - * ``-o``: By default only the required externals are checked out. This flag will also check out the optional externals. - -Generally, users will not need to use the options and can simply run the script, but the options are available for those who are curious. - -.. _BuildExecutables: - -Set Up the Environment and Build the Executables -=================================================== - -.. _DevBuild: - -``devbuild.sh`` Approach ------------------------------ - -On Level 1 systems for which a modulefile is provided under the ``modulefiles`` directory, users can build the SRW App binaries with the following command: - -.. code-block:: console - - ./devbuild.sh --platform= - -where ```` is replaced with the name of the platform the user is working on. Valid values include: ``cheyenne`` | ``gaea`` | ``hera`` | ``jet`` | ``linux`` | ``macos`` | ``noaacloud`` | ``orion`` - -.. note:: - Although build modulefiles exist for generic Linux and MacOS machines, users will need to alter these according to the instructions in Sections :numref:`%s ` & :numref:`%s `. Users on these systems may have more success building the SRW App with the :ref:`CMake Approach ` instead. - -If compiler auto-detection fails for some reason, specify it using the ``--compiler`` argument. For example: - -.. code-block:: console - - ./devbuild.sh --platform=hera --compiler=intel - -where valid values are ``intel`` or ``gnu``. - -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. - -If users want to build the optional ``GSI`` and ``rrfs_utl`` components for :term:`RRFS`, they can pass the ``gsi`` and ``rrfs_utils`` arguments to ``devbuild.sh``. For example: - -.. code-block:: console - - ./devbuild.sh -p=hera gsi rrfs_utils - -.. note:: - RRFS capabilities are currently build-only features. They are not yet available for use at runtime. - -The last few lines of the RRFS console output should be: - -.. code-block:: console - - [100%] Built target RRFS_UTILS - Install the project... - -- Install configuration: "RELEASE" - -- Installing: /path/to/ufs-srweather-app/exec/ufs_srweather_app.settings - -After running ``devbuild.sh``, the executables listed in :numref:`Table %s ` should appear in the ``ufs-srweather-app/exec`` directory. If users choose to build the ``GSI`` and ``rrfs_utils`` components, the executables listed in :numref:`Table %s ` will also appear there. If the ``devbuild.sh`` build method does not work, or if users are not on a supported machine, they will have to manually set up the environment and build the SRW App binaries with CMake as described in :numref:`Section %s `. - -.. _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 | - +------------------------+---------------------------------------------------------------------------------+ - | 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 | - +------------------------+---------------------------------------------------------------------------------+ - | filter_topo | Filters topography based on resolution | - +------------------------+---------------------------------------------------------------------------------+ - | fregrid | Remaps data from the input mosaic grid to the output mosaic grid | - +------------------------+---------------------------------------------------------------------------------+ - | fvcom_to_FV3 | Determines lake surface conditions for the Great Lakes | - +------------------------+---------------------------------------------------------------------------------+ - | global_cycle | Updates the GFS surface conditions using external snow and sea ice analyses | - +------------------------+---------------------------------------------------------------------------------+ - | global_equiv_resol | Calculates a global, uniform, cubed-sphere equivalent resolution for the | - | | regional Extended Schmidt Gnomonic (ESG) grid | - +------------------------+---------------------------------------------------------------------------------+ - | inland | Creates an inland land mask by determining inland (i.e., non-coastal) points | - | | and assigning a value of 1. Default value is 0. | - +------------------------+---------------------------------------------------------------------------------+ - | lakefrac | Calculates the ratio of the lake area to the grid cell area at each atmospheric | - | | grid point. | - +------------------------+---------------------------------------------------------------------------------+ - | make_hgrid | Computes geo-referencing parameters (e.g., latitude, longitude, grid cell area) | - | | for global uniform grids | - +------------------------+---------------------------------------------------------------------------------+ - | make_solo_mosaic | Creates mosaic files with halos | - +------------------------+---------------------------------------------------------------------------------+ - | orog | Generates orography, land mask, and gravity wave drag files from fixed files | - +------------------------+---------------------------------------------------------------------------------+ - | orog_gsl | Creates orographic statistics fields required for the orographic drag suite | - | | developed by NOAA's Global Systems Laboratory (GSL) | - +------------------------+---------------------------------------------------------------------------------+ - | 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 lateral boundary | - | | conditions (LBCs) in the orography and grid files | - +------------------------+---------------------------------------------------------------------------------+ - | upp.x | Post processor for the model output | - +------------------------+---------------------------------------------------------------------------------+ - | ufs_model | UFS Weather Model executable | - +------------------------+---------------------------------------------------------------------------------+ - | vcoord_gen | Generates hybrid coordinate interface profiles | - +------------------------+---------------------------------------------------------------------------------+ - -.. _RRFSexec: - -.. table:: Names and descriptions of the executables produced when the RRFS option is enabled - - +----------------------------+-----------------------------------------------------------------------------+ - | **Executable Name** | **Description** | - +============================+=============================================================================+ - | gsi.x | Runs the Gridpoint Statistical Interpolation (GSI). | - +----------------------------+-----------------------------------------------------------------------------+ - | enkf.x | Runs the Ensemble Kalman Filter. | - +----------------------------+-----------------------------------------------------------------------------+ - | adjust_soiltq.exe | Uses the lowest-level temperature and moisture analysis increments to | - | | adjust the soil moisture and soil temperature after analysis. | - +----------------------------+-----------------------------------------------------------------------------+ - | check_imssnow_fv3lam.exe | This is a tool used to read snow and ice fields from surface files and | - | | check those fields. | - +----------------------------+-----------------------------------------------------------------------------+ - | fv3lam_nonvarcldana.exe | Runs the non-variational cloud and precipitable hydrometeor analysis based | - | | on the METAR cloud observations, satellite retrieved cloud top products, | - | | and radar reflectivity. | - +----------------------------+-----------------------------------------------------------------------------+ - | gen_annual_maxmin_GVF.exe | Generates maximum and minimum greenness vegetation fraction (GVF) files | - | | based on year-long GVF observations for the ``update_GVF`` process. | - +----------------------------+-----------------------------------------------------------------------------+ - | gen_cs.exe | NCL scripts to do cross section plotting. | - +----------------------------+-----------------------------------------------------------------------------+ - | gen_ensmean_recenter.exe | Runs the ensemble mean/recentering calculation for FV3LAM ensemble files. | - +----------------------------+-----------------------------------------------------------------------------+ - | lakesurgery.exe | Replaces the existing lake depth with the GLOBathy bathymetry. It is | - | | designed to work with the HRRR model. | - +----------------------------+-----------------------------------------------------------------------------+ - | nc_diag_cat.x | Performs :term:`NetCDF` Diagnostic Concatenation. Reads metadata while | - | | allocating necessary space, defines variables with the metadata (no | - | | attributes are stored), then finally add data to the output file. | - | | This is the MPI executable. | - +----------------------------+-----------------------------------------------------------------------------+ - | process_imssnow_fv3lam.exe | Uses FV3LAM snow and ice fields based on the snow and ice information from | - | | imssnow. | - +----------------------------+-----------------------------------------------------------------------------+ - | process_larccld.exe | Processes NASA Langley cloud top product, which reads the cloud top | - | | pressure, temperature, etc. and maps them to the ESG grid. | - +----------------------------+-----------------------------------------------------------------------------+ - | process_Lightning.exe | Processes lightning data. Reads NLDN NetCDF observation files and map the | - | | lightning observations into FV3LAM ESG grid. | - +----------------------------+-----------------------------------------------------------------------------+ - | process_metarcld.exe | Processes METAR ceilometer cloud observations. Reads the cloud base and | - | | coverage observations from PrepBUFR and distributes the cloud, weather, | - | | and visibility observations to the ESG grid. | - +----------------------------+-----------------------------------------------------------------------------+ - | process_NSSL_mosaic.exe | Processes :term:`NSSL` MRMS radar reflectivity mosaic observations. Reads | - | | 33-level NSSL MRMS radar reflectivity grib2 files and then interpolates the | - | | reflectivity horizontally to the ESG grid. | - +----------------------------+-----------------------------------------------------------------------------+ - | process_updatesst.exe | Updates Sea Surface Temperature (SST) field based on the SST analysis from | - | | NCEP. | - +----------------------------+-----------------------------------------------------------------------------+ - | ref2tten.exe | Calculates temperature tendency based on the radar reflectivity observation | - | | at each grid point. This temperature tendency can be used by the model | - | | during integration as latent heating initialization for ongoing | - | | precipitation systems, especially convection. | - +----------------------------+-----------------------------------------------------------------------------+ - | test_nc_unlimdims.x | Checks to see the number of fields with unlimited dimensions in NetCDF | - | | files. | - +----------------------------+-----------------------------------------------------------------------------+ - | ufs_srweather_app.settings | | - +----------------------------+-----------------------------------------------------------------------------+ - | update_bc.exe | Adjusts 0-h boundary conditions based on the analysis results during data | - | | assimilation cycling. | - +----------------------------+-----------------------------------------------------------------------------+ - | update_GVF.exe | Updates the GVF in the surface file based on the real-time observation | - | | files. | - +----------------------------+-----------------------------------------------------------------------------+ - | update_ice.exe | Replaces ice fields in warm start surface files based on the forecast from | - | | cold start forecast using the GFS as the initial file. | - +----------------------------+-----------------------------------------------------------------------------+ - | use_raphrrr_sfc.exe | Uses RAP and HRRR surface fields to replace the surface fields in FV3LAM. | - | | This is only used for starting the RRFS surface cycling. | - +----------------------------+-----------------------------------------------------------------------------+ - -.. COMMENT: What does ufs_srweather_app.settings do? - - precipitable hydrometeor analysis? - - What does the update_ice.exe description mean? - - -.. _CMakeApproach: - -CMake Approach ------------------ - -Set Up the Build Environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. attention:: - * If users successfully built the executables in :numref:`Table %s `, they should skip to step :numref:`Chapter %s `. - * Users who want to build the SRW App on MacOS or generic Linux systems should skip to :numref:`Section %s ` and follow the approach there. - -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, users can run one of the following two commands depending on whether they have a bash or csh shell, respectively: - -.. code-block:: console - - source etc/lmod-setup.sh gaea - source etc/lmod-setup.csh gaea - -.. note:: - - If users execute one of the above commands on systems that don't need it, it will not cause any problems (it will simply do a ``module purge``). - -From here, ``Lmod`` is ready to load the modulefiles needed by the SRW App. These modulefiles are located in the ``modulefiles`` directory. To load the necessary modulefile for a specific ```` using a given ````, 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 (including generic Linux/MacOS 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, depending on whether they are using a bash or csh/tcsh shell, respectively: - -.. code-block:: - - export = - setenv - -Note that building the SRW App without Lmod is not supported at this time. It should be possible to do so, but it has not been tested. Users are encouraged to install Lmod on their system. - -.. _BuildCMake: - -Build the Executables Using CMake -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -After setting up the build environment in the preceding section (by loading the ``build__`` modulefile), users need to build the executables required to run the SRW App. 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=.. -DCMAKE_INSTALL_BINDIR=exec .. - make -j 4 >& build.out & - -``-DCMAKE_INSTALL_PREFIX`` specifies the location where the ``exec``, ``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`` 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., ``-j 8``, ``-j 2``), 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/exec`` directory. These executables are described in :numref:`Table %s `. - -.. hint:: - - If you see the ``build.out`` file, but there is no ``ufs-srweather-app/exec`` directory, wait a few more minutes for the build to complete. - -.. _MacLinuxDetails: - -Additional Details for Building on MacOS or Generic Linux ------------------------------------------------------------- - -.. note:: - Users who are **not** building the SRW App on MacOS or generic Linux platforms may skip to :numref:`Section %s ` to finish building the SRW App or continue to :numref:`Chapter %s ` to configure and run an experiment. - -The SRW App can be built on MacOS and generic Linux machines after the prerequisite software has been installed on these systems (via :term:`HPC-Stack` or :term:`spack-stack`). The installation for MacOS is architecture-independent and has been tested using both x86_64 and M1 chips (running natively). The following configurations for MacOS have been tested: - - #. MacBookPro 2019, 2.4 GHz 8-core Intel Core i9 (x86_64), Monterey Sur 12.1, GNU compiler suite v.11.3.0 (gcc, gfortran, g++); mpich 3.3.2 or openmpi/4.1.2 - #. MacBookAir 2020, M1 chip (arm64, running natively), 4+4 cores, Big Sur 11.6.4, GNU compiler suite v.11.3.0 (gcc, gfortran, g++); mpich 3.3.2 or openmpi/4.1.2 - #. MacBook Pro 2015, 2.8 GHz Quad-Core Intel Core i7 (x86_64), Catalina OS X 10.15.7, GNU compiler suite v.11.2.0_3 (gcc, gfortran, g++); mpich 3.3.2 or openmpi/4.1.2 - -Several Linux builds have been tested on systems with x86_64 architectures. - -The ``./modulefiles/build__gnu.lua`` modulefile (where ```` is ``macos`` or ``linux``) is written as a Lmod module in the Lua language, and it can be loaded once the Lmod module environment has been initialized (which should have happened even prior to :ref:`installing HPC-Stack `). This module lists the location of the HPC-Stack modules, loads the meta-modules and modules, sets serial and parallel compilers, additional flags, and any environment variables needed for building the SRW App. The modulefile must be modified to include the absolute path to the user's HPC-Stack installation: - -.. code-block:: console - - - This path should point to your HPCstack installation directory - local HPCstack="/Users/username/hpc-stack/install" - -Linux users need to configure the ``ufs-srweather-app/etc/lmod-setup.sh`` file for the ``linux`` case and set the ``BASH_ENV`` variable to point to the Lmod initialization script. There is no need to modify this script for the ``macos`` case presuming that Lmod followed a standard installation procedure using the Homebrew package manager for MacOS. - -Next, users must source the Lmod setup file, just as they would on other systems, and load the modulefiles needed for building and running the SRW App: - -.. code-block:: console - - source etc/lmod-setup.sh - module use - module load build__gnu - export LDFLAGS+=" -L${MPI_ROOT}/lib " - -In a csh/tcsh shell, users would run ``source etc/lmod-setup.csh `` in place of the first line in the code block above. The last line is primarily needed for the MacOS platforms. - -Proceed to building the executables using the process outlined in :numref:`Step %s `. - -Run an Experiment -===================== - -To configure and run an experiment, users should proceed to :numref:`Chapter %s `. diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst deleted file mode 100644 index 621ff91edd..0000000000 --- a/docs/UsersGuide/source/Components.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. _Components: - -============================ -SRW Application Components -============================ - -The SRW Application assembles a variety of components, including: - -* Pre-processor Utilities & Initial Conditions -* 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 the `GitHub Discussions `__ forum. - -.. _Utils: - -Pre-processor Utilities and Initial Conditions -============================================== - -The SRW Application includes a number of pre-processing utilities (UFS_UTILS) that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), these utilities 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 :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3`-:term:`LAM`. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS Technical Documentation `__ and in the `UFS_UTILS Scientific Documentation `__. - -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 `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 (:term:`LAM`) capability (:cite:t:`BlackEtAl2021`). The :term:`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 accessed `here `__. - -Supported model resolutions in this release include 3-, 13-, and 25-km predefined contiguous U.S. (:term:`CONUS`) domains, each with 127 vertical levels. Preliminary tools for users to define their own domain are also available in the release with full, formal support of these tools to be provided in future releases. The Extended Schmidt Gnomonic (ESG) grid is used with the FV3-LAM, which features relatively uniform grid cells across the entirety of the domain. Additional information about the FV3 dynamical core can be found in the `scientific documentation `__, the `technical documentation `__, and on the `NOAA Geophysical Fluid Dynamics Laboratory website `__. - -Model Physics ---------------- - -The Common Community Physics Package (CCPP), described `here `__, 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 most recent SRW App release (v2.1.0) included four supported physics suites, and a fifth has since been added: FV3_RRFS_v1beta, FV3_GFS_v16, FV3_WoFS_v0, FV3_HRRR, and FV3_RAP (new!). The FV3_RRFS_v1beta physics suite is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (:term:`RRFS`) planned for 2023-2024, and the FV3_GFS_v16 is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. A detailed list of CCPP updates since the SRW App v2.0.0 release is available :ref:`here `. A full scientific description of CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. Additionally, a CCPP single-column model (`CCPP-SCM `__) option has also been developed as a child repository. Users can refer to the `CCPP Single Column Model User and Technical Guide `__ for more details. This CCPP-SCM user guide contains a Quick Start Guide with instructions for obtaining the code, compiling, and running test cases, which include five standard test cases and two additional FV3 replay cases (refer to section 5.2 in the CCPP-SCM user guide for more details). Moreover, the CCPP-SCM supports a precompiled version in a docker container, allowing it to be easily executed on NOAA's cloud computing platforms without any issues (see section 2.5 in the CCPP-SCM user guide for more details). - -.. note:: - SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which physics suite definition file (:term:`SDF`) is chosen when turning this option on. Among the supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. - -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. - -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 App, the UPP converts model output data from the model's native :term:`netCDF` format 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). - -.. _MetplusComponent: - -METplus Verification Suite -============================= - -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. - -The METplus verification framework 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) `__. - -METplus *installation* is not included as part of the build process for the most recent release of the SRW App. However, METplus is preinstalled on many `Level 1 & 2 `__ systems; existing builds can be viewed `here `__. - -METplus can be installed on other systems individually or as part of :term:`HPC-Stack` installation. Users on systems without a previous installation of METplus can follow the `MET Installation Guide `__ and `METplus Installation Guide `__ 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. - -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. - -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 (which include conventional point-based surface and upper-air data) in `prepBUFR format `__ 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 (:term:`EMC`), and it is open to community contributions. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. - -AQM Utilities -=============== - -https://github.com/NOAA-EMC/AQM-utils - -NOAA Emission and Exchange Unified System (NEXUS) -=================================================== - -https://github.com/noaa-oar-arl/NEXUS - -Gridpoint Statistical Interpolation (GSI) -============================================ - -https://github.com/NOAA-EMC/GSI - -RRFS Utilities -================ - -https://github.com/NOAA-GSL/rrfs_utl - -Unified Workflow Tools -======================== - -https://github.com/ufs-community/workflow-tools - - -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. This build system collects the components necessary for running the end-to-end SRW Application, including the UFS Weather Model and the pre- and post-processing software. Additional libraries necessary for the application (e.g., :term:`NCEPLIBS-external` and :term:`NCEPLIBS`) are not included in the SRW Application build system but are available pre-built on pre-configured platforms. On other systems, they can be installed via the HPC-Stack (see :doc:`HPC-Stack Documentation `). There is a small set of system libraries and utilities that are assumed to be present on the target computer: the CMake build software; a Fortran, C, and C++ compiler; and an :term:`MPI` library. - -Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see :numref:`Chapter %s ` or the `Rocoto documentation `__ for more information on Rocoto and workflow management). 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 SRW Application allows users to configure various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, integration time step, and the physics suite used for the simulation. It also allows for configuration of other elements of the workflow; for example, users can choose whether to run some or all of the pre-processing, forecast model, and post-processing steps. More information on how to configure the workflow is available in :numref:`Section %s `. - -An optional Python plotting task is also included to create basic visualizations of the model output. The task outputs graphics in PNG format for several standard meteorological variables on the pre-defined :term:`CONUS` domain. A difference plotting option is also included to visually compare two runs for the same domain and resolution. These plots may be used to perform a visual check to verify that the application is producing reasonable results. Configuration instructions are provided in :numref:`Section %s `. - -The SRW Application has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g., Hera, Orion, Jet); the National Center for Atmospheric Research (:term:`NCAR`) Cheyenne system; cloud environment, 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 (Level 3), and build-only (Level 4) platforms. - -Preconfigured (Level 1) systems already have the required external libraries available in a central location (via :term:`HPC-Stack` or :term:`spack-stack`). 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. - -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. Users will need to install the required libraries as part of the :ref:`SRW Application build ` process. Applications and models are expected to build and run once the required libraries are built. Release testing is conducted on these systems to ensure that the SRW App runs smoothly there. - -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. 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. - -On all platforms, the SRW App can be :ref:`run within a container ` that includes the prerequisite software. - -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 `__. - diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst deleted file mode 100644 index fc7b5e1391..0000000000 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ /dev/null @@ -1,1248 +0,0 @@ -.. _ConfigWorkflow: - -================================================================================================ -Workflow Parameters: Configuring the Workflow in ``config.yaml`` and ``config_defaults.yaml`` -================================================================================================ -To create the experiment directory and workflow when running the SRW Application, the user must create an experiment configuration file (usually named ``config.yaml``). This file contains experiment-specific information, such as forecast dates, grid and physics suite choices, data directories, and other relevant settings. To help the user, two sample configuration files have been included in the ``ush`` directory: ``config.community.yaml`` and ``config.nco.yaml``. The first is for running experiments in *community* mode (``RUN_ENVIR`` set to "community"), and the second is for running experiments in *nco* mode (``RUN_ENVIR`` set to "nco"). The content of these files can be copied into ``config.yaml`` and used as the starting point from which to generate a variety of experiment configurations for the SRW App. Note that for this release, only *community* mode is supported. - -There is an extensive list of experiment parameters that a user can set when configuring the experiment. Not all of these parameters need to be set explicitly by the user in ``config.yaml``. If a user does not define a variable in the ``config.yaml`` script, its value in ``config_defaults.yaml`` will be used, or the value will be reset depending on other parameters, such as the platform (``MACHINE``) selected for the experiment. - -.. note:: - The ``config_defaults.yaml`` file contains the full list of experiment parameters that a user may set in ``config.yaml``. The user cannot set parameters in ``config.yaml`` that are not initialized in ``config_defaults.yaml``, with the notable exception in the ``rocoto`` section, described in :numref:`Chapter %s `. - -The following is a list of the parameters in the ``config_defaults.yaml`` file. For each parameter, the default value and a brief description is provided. - -.. _user: - -USER Configuration Parameters -================================= - -If non-default parameters are selected for the variables in this section, they should be added to the ``user:`` section of the ``config.yaml`` file. - -``RUN_ENVIR``: (Default: "nco") - This variable determines the workflow mode. The user can choose between two options: "nco" and "community". The "nco" mode uses a directory structure that mimics what is used in operations at NOAA/NCEP Central Operations (NCO) and at the NOAA/NCEP/Environmental Modeling Center (EMC), which works with NCO on pre-implementation testing. Specifics of the conventions used in "nco" mode can be found in the following `WCOSS Implementation Standards `__ document: - - | NCEP Central Operations - | WCOSS Implementation Standards - | January 19, 2022 - | Version 11.0.0 - - Setting ``RUN_ENVIR`` to "community" is recommended in most cases for users who are not planning to implement their code into operations at NCO. Valid values: ``"nco"`` | ``"community"`` - -``MACHINE``: (Default: "BIG_COMPUTER") - The machine (a.k.a. platform or system) on which the workflow will run. Currently supported platforms are listed on the `SRW App Wiki page `__. When running the SRW App on any ParellelWorks/NOAA Cloud system, use "NOAACLOUD" regardless of the underlying system (AWS, GCP, or Azure). Valid values: ``"HERA"`` | ``"ORION"`` | ``"JET"`` | ``"CHEYENNE"`` | ``"GAEA"`` | ``"NOAACLOUD"`` | ``"STAMPEDE"`` | ``"ODIN"`` | ``"MACOS"`` | ``"LINUX"`` | ``"SINGULARITY"`` | ``"WCOSS2"`` - - .. hint:: - Users who are NOT on a named, supported Level 1 or 2 platform will need to set the ``MACHINE`` variable to ``LINUX`` or ``MACOS``; to combine use of a Linux or MacOS platform with the Rocoto workflow manager, users will also need to set ``WORKFLOW_MANAGER: "rocoto"`` in the ``platform:`` section of ``config.yaml``. This combination will assume a Slurm batch manager when generating the XML. - -``MACHINE_FILE``: (Default: "") - Path to a configuration file with machine-specific settings. If none is provided, ``setup.py`` will attempt to set the path to a configuration file for a supported platform. - -``ACCOUNT``: (Default: "project_name") - The account under which users submit jobs to the queue on the specified ``MACHINE``. To determine an appropriate ``ACCOUNT`` field for `Level 1 `__ systems, users may run the ``groups`` command, which will return a list of projects that the user has permissions for. Not all of the listed projects/groups have an HPC allocation, but those that do are potentially valid account names. On some systems, the ``saccount_params`` command will display additional account details. - -.. _PlatformConfig: - -PLATFORM Configuration Parameters -===================================== - -If non-default parameters are selected for the variables in this section, they should be added to the ``platform:`` section of the ``config.yaml`` file. - -``WORKFLOW_MANAGER``: (Default: "none") - The workflow manager to use (e.g., "rocoto"). This is set to "none" by default, but if the machine name is set to a platform that supports Rocoto, this will be overwritten and set to "rocoto." If set explicitly to "rocoto" along with the use of the ``MACHINE: "LINUX"`` target, the configuration layer assumes a Slurm batch manager when generating the XML. Valid values: ``"rocoto"`` | ``"none"`` - -``NCORES_PER_NODE``: (Default: "") - The number of cores available per node on the compute platform. Set for supported platforms in ``setup.py``, but it is now also configurable for all platforms. - -``BUILD_MOD_FN``: (Default: "") - Name of an alternative build module file to use if running on an unsupported platform. It is set automatically for supported machines. - -``WFLOW_MOD_FN``: (Default: "") - Name of an alternative workflow module file to use if running on an unsupported platform. It is set automatically for supported machines. - -``BUILD_VER_FN``: (Default: "") - File name containing the version of the modules used for building the app. Currently, WCOSS2 only uses this file. - -``RUN_VER_FN``: (Default: "") - File name containing the version of the modules used for running the app. Currently, WCOSS2 only uses this file. - -.. _sched: - -``SCHED``: (Default: "") - The job scheduler to use (e.g., Slurm) on the specified ``MACHINE``. Leaving this an empty string allows the experiment generation script to set it automatically depending on the machine the workflow is running on. Valid values: ``"slurm"`` | ``"pbspro"`` | ``"lsf"`` | ``"lsfcray"`` | ``"none"`` - -``SCHED_NATIVE_CMD``: (Default: "") - Allows an extra parameter to be passed to the job scheduler (Slurm or PBSPRO) via XML Native command. - -``DOMAIN_PREGEN_BASEDIR``: (Default: "") - For use in NCO mode only (``RUN_ENVIR: "nco"``). The base directory containing pregenerated grid, orography, and surface climatology files. This is an alternative for setting ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` individually. For the pregenerated grid specified by ``PREDEF_GRID_NAME``, these "fixed" files are located in: - - .. code-block:: console - - ${DOMAIN_PREGEN_BASEDIR}/${PREDEF_GRID_NAME} - - The workflow scripts will create a symlink in the experiment directory that will point to a subdirectory (having the same name as the experiment grid) under this directory. This variable should be set to a null string in ``config_defaults.yaml``, but it can be changed in the user-specified workflow configuration file set by ``EXPT_CONFIG_FN`` (usually ``config.yaml``). - -``PRE_TASK_CMDS``: (Default: "") - Pre-task commands such as ``ulimit`` needed by tasks. For example: ``'{ ulimit -s unlimited; ulimit -a; }'`` - -Machine-Dependent Parameters -------------------------------- -These parameters vary depending on machine. On `Level 1 and 2 `__ systems, the appropriate values for each machine can be viewed in the ``ush/machine/.sh`` scripts. To specify a value other than the default, add these variables and the desired value in the ``config.yaml`` file so that they override the ``config_defaults.yaml`` and machine default values. - -``PARTITION_DEFAULT``: (Default: "") - This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). This is the default partition to which Slurm submits workflow tasks. When a variable that designates the partition (e.g., ``PARTITION_HPSS``, ``PARTITION_FCST``; see below) is **not** specified, the task will be submitted to the default partition indicated in the ``PARTITION_DEFAULT`` variable. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"hera"`` | ``"normal"`` | ``"orion"`` | ``"sjet"`` | ``"vjet"`` | ``"kjet"`` | ``"xjet"`` | ``"workq"`` - -``QUEUE_DEFAULT``: (Default: "") - The default queue or QOS to which workflow tasks are submitted (QOS is Slurm's term for queue; it stands for "Quality of Service"). If the task's ``QUEUE_HPSS`` or ``QUEUE_FCST`` parameters (see below) are not specified, the task will be submitted to the queue indicated by this variable. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` - -``PARTITION_HPSS``: (Default: "") - This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). Tasks that get or create links to external model files are submitted to the partition specified in this variable. These links are needed to generate initial conditions (:term:`ICs`) and lateral boundary conditions (:term:`LBCs`) for the experiment. If this variable is not set or is set to an empty string, it will be (re)set to the ``PARTITION_DEFAULT`` value (if set) or to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"normal"`` | ``"service"`` | ``"workq"`` - -``QUEUE_HPSS``: (Default: "") - Tasks that get or create links to external model files are submitted to this queue, or QOS (QOS is Slurm's term for queue; it stands for "Quality of Service"). These links are needed to generate initial conditions (:term:`ICs`) and lateral boundary conditions (:term:`LBCs`) for the experiment. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev_transfer"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` - -``PARTITION_FCST``: (Default: "") - This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). The task that runs forecasts is submitted to this partition. If this variable is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"hera"`` | ``"normal"`` | ``"orion"`` | ``"sjet"`` | ``"vjet"`` | ``"kjet"`` | ``"xjet"`` | ``"workq"`` - -``QUEUE_FCST``: (Default: "") - The task that runs a forecast is submitted to this queue, or QOS (QOS is Slurm's term for queue; it stands for "Quality of Service"). If this variable is not set or set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` - -Parameters for Running Without a Workflow Manager ------------------------------------------------------ -These settings define the run commands for the platform. - -``RUN_CMD_UTILS``: (Default: "mpirun -np 1") - 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``). 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. - -``RUN_CMD_POST``: (Default: "mpirun -np 1") - The run command for post-processing (via the :term:`UPP`). Can be left blank for smaller domains, in which case UPP will run without :term:`MPI`. - - -METplus Parameters ----------------------- - -:ref:`METplus ` is a scientific verification framework that spans a wide range of temporal and spatial scales. Many of the METplus parameters are described below, but additional documentation for the METplus components is available on the `METplus website `__. - -``MODEL``: (Default: "") - A descriptive name of the user's choice for the model being verified. - -``MET_INSTALL_DIR``: (Default: "") - Path to top-level directory of MET installation. - -``METPLUS_PATH``: (Default: "") - Path to top-level directory of METplus installation. - -``MET_BIN_EXEC``: (Default: "") - Name of subdirectory where METplus executables are installed. - -.. _METParamNote: - -.. note:: - Where a date field is required: - * ``YYYY`` refers to the 4-digit valid year - * ``MM`` refers to the 2-digit valid month - * ``DD`` refers to the 2-digit valid day of the month - * ``HH`` refers to the 2-digit valid hour of the day - * ``mm`` refers to the 2-digit valid minutes of the hour - * ``SS`` refers to the two-digit valid seconds of the hour - -``CCPA_OBS_DIR``: (Default: "") - 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_CCPA`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify.yaml``). - - METplus configuration files require the use of a 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 (``scripts/exregional_get_obs_ccpa.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_obs_ccpa.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 :term:`HPSS` (if the user has access) via the ``GET_OBS_MRMS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify.yaml``). 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 that retrieves 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: ``scripts/exregional_get_obs_mrms.sh``. This script calls the script used to identify the MRMS file closest to the valid time: ``ush/mrms_pull_topofhour.py``. - -``NDAS_OBS_DIR``: (Default: "") - User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_NDAS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. Please note, this path must be defined as ``//ndas/proc``. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. - - METplus configuration files require the use of predetermined file names. Therefore, if the NDAS files are user-provided, they need to follow the anticipated naming structure: ``prepbufr.ndas.{YYYYMMDDHH}``, where YYYYMMDDHH is as described in the note :ref:`above `. The script to pull the NDAS data from the NOAA HPSS (``scripts/exregional_get_obs_ndas.sh``) has an example of how to rename the NDAS data into a more intuitive format with the valid time listed in the file name. - -Test Directories ----------------------- - -These directories are used only by the ``run_WE2E_tests.py`` script, so they are not used unless the user runs a Workflow End-to-End (WE2E) test (see :numref:`Chapter %s `). Their function corresponds to the same variables without the ``TEST_`` prefix. Users typically should not modify these variables. For any alterations, the logic in the ``run_WE2E_tests.py`` script would need to be adjusted accordingly. - -``TEST_EXTRN_MDL_SOURCE_BASEDIR``: (Default: "") - This parameter allows testing of user-staged files in a known location on a given platform. This path contains a limited dataset and likely will not be useful for most user experiments. - -``TEST_PREGEN_BASEDIR``: (Default: "") - Similar to ``DOMAIN_PREGEN_BASEDIR``, this variable sets the base directory containing pregenerated grid, orography, and surface climatology files for WE2E tests. This is an alternative for setting ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` individually. - -``TEST_ALT_EXTRN_MDL_SYSBASEDIR_ICS``: (Default: "") - This parameter is used to test the mechanism that allows users to point to a data stream on disk. It sets up a sandbox location that mimics the stream in a more controlled way and tests the ability to access :term:`ICS`. - -``TEST_ALT_EXTRN_MDL_SYSBASEDIR_LBCS``: (Default: "") - This parameter is used to test the mechanism that allows users to point to a data stream on disk. It sets up a sandbox location that mimics the stream in a more controlled way and tests the ability to access :term:`LBCS`. - - -.. _workflow: - -WORKFLOW Configuration Parameters -===================================== - -If non-default parameters are selected for the variables in this section, they should be added to the ``workflow:`` section of the ``config.yaml`` file. - -.. _Cron: - -Cron-Associated Parameters ------------------------------- - -Cron is a job scheduler accessed through the command-line on UNIX-like operating systems. It is useful for automating tasks such as the ``rocotorun`` command, which launches each workflow task in the SRW App. Cron periodically checks a cron table (aka crontab) to see if any tasks are are ready to execute. If so, it runs them. - -``USE_CRON_TO_RELAUNCH``: (Default: false) - Flag that determines whether or not a line is added to the user's cron table, which calls the experiment launch script every ``CRON_RELAUNCH_INTVL_MNTS`` minutes. Valid values: ``True`` | ``False`` - -``CRON_RELAUNCH_INTVL_MNTS``: (Default: 3) - The interval (in minutes) between successive calls of the experiment launch script by a cron job to (re)launch the experiment (so that the workflow for the experiment kicks off where it left off). This is used only if ``USE_CRON_TO_RELAUNCH`` is set to true. - -.. _DirParams: - -Directory Parameters ------------------------ - -``EXPT_BASEDIR``: (Default: "") - The full path to the base directory in which the experiment directory (``EXPT_SUBDIR``) will be created. If this is not specified or if it is set to an empty string, it will default to ``${HOMEdir}/../expt_dirs``, where ``${HOMEdir}`` contains the full path to the ``ufs-srweather-app`` directory. If set to a relative path, the provided path will be appended to the default value ``${HOMEdir}/../expt_dirs``. For example, if ``EXPT_BASEDIR=some/relative/path`` (i.e. a path that does not begin with ``/``), the value of ``EXPT_BASEDIR`` used by the workflow will be ``EXPT_BASEDIR=${HOMEdir}/../expt_dirs/some/relative/path``. - -``EXPT_SUBDIR``: (Default: "") - The user-designated name of the experiment directory (*not* its full path). The full path to the experiment directory, which will be contained in the variable ``EXPTDIR``, will be: - - .. code-block:: console - - EXPTDIR="${EXPT_BASEDIR}/${EXPT_SUBDIR}" - - This parameter cannot be left as a null string. It must be set to a non-null value in the user-defined experiment configuration file (i.e., ``config.yaml``). - -``EXEC_SUBDIR``: (Default: "exec") - The name of the subdirectory of ``ufs-srweather-app`` where executables are installed. - -Pre-Processing File Separator Parameters --------------------------------------------- - -``DOT_OR_USCORE``: (Default: "_") - This variable sets the separator character(s) to use in the names of the grid, mosaic, and orography fixed files. Ideally, the same separator should be used in the names of these fixed files as in the surface climatology fixed files. Valid values: ``"_"`` | ``"."`` - - -Set File Name Parameters ----------------------------- - -``EXPT_CONFIG_FN``: (Default: "config.yaml") - Name of the user-specified configuration file for the forecast experiment. - -``CONSTANTS_FN``: (Default: "constants.yaml") - Name of the file containing definitions of various mathematical, physical, and SRW App contants. - -``RGNL_GRID_NML_FN``: (Default: "regional_grid.nml") - Name of the file containing namelist settings for the code that generates an "ESGgrid" regional grid. - -``FV3_NML_BASE_SUITE_FN``: (Default: "input.nml.FV3") - Name of the Fortran file containing the forecast model's base suite namelist (i.e., the portion of the namelist that is common to all physics suites). - -``FV3_NML_YAML_CONFIG_FN``: (Default: "FV3.input.yml") - Name of YAML configuration file containing the forecast model's namelist settings for various physics suites. - -``FV3_NML_BASE_ENS_FN``: (Default: "input.nml.base_ens") - Name of the Fortran file containing the forecast model's base ensemble namelist (i.e., the original namelist file from which each of the ensemble members' namelist files is generated). - -``FV3_EXEC_FN``: (Default: "ufs_model") - Name to use for the forecast model executable. - -``DIAG_TABLE_TMPL_FN``: (Default: "") - Name of a template file that specifies the output fields of the forecast model. The selected physics suite is appended to this file name in ``setup.py``, taking the form ``{DIAG_TABLE_TMPL_FN}.{CCPP_PHYS_SUITE}``. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``diag_table.{CCPP_PHYS_SUITE}``), and users should **not** specify a value for ``DIAG_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the names of the ``diag_table`` options in the ``ufs-srweather-app/parm`` directory. - -``FIELD_TABLE_TMPL_FN``: (Default: "") - Name of a template file that specifies the :term:`tracers ` that the forecast model will read in from the :term:`IC/LBC ` files. The selected physics suite is appended to this file name in ``setup.py``, taking the form ``{FIELD_TABLE_TMPL_FN}.{CCPP_PHYS_SUITE}``. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``field_table.{CCPP_PHYS_SUITE}``), and users should **not** specify a different value for ``FIELD_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the names of the ``field_table`` options in the ``ufs-srweather-app/parm`` directory. - -``DATA_TABLE_TMPL_FN``: (Default: "") - Name of a template file that contains the data table read in by the forecast model. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``data_table``), and users should **not** specify a different value for ``DATA_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``data_table`` in the ``ufs-srweather-app/parm`` directory. - -``MODEL_CONFIG_TMPL_FN``: (Default: "") - Name of a template file that contains settings and configurations for the :term:`NUOPC`/:term:`ESMF` main component. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``model_configure``), and users should **not** specify a different value for ``MODEL_CONFIG_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``model_configure`` in the ``ufs-srweather-app/parm`` directory. - -``NEMS_CONFIG_TMPL_FN``: (Default: "") - Name of a template file that contains information about the various :term:`NEMS` components and their run sequence. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``nems.configure``), and users should **not** specify a different value for ``NEMS_CONFIG_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``nems.configure`` in the ``ufs-srweather-app/parm`` directory. - -``FCST_MODEL``: (Default: "ufs-weather-model") - Name of forecast model. Valid values: ``"ufs-weather-model"`` | ``"fv3gfs_aqm"`` - -``WFLOW_XML_FN``: (Default: "FV3LAM_wflow.xml") - Name of the Rocoto workflow XML file that the experiment generation script creates. This file defines the workflow for the experiment. - -``GLOBAL_VAR_DEFNS_FN``: (Default: "var_defns.sh") - Name of the file (a shell script) containing definitions of the primary and secondary experiment variables (parameters). This file is sourced by many scripts (e.g., the J-job scripts corresponding to each workflow task) in order to make all the experiment variables available in those scripts. The primary variables are defined in the default configuration script (``config_defaults.yaml``) and in ``config.yaml``. The secondary experiment variables are generated by the experiment generation script. - -``EXTRN_MDL_VAR_DEFNS_FN``: (Default: "extrn_mdl_var_defns") - Name of the file (a shell script) containing the definitions of variables associated with the external model from which :term:`ICs` or :term:`LBCs` are generated. This file is created by the ``GET_EXTRN_*`` task because the values of the variables it contains are not known before this task runs. The file is then sourced by the ``MAKE_ICS`` and ``MAKE_LBCS`` tasks. - -``WFLOW_LAUNCH_SCRIPT_FN``: (Default: "launch_FV3LAM_wflow.sh") - Name of the script that can be used to (re)launch the experiment's Rocoto workflow. - -``WFLOW_LAUNCH_LOG_FN``: (Default: "log.launch_FV3LAM_wflow") - Name of the log file that contains the output from successive calls to the workflow launch script (``WFLOW_LAUNCH_SCRIPT_FN``). - -.. _CCPP_Params: - -CCPP Parameter ------------------- - -``CCPP_PHYS_SUITE``: (Default: "FV3_GFS_v16") - This parameter indicates which :term:`CCPP` (Common Community Physics Package) physics suite to use for the forecast(s). The choice of physics suite determines the forecast model's namelist file, the diagnostics table file, the field table file, and the XML physics suite definition file, which are staged in the experiment directory or the :term:`cycle` directories under it. - - .. note:: - For information on *stochastic physics* parameters, see :numref:`Section %s `. - - **Current supported settings for the CCPP parameter are:** - - | ``"FV3_GFS_v16"`` - | ``"FV3_RRFS_v1beta"`` - | ``"FV3_HRRR"`` - | ``"FV3_WoFS_v0"`` - | ``"FV3_RAP"`` - - Other valid values can be found in the ``ush/valid_param_vals.yaml`` file, but users can not expect full support for these schemes. - - -.. _GridGen: - -Grid Generation Parameters ------------------------------- - -``GRID_GEN_METHOD``: (Default: "") - This variable specifies which method to use to generate a regional grid in the horizontal plane. The values that it can take on are: - - * ``"ESGgrid"``: The "ESGgrid" method will generate a regional version of the Extended Schmidt Gnomonic (ESG) grid using the map projection developed by Jim Purser of EMC (:cite:t:`Purser_2020`). "ESGgrid" is the preferred grid option. - - * ``"GFDLgrid"``: The "GFDLgrid" method first generates a "parent" global cubed-sphere grid. Then a portion from tile 6 of the global grid is used as the regional grid. This regional grid is referred to in the grid generation scripts as "tile 7," even though it does not correspond to a complete tile. The forecast is run only on the regional grid (i.e., on tile 7, not on tiles 1 through 6). Note that the "GFDLgrid" method is the legacy grid generation method. It is not supported in *all* predefined domains. - -.. attention:: - - If the experiment uses a **predefined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to the name of a valid predefined grid), then ``GRID_GEN_METHOD`` will be reset to the value of ``GRID_GEN_METHOD`` for that grid. This will happen regardless of whether ``GRID_GEN_METHOD`` is assigned a value in the experiment configuration file; any value assigned will be overwritten. - -.. note:: - - If the experiment uses a **user-defined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to a null string), then ``GRID_GEN_METHOD`` must be set in the experiment configuration file. Otherwise, the experiment generation will fail because the generation scripts check to ensure that the grid name is set to a non-empty string before creating the experiment directory. - -Forecast Parameters ----------------------- -``DATE_FIRST_CYCL``: (Default: "YYYYMMDDHH") - Starting date of the first forecast in the set of forecasts to run. Format is "YYYYMMDDHH". - -``DATE_LAST_CYCL``: (Default: "YYYYMMDDHH") - Starting date of the last forecast in the set of forecasts to run. Format is "YYYYMMDDHH". - -``INCR_CYCL_FREQ``: (Default: 24) - Increment in hours for Rocoto cycle frequency. The default is 24, which means cycl_freq=24:00:00. - -``FCST_LEN_HRS``: (Default: 24) - The length of each forecast, in integer hours. - -Pre-Existing Directory Parameter ------------------------------------- -``PREEXISTING_DIR_METHOD``: (Default: "delete") - This variable determines how to deal with pre-existing directories (resulting from previous calls to the experiment generation script using the same experiment name [``EXPT_SUBDIR``] as the current experiment). This variable must be set to one of three valid values: ``"delete"``, ``"rename"``, or ``"quit"``. The behavior for each of these values is as follows: - - * **"delete":** The preexisting directory is deleted and a new directory (having the same name as the original preexisting directory) is created. - - * **"rename":** The preexisting directory is renamed and a new directory (having the same name as the original pre-existing directory) is created. The new name of the preexisting directory consists of its original name and the suffix "_old###", where ``###`` is a 3-digit integer chosen to make the new name unique. - - * **"quit":** The preexisting directory is left unchanged, but execution of the currently running script is terminated. In this case, the preexisting directory must be dealt with manually before rerunning the script. - -Verbose Parameter ---------------------- -``VERBOSE``: (Default: true) - Flag that determines whether the experiment generation and workflow task scripts print out extra informational messages. Valid values: ``True`` | ``False`` - -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 be reset to true if it isn't already. Valid values: ``True`` | ``False`` - -Compiler ------------ - -``COMPILER``: (Default: "intel") - Type of compiler invoked during the build step. Currently, this must be set manually; it is not inherited from the build system in the ``ufs-srweather-app`` directory. Valid values: ``"intel"`` | ``"gnu"`` - -Verification Parameters ---------------------------- - -``GET_OBS``: (Default: "get_obs") - Set the name of the Rocoto workflow task used to load proper module files for ``GET_OBS_*`` tasks. Users typically do not need to change this value. - - -.. _NCOModeParms: - -NCO-Specific Variables -========================= - -A standard set of environment variables has been established for *nco* mode to simplify the production workflow and improve the troubleshooting process for operational and preoperational models. These variables are only used in *nco* mode (i.e., when ``RUN_ENVIR: "nco"``). When non-default parameters are selected for the variables in this section, they should be added to the ``nco:`` section of the ``config.yaml`` file. - -.. note:: - Only *community* mode is fully supported for this release. *nco* mode is used by those at the Environmental Modeling Center (EMC) and Global Systems Laboratory (GSL) who are working on pre-implementation operational testing. Other users should run the SRW App in *community* mode. - -``envir, NET, model_ver, RUN``: - Standard environment variables defined in the NCEP Central Operations WCOSS Implementation Standards document. These variables are used in forming the path to various directories containing input, output, and workflow files. The variables are defined in the `WCOSS Implementation Standards `__ document (pp. 4-5) as follows: - - ``envir``: (Default: "para") - Set to "test" during the initial testing phase, "para" when running in parallel (on a schedule), and "prod" in production. - - ``NET``: (Default: "rrfs") - Model name (first level of ``com`` directory structure) - - ``model_ver``: (Default: "v1.0.0") - Version number of package in three digits (second level of ``com`` directory) - - ``RUN``: (Default: "rrfs") - Name of model run (third level of ``com`` directory structure). In general, same as ``$NET``. - -``OPSROOT``: (Default: "") - The operations root directory in *nco* mode. - -.. _make-grid: - -MAKE_GRID Configuration Parameters -====================================== - -Non-default parameters for the ``make_grid`` task are set in the ``task_make_grid:`` section of the ``config.yaml`` file. - -Basic Task Parameters --------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. Typically, users do not need to adjust the default values. - - ``GRID_DIR``: (Default: "") - The directory containing pre-generated grid files when the ``MAKE_GRID`` task is not meant to run. - -.. _ESGgrid: - -ESGgrid Settings -------------------- - -The following parameters must be set if using the "ESGgrid" method to generate a regional grid (i.e., when ``GRID_GEN_METHOD: "ESGgrid"``, see :numref:`Section %s `). If a different ``GRID_GEN_METHOD`` is used, these parameters will be ignored. When using a predefined grid with ``GRID_GEN_METHOD: "ESGgrid"``, the values in this section will be set automatically to the assigned values for that grid. - -``ESGgrid_LON_CTR``: (Default: "") - The longitude of the center of the grid (in degrees). - -``ESGgrid_LAT_CTR``: (Default: "") - The latitude of the center of the grid (in degrees). - -``ESGgrid_DELX``: (Default: "") - The cell size in the zonal direction of the regional grid (in meters). - -``ESGgrid_DELY``: (Default: "") - The cell size in the meridional direction of the regional grid (in meters). - -``ESGgrid_NX``: (Default: "") - The number of cells in the zonal direction on the regional grid. - -``ESGgrid_NY``: (Default: "") - The number of cells in the meridional direction on the regional grid. - -``ESGgrid_PAZI``: (Default: "") - The rotational parameter for the "ESGgrid" (in degrees). - -``ESGgrid_WIDE_HALO_WIDTH``: (Default: "") - The width (in number of grid cells) of the :term:`halo` to add around the regional grid before shaving the halo down to the width(s) expected by the forecast model. The user need not specify this variable since it is set automatically in ``set_gridparams_ESGgrid.py`` - -.. _WideHalo: - -.. note:: - A :term:`halo` is the strip of cells surrounding the regional grid; the halo is used to feed in the lateral boundary conditions to the grid. The forecast model requires **grid** files containing 3-cell- and 4-cell-wide halos and **orography** files with 0-cell- and 3-cell-wide halos. In order to generate grid and orography files with appropriately-sized halos, the grid and orography tasks create preliminary files with halos around the regional domain of width ``ESGgrid_WIDE_HALO_WIDTH`` cells. The files are then read in and "shaved" down to obtain grid files with 3-cell-wide and 4-cell-wide halos and orography files with 0-cell-wide and 3-cell-wide halos. The original halo that gets shaved down is referred to as the "wide" halo because it is wider than the 0-cell-wide, 3-cell-wide, and 4-cell-wide halos that users eventually end up with. Note that the grid and orography files with the wide halo are only needed as intermediates in generating the files with 0-cell-, 3-cell-, and 4-cell-wide halos; they are not needed by the forecast model. - -GFDLgrid Settings ---------------------- - -The following parameters must be set if using the "GFDLgrid" method to generate a regional grid (i.e., when ``GRID_GEN_METHOD: "GFDLgrid"``, see :numref:`Section %s `). If a different ``GRID_GEN_METHOD`` is used, these parameters will be ignored. When using a predefined grid with ``GRID_GEN_METHOD: "GFDLgrid"``, the values in this section will be set automatically to the assigned values for that grid. - -Note that the regional grid is defined with respect to a "parent" global cubed-sphere grid. Thus, all the parameters for a global cubed-sphere grid must be specified even though the model equations are integrated only on the regional grid. Tile 6 has arbitrarily been chosen as the tile to use to orient the global parent grid on the sphere (Earth). For convenience, the regional grid is denoted as "tile 7" even though it is embedded within tile 6 (i.e., it doesn't extend beyond the boundary of tile 6). Its exact location within tile 6 is determined by specifying the starting and ending i- and j-indices of the regional grid on tile 6, where ``i`` is the grid index in the x direction and ``j`` is the grid index in the y direction. All of this information is set in the variables below. - -``GFDLgrid_LON_T6_CTR``: (Default: "") - Longitude of the center of tile 6 (in degrees). - -``GFDLgrid_LAT_T6_CTR``: (Default: "") - Latitude of the center of tile 6 (in degrees). - -``GFDLgrid_NUM_CELLS``: (Default: "") - Number of grid cells in either of the two horizontal directions (x and y) on each of the six tiles of the parent global cubed-sphere grid. Valid values: ``48`` | ``96`` | ``192`` | ``384`` | ``768`` | ``1152`` | ``3072`` - - To give an idea of what these values translate to in terms of grid cell size in kilometers, we list below the approximate grid cell size on a uniform global grid having the specified value of ``GFDLgrid_NUM_CELLS``, where by "uniform" we mean with Schmidt stretch factor ``GFDLgrid_STRETCH_FAC: "1"`` (although in regional applications ``GFDLgrid_STRETCH_FAC`` will typically be set to a value greater than ``"1"`` to obtain a smaller grid size on tile 6): - - +---------------------+--------------------+ - | GFDLgrid_NUM_CELLS | Typical Cell Size | - +=====================+====================+ - | 48 | 200 km | - +---------------------+--------------------+ - | 96 | 100 km | - +---------------------+--------------------+ - | 192 | 50 km | - +---------------------+--------------------+ - | 384 | 25 km | - +---------------------+--------------------+ - | 768 | 13 km | - +---------------------+--------------------+ - | 1152 | 8.5 km | - +---------------------+--------------------+ - | 3072 | 3.2 km | - +---------------------+--------------------+ - - Note that these are only typical cell sizes. The actual cell size on the global grid tiles varies somewhat as we move across a tile and is also dependent on ``GFDLgrid_STRETCH_FAC``, which modifies the shape and size of the tile. - -``GFDLgrid_STRETCH_FAC``: (Default: "") - Stretching factor used in the Schmidt transformation applied to the parent cubed-sphere grid. Setting the Schmidt stretching factor to a value greater than 1 shrinks tile 6, while setting it to a value less than 1 (but still greater than 0) expands it. The remaining 5 tiles change shape as necessary to maintain global coverage of the grid. - -``GFDLgrid_REFINE_RATIO``: (Default: "") - Cell refinement ratio for the regional grid. It refers to the number of cells in either the x or y direction on the regional grid (tile 7) that abut one cell on its parent tile (tile 6). - -``GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G``: (Default: "") - i-index on tile 6 at which the regional grid (tile 7) starts. - -``GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G``: (Default: "") - i-index on tile 6 at which the regional grid (tile 7) ends. - -``GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G``: (Default: "") - j-index on tile 6 at which the regional grid (tile 7) starts. - -``GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G``: (Default: "") - j-index on tile 6 at which the regional grid (tile 7) ends. - -``GFDLgrid_USE_NUM_CELLS_IN_FILENAMES``: (Default: "") - Flag that determines the file naming convention to use for grid, orography, and surface climatology files (or, if using pregenerated files, the naming convention that was used to name these files). These files usually start with the string ``"C${RES}_"``, where ``RES`` is an integer. In the global forecast model, ``RES`` is the number of points in each of the two horizontal directions (x and y) on each tile of the global grid (defined here as ``GFDLgrid_NUM_CELLS``). If this flag is set to true, ``RES`` will be set to ``GFDLgrid_NUM_CELLS`` just as in the global forecast model. If it is set to false, we calculate (in the grid generation task) an "equivalent global uniform cubed-sphere resolution" --- call it ``RES_EQUIV`` --- and then set ``RES`` equal to it. ``RES_EQUIV`` is the number of grid points in each of the x and y directions on each tile that a global UNIFORM (i.e., stretch factor of 1) cubed-sphere grid would need to have in order to have the same average grid size as the regional grid. This is a more useful indicator of the grid size because it takes into account the effects of ``GFDLgrid_NUM_CELLS``, ``GFDLgrid_STRETCH_FAC``, and ``GFDLgrid_REFINE_RATIO`` in determining the regional grid's typical grid size, whereas simply setting ``RES`` to ``GFDLgrid_NUM_CELLS`` doesn't take into account the effects of ``GFDLgrid_STRETCH_FAC`` and ``GFDLgrid_REFINE_RATIO`` on the regional grid's resolution. Nevertheless, some users still prefer to use ``GFDLgrid_NUM_CELLS`` in the file names, so we allow for that here by setting this flag to true. - -.. _make-orog: - -MAKE_OROG Configuration Parameters -===================================== - -Non-default parameters for the ``make_orog`` task are set in the ``task_make_orog:`` section of the ``config.yaml`` file. - -``KMP_AFFINITY_MAKE_OROG``: (Default: "disabled") - Intel Thread Affinity Interface for the ``make_orog`` task. See :ref:`this note ` for more information on thread affinity. Settings for the ``make_orog`` task is disabled because this task does not use parallelized code. - -``OMP_NUM_THREADS_MAKE_OROG``: (Default: 6) - The number of OpenMP threads to use for parallel regions. - - - -``OMP_STACKSIZE_MAKE_OROG``: (Default: "2048m") - Controls the size of the stack for threads created by the OpenMP implementation. - -``OROG_DIR``: (Default: "") - The directory containing pre-generated orography files to use when the ``MAKE_OROG`` task is not meant to run. - -.. _make-sfc-climo: - -MAKE_SFC_CLIMO Configuration Parameters -=========================================== - -Non-default parameters for the ``make_sfc_climo`` task are set in the ``task_make_sfc_climo:`` section of the ``config.yaml`` file. - -``KMP_AFFINITY_MAKE_SFC_CLIMO``: (Default: "scatter") - Intel Thread Affinity Interface for the ``make_sfc_climo`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_MAKE_SFC_CLIMO``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_MAKE_SFC_CLIMO``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -``SFC_CLIMO_DIR``: (Default: "") - The directory containing pre-generated surface climatology files to use when the ``MAKE_SFC_CLIMO`` task is not meant to run. - -.. _task_get_extrn_ics: - -GET_EXTRN_ICS Configuration Parameters -========================================= - -Non-default parameters for the ``get_extrn_ics`` task are set in the ``task_get_extrn_ics:`` section of the ``config.yaml`` file. - -.. _basic-get-extrn-ics: - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``EXTRN_MDL_NAME_ICS``: (Default: "FV3GFS") - The name of the external model that will provide fields from which initial condition (IC) files, surface files, and 0-th hour boundary condition files will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` - -``EXTRN_MDL_ICS_OFFSET_HRS``: (Default: 0) - Users may wish to start a forecast using forecast data from a previous cycle of an external model. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should start from a 6-hour forecast of the GFS, then ``EXTRN_MDL_ICS_OFFSET_HRS: "6"``. - -``FV3GFS_FILE_FMT_ICS``: (Default: "nemsio") - If using the FV3GFS model as the source of the :term:`ICs` (i.e., if ``EXTRN_MDL_NAME_ICS: "FV3GFS"``), this variable specifies the format of the model files to use when generating the ICs. Valid values: ``"nemsio"`` | ``"grib2"`` | ``"netcdf"`` - -File and Directory Parameters --------------------------------- - -``USE_USER_STAGED_EXTRN_FILES``: (Default: false) - Flag that determines whether the workflow will look for the external model files needed for generating :term:`ICs` in user-specified directories (rather than fetching them from mass storage like NOAA :term:`HPSS`). Valid values: ``True`` | ``False`` - -``EXTRN_MDL_SOURCE_BASEDIR_ICS``: (Default: "") - Directory containing external model files for generating ICs. If ``USE_USER_STAGED_EXTRN_FILES`` is set to true, the workflow looks within this directory for a subdirectory named "YYYYMMDDHH", which contains the external model files specified by the array ``EXTRN_MDL_FILES_ICS``. This "YYYYMMDDHH" subdirectory corresponds to the start date and cycle hour of the forecast (see :ref:`above `). These files will be used to generate the :term:`ICs` on the native FV3-LAM grid. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. - -``EXTRN_MDL_SYSBASEDIR_ICS``: (Default: '') - A known location of a real data stream on a given platform. This is typically a real-time data stream as on Hera, Jet, or WCOSS. External model files for generating :term:`ICs` on the native grid should be accessible via this data stream. The way the full path containing these files is constructed depends on the user-specified external model for ICs (defined above in :numref:`Section %s ` ``EXTRN_MDL_NAME_ICS``). - - .. note:: - This variable must be defined as a null string in ``config_defaults.yaml`` so that if it is specified by the user in the experiment configuration file (``config.yaml``), it remains set to those values, and if not, it gets set to machine-dependent values. - -``EXTRN_MDL_FILES_ICS``: (Default: "") - Array containing templates of the file names to search for in the ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` directory. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. A single template should be used for each model file type that is used. Users may use any of the Python-style templates allowed in the ``ush/retrieve_data.py`` script. To see the full list of supported templates, run that script with the ``-h`` option. - - For example, to set FV3GFS nemsio input files: - - .. code-block:: console - - EXTRN_MDL_FILES_ICS=[ gfs.t{hh}z.atmf{fcst_hr:03d}.nemsio , - gfs.t{hh}z.sfcf{fcst_hr:03d}.nemsio ] - - To set FV3GFS grib files: - - .. code-block:: console - - EXTRN_MDL_FILES_ICS=[ gfs.t{hh}z.pgrb2.0p25.f{fcst_hr:03d} ] - -``EXTRN_MDL_DATA_STORES``: (Default: "") - A list of data stores where the scripts should look to find external model data. The list is in priority order. If disk information is provided via ``USE_USER_STAGED_EXTRN_FILES`` or a known location on the platform, the disk location will receive highest priority. Valid values: ``disk`` | ``hpss`` | ``aws`` | ``nomads`` - -NOMADS Parameters ---------------------- - -Set parameters associated with NOMADS online data. - -``NOMADS``: (Default: false) - Flag controlling whether to use NOMADS online data. Valid values: ``True`` | ``False`` - -``NOMADS_file_type``: (Default: "nemsio") - Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"`` - -.. _task_get_extrn_lbcs: - -GET_EXTRN_LBCS Configuration Parameters -========================================== - -Non-default parameters for the ``get_extrn_lbcs`` task are set in the ``task_get_extrn_lbcs:`` section of the ``config.yaml`` file. - -.. _basic-get-extrn-lbcs: - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``EXTRN_MDL_NAME_LBCS``: (Default: "FV3GFS") - The name of the external model that will provide fields from which lateral boundary condition (LBC) files (except for the 0-th hour LBC file) will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` - -``LBC_SPEC_INTVL_HRS``: (Default: "6") - The interval (in integer hours) at which LBC files will be generated. This is also referred to as the *boundary update interval*. Note that the model selected in ``EXTRN_MDL_NAME_LBCS`` must have data available at a frequency greater than or equal to that implied by ``LBC_SPEC_INTVL_HRS``. For example, if ``LBC_SPEC_INTVL_HRS`` is set to "6", then the model must have data available at least every 6 hours. It is up to the user to ensure that this is the case. - -``EXTRN_MDL_LBCS_OFFSET_HRS``: (Default: "") - Users may wish to use lateral boundary conditions from a forecast that was started earlier than the start of the forecast configured here. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should use lateral boundary conditions from the GFS started 6 hours earlier, then ``EXTRN_MDL_LBCS_OFFSET_HRS: "6"``. Note: the default value is model-dependent and is set in ``ush/set_extrn_mdl_params.py``. - -``FV3GFS_FILE_FMT_LBCS``: (Default: "nemsio") - If using the FV3GFS model as the source of the :term:`LBCs` (i.e., if ``EXTRN_MDL_NAME_LBCS: "FV3GFS"``), this variable specifies the format of the model files to use when generating the LBCs. Valid values: ``"nemsio"`` | ``"grib2"`` | ``"netcdf"`` - - -File and Directory Parameters --------------------------------- - -``USE_USER_STAGED_EXTRN_FILES``: (Default: false) - Analogous to ``USE_USER_STAGED_EXTRN_FILES`` in :term:`ICs` but for :term:`LBCs`. Flag that determines whether the workflow will look for the external model files needed for generating :term:`LBCs` in user-specified directories (rather than fetching them from mass storage like NOAA :term:`HPSS`). Valid values: ``True`` | ``False`` - -``EXTRN_MDL_SOURCE_BASEDIR_LBCS``: (Default: "") - Analogous to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` but for :term:`LBCs` instead of :term:`ICs`. - Directory containing external model files for generating LBCs. If ``USE_USER_STAGED_EXTRN_FILES`` is set to true, the workflow looks within this directory for a subdirectory named "YYYYMMDDHH", which contains the external model files specified by the array ``EXTRN_MDL_FILES_LBCS``. This "YYYYMMDDHH" subdirectory corresponds to the start date and cycle hour of the forecast (see :ref:`above `). These files will be used to generate the :term:`LBCs` on the native FV3-LAM grid. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. - -``EXTRN_MDL_SYSBASEDIR_LBCS``: (Default: '') - Same as ``EXTRN_MDL_SYSBASEDIR_ICS`` but for :term:`LBCs`. A known location of a real data stream on a given platform. This is typically a real-time data stream as on Hera, Jet, or WCOSS. External model files for generating :term:`LBCs` on the native grid should be accessible via this data stream. The way the full path containing these files is constructed depends on the user-specified external model for LBCs (defined above in :numref:`Section %s ` ``EXTRN_MDL_NAME_LBCS`` above). - - .. note:: - This variable must be defined as a null string in ``config_defaults.yaml`` so that if it is specified by the user in the experiment configuration file (``config.yaml``), it remains set to those values, and if not, it gets set to machine-dependent values. - -``EXTRN_MDL_FILES_LBCS``: (Default: "") - Analogous to ``EXTRN_MDL_FILES_ICS`` but for :term:`LBCs` instead of :term:`ICs`. Array containing templates of the file names to search for in the ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` directory. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. A single template should be used for each model file type that is used. Users may use any of the Python-style templates allowed in the ``ush/retrieve_data.py`` script. To see the full list of supported templates, run that script with the ``-h`` option. For examples, see the ``EXTRN_MDL_FILES_ICS`` variable above. - -``EXTRN_MDL_DATA_STORES``: (Default: "") - Analogous to ``EXTRN_MDL_DATA_STORES`` in :term:`ICs` but for :term:`LBCs`. A list of data stores where the scripts should look to find external model data. The list is in priority order. If disk information is provided via ``USE_USER_STAGED_EXTRN_FILES`` or a known location on the platform, the disk location will receive highest priority. Valid values: ``disk`` | ``hpss`` | ``aws`` | ``nomads`` - -NOMADS Parameters ---------------------- - -Set parameters associated with NOMADS online data. Analogus to :term:`ICs` NOMADS Parameters. - -``NOMADS``: (Default: false) - Flag controlling whether to use NOMADS online data. - -``NOMADS_file_type``: (Default: "nemsio") - Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"`` - -MAKE_ICS Configuration Parameters -====================================== - -Non-default parameters for the ``make_ics`` task are set in the ``task_make_ics:`` section of the ``config.yaml`` file. - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``KMP_AFFINITY_MAKE_ICS``: (Default: "scatter") - Intel Thread Affinity Interface for the ``make_ics`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_MAKE_ICS``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_MAKE_ICS``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -FVCOM Parameter -------------------- -``USE_FVCOM``: (Default: false) - Flag that specifies whether to update surface conditions in FV3-:term:`LAM` with fields generated from the Finite Volume Community Ocean Model (:term:`FVCOM`). If set to true, lake/sea surface temperatures, ice surface temperatures, and ice placement will be overwritten using data provided by FVCOM. Setting ``USE_FVCOM`` to true causes the executable ``process_FVCOM.exe`` in the ``MAKE_ICS`` task to run. This, in turn, modifies the file ``sfc_data.nc`` generated by ``chgres_cube`` during the ``make_ics`` task. Note that the FVCOM data must already be interpolated to the desired FV3-LAM grid. Valid values: ``True`` | ``False`` - -``FVCOM_WCSTART``: (Default: "cold") - Define if this is a "warm" start or a "cold" start. Setting this to "warm" will read in ``sfc_data.nc`` generated in a RESTART directory. Setting this to "cold" will read in the ``sfc_data.nc`` generated from ``chgres_cube`` in the ``make_ics`` portion of the workflow. Valid values: ``"cold"`` | ``"COLD"`` | ``"warm"`` | ``"WARM"`` - -``FVCOM_DIR``: (Default: "") - User-defined directory where the ``fvcom.nc`` file containing :term:`FVCOM` data already interpolated to the FV3-LAM native grid is located. The file in this directory must be named ``fvcom.nc``. - -``FVCOM_FILE``: (Default: "fvcom.nc") - Name of the file located in ``FVCOM_DIR`` that has :term:`FVCOM` data interpolated to the FV3-LAM grid. This file will be copied later to a new location, and the name will be changed to ``fvcom.nc`` if a name other than ``fvcom.nc`` is selected. - - -MAKE_LBCS Configuration Parameters -====================================== - -Non-default parameters for the ``make_lbcs`` task are set in the ``task_make_lbcs:`` section of the ``config.yaml`` file. - -``KMP_AFFINITY_MAKE_LBCS``: (Default: "scatter") - Intel Thread Affinity Interface for the ``make_lbcs`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_MAKE_LBCS``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_MAKE_LBCS``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -.. _FcstConfigParams: - -FORECAST Configuration Parameters -===================================== - -Non-default parameters for the ``run_fcst`` task are set in the ``task_run_fcst:`` section of the ``config.yaml`` file. - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``KMP_AFFINITY_RUN_FCST``: (Default: "scatter") - Intel Thread Affinity Interface for the ``run_fcst`` task. - -.. _thread-affinity: - - .. note:: - - **Thread Affinity Interface** - - "Intel's runtime library can bind OpenMP threads to physical processing units. The interface is controlled using the ``KMP_AFFINITY`` environment variable. Thread affinity restricts execution of certain threads to a subset of the physical processing units in a multiprocessor computer. Depending on the system (machine) topology, application, and operating system, thread affinity can have a dramatic effect on the application speed and on the execution speed of a program." Valid values: ``"scatter"`` | ``"disabled"`` | ``"balanced"`` | ``"compact"`` | ``"explicit"`` | ``"none"`` - - For more information, see the `Intel Development Reference Guide `__. - -``OMP_NUM_THREADS_RUN_FCST``: (Default: 2) - The number of OpenMP threads to use for parallel regions. Corresponds to the ``atmos_nthreads`` value in ``model_configure``. - -``OMP_STACKSIZE_RUN_FCST``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -.. _ModelConfigParams: - -Model Configuration Parameters ----------------------------------- - -These parameters set values in the Weather Model's ``model_configure`` file. - -``DT_ATMOS``: (Default: "") - Time step for the outermost atmospheric model loop in seconds. This corresponds to the frequency at which the physics routines and the top level dynamics routine are called. (Note that one call to the top-level dynamics routine results in multiple calls to the horizontal dynamics, :term:`tracer` transport, and vertical dynamics routines; see the `FV3 dycore scientific documentation `__ for details.) Must be set. Takes an integer value. In the SRW App, a default value for ``DT_ATMOS`` appears in the ``set_predef_grid_params.yaml`` script, but a different value can be set in ``config.yaml``. In general, the smaller the grid cell size is, the smaller this value needs to be in order to avoid numerical instabilities during the forecast. - -``RESTART_INTERVAL``: (Default: 0) - Frequency of the output restart files in hours. Using the default interval (0), restart files are produced at the end of a forecast run. When ``RESTART_INTERVAL: 1``, restart files are produced every hour with the prefix "YYYYMMDD.HHmmSS." in the ``RESTART`` directory. - -.. _InlinePost: - -``WRITE_DOPOST``: (Default: false) - Flag that determines whether to use the inline post option. The default ``WRITE_DOPOST: false`` does not use the inline post functionality, and the ``run_post`` tasks are called from outside of the Weather Model. If ``WRITE_DOPOST: true``, the ``WRITE_DOPOST`` flag in the ``model_configure`` file will be set to true, and the post-processing (:term:`UPP`) tasks will be called from within the Weather Model. This means that the post-processed files (in :term:`grib2` format) are output by the Weather Model at the same time that it outputs the ``dynf###.nc`` and ``phyf###.nc`` files. Setting ``WRITE_DOPOST: true`` turns off the separate ``run_post`` task in ``setup.py`` to avoid unnecessary computations. Valid values: ``True`` | ``False`` - -Computational Parameters ----------------------------- - -``LAYOUT_X, LAYOUT_Y``: (Default: "") - The number of :term:`MPI` tasks (processes) to use in the two horizontal directions (x and y) of the regional grid when running the forecast model. - -``BLOCKSIZE``: (Default: "") - The amount of data that is passed into the cache at a time. - -.. note:: - - In ``config_defaults.yaml`` the computational parameters are set to null strings so that: - - #. If the experiment is using a predefined grid and the user sets the parameter in the user-specified experiment configuration file (i.e., ``config.yaml``), that value will be used in the forecast(s). Otherwise, the default value for that predefined grid will be used. - #. If the experiment is *not* using a predefined grid (i.e., it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the parameter in that configuration file. Otherwise, the parameter will remain set to a null string, and the experiment generation will fail because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory. - -.. _WriteComp: - -Write-Component (Quilting) Parameters ------------------------------------------ - -.. note:: - The :term:`UPP` (called by the ``RUN_POST`` 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 use an Earth System Modeling Framework (:term:`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``. - - 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`` (meta)task cannot run because the :term:`UPP` code called by this task cannot process fields on the native grid. In that case, the ``RUN_POST`` (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. Valid values: ``True`` | ``False`` - -``PRINT_ESMF``: (Default: false) - Flag that determines whether to output extra (debugging) information from :term:`ESMF` routines. 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). Valid values: ``True`` | ``False`` - -``WRTCMP_write_groups``: (Default: 1) - The number of write groups (i.e., groups of :term:`MPI` tasks) to use in the write component. Each write group will write 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 ``WRTCMP_write_tasks_per_group`` tasks. Usually, one write group is sufficient. 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. - -``WRTCMP_write_tasks_per_group``: (Default: 20) - 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.yaml`` 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. - -``WRTCMP_cen_lat``: (Default: "") - 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 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 when running an experiment with a user-defined grid. - -**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "rotated_latlon":** - -``WRTCMP_lon_upr_rght``: (Default: "") - Longitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated longitude). - -``WRTCMP_lat_upr_rght``: (Default: "") - Latitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated latitude). - -``WRTCMP_dlon``: (Default: "") - Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated longitude). - -``WRTCMP_dlat``: (Default: "") - Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated latitude). - -**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "lambert_conformal":** - -``WRTCMP_stdlat1``: (Default: "") - First standard latitude (in degrees) in definition of Lambert conformal projection. - -``WRTCMP_stdlat2``: (Default: "") - Second standard latitude (in degrees) in definition of Lambert conformal projection. - -``WRTCMP_nx``: (Default: "") - Number of grid points in the x-coordinate of the Lambert conformal projection. - -``WRTCMP_ny``: (Default: "") - Number of grid points in the y-coordinate of the Lambert conformal projection. - -``WRTCMP_dx``: (Default: "") - Grid cell size (in meters) along the x-axis of the Lambert conformal projection. - -``WRTCMP_dy``: (Default: "") - Grid cell size (in meters) along the y-axis of the Lambert conformal projection. - -.. _PredefGrid: - -Predefined Grid Parameters ------------------------------- - -``PREDEF_GRID_NAME``: (Default: "") - This parameter indicates which (if any) predefined regional grid to use for the experiment. Setting ``PREDEF_GRID_NAME`` provides a convenient method of specifying a commonly used set of grid-dependent parameters. The predefined grid settings can be viewed in the script ``ush/set_predef_grid_params.yaml``. - - **Currently supported options:** - - | ``"RRFS_CONUS_25km"`` - | ``"RRFS_CONUS_13km"`` - | ``"RRFS_CONUS_3km"`` - | ``"SUBCONUS_Ind_3km"`` - - **Other valid values include:** - - | ``"CONUS_25km_GFDLgrid"`` - | ``"CONUS_3km_GFDLgrid"`` - | ``"EMC_AK"`` - | ``"EMC_HI"`` - | ``"EMC_PR"`` - | ``"EMC_GU"`` - | ``"GSL_HAFSV0.A_25km"`` - | ``"GSL_HAFSV0.A_13km"`` - | ``"GSL_HAFSV0.A_3km"`` - | ``"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:: - - * If ``PREDEF_GRID_NAME`` is set to a valid predefined grid name, the grid generation 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.yaml``). 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. - - * If ``PREDEF_GRID_NAME`` is set to an empty string, it implies that the user will provide the native grid parameters in the user-specified experiment configuration file (``config.yaml``). In this case, the grid generation method, the native grid parameters, the write component grid parameters, the main time step (``DT_ATMOS``), and the computational parameters (``LAYOUT_X``, ``LAYOUT_Y``, and ``BLOCKSIZE``) must be set in the configuration file. Otherwise, the values of the parameters in the default experiment configuration file (``config_defaults.yaml``) will be used. - -Aerosol Climatology Parameter ---------------------------------- - -``USE_MERRA_CLIMO``: (Default: false) - Flag that determines whether :term:`MERRA2` aerosol climatology data and lookup tables for optics properties are obtained. Valid values: ``True`` | ``False`` - - .. COMMENT: When would it be appropriate to obtain these files? - -Fixed File Parameters -------------------------- - -These parameters are associated with the fixed (i.e., static) files. On `Level 1 & 2 `__ systems, fixed files are pre-staged with paths defined in the ``setup.py`` script. Because the default values are platform-dependent, they are set to a null string in ``config_defaults.yaml``. Then these null values are overwritten in ``setup.py`` with machine-specific values or with a user-specified value from ``config.yaml``. - -``FIXgsm``: (Default: "") - System directory in which the majority of fixed (i.e., time-independent) files that are needed to run the FV3-LAM model are located. - -``FIXaer``: (Default: "") - System directory where :term:`MERRA2` aerosol climatology files are located. - -``FIXlut``: (Default: "") - System directory where the lookup tables for optics properties are located. - -``FIXshp``: (Default: "") - System directory where the graphics shapefiles are located. On Level 1 systems, these are set within the machine files. Users on other systems will need to provide the path to the directory that contains the *Natural Earth* shapefiles. - -``TOPO_DIR``: (Default: "") - The location on disk of the static input files used by the ``make_orog`` task (i.e., ``orog.x`` and ``shave.x``). Can be the same as ``FIXgsm``. - -``SFC_CLIMO_INPUT_DIR``: (Default: "") - The location on disk of the static surface climatology input fields, used by ``sfc_climo_gen``. These files are only used if the ``MAKE_SFC_CLIMO`` task is meant to run. - -``SYMLINK_FIX_FILES``: (Default: true) - Flag that indicates whether to symlink or copy fix files to the experiment directory. - -RUN_POST Configuration Parameters -===================================== - -Non-default parameters for the ``run_post`` task are set in the ``task_run_post:`` section of the ``config.yaml`` file. - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``KMP_AFFINITY_RUN_POST``: (Default: "scatter") - Intel Thread Affinity Interface for the ``run_post`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_RUN_POST``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_RUN_POST``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - - -Subhourly Post Parameters ------------------------------ -Set parameters associated with subhourly forecast model output and post-processing. - -``SUB_HOURLY_POST``: (Default: false) - 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 valid value between 1 and 59. Valid values: ``True`` | ``False`` - -``DT_SUB_HOURLY_POST_MNTS``: (Default: 0) - Time interval in minutes between the forecast model output files (only used if ``SUB_HOURLY_POST`` is set to true). If ``SUB_HOURLY_POST`` is set to true, this needs to be set to a valid two-digit integer between 1 and 59. Note that if ``SUB_HOURLY_POST`` is set to true but ``DT_SUB_HOURLY_POST_MNTS`` is set to 0, ``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: ``0`` | ``1`` | ``2`` | ``3`` | ``4`` | ``5`` | ``6`` | ``10`` | ``12`` | ``15`` | ``20`` | ``30`` - -Customized Post Configuration Parameters --------------------------------------------- - -Set parameters for customizing the :term:`UPP`. - -``USE_CUSTOM_POST_CONFIG_FILE``: (Default: false) - Flag that determines whether a user-provided custom configuration file should be used for post-processing the model data. If this is set to true, then the workflow will use the custom post-processing (:term:`UPP`) configuration file specified in ``CUSTOM_POST_CONFIG_FP``. Otherwise, a default configuration file provided in the UPP repository will be used. Valid values: ``True`` | ``False`` - -``CUSTOM_POST_CONFIG_FP``: (Default: "") - The full path to the custom post flat file, including filename, to be used for post-processing. This is only used if ``CUSTOM_POST_CONFIG_FILE`` is set to true. - -``POST_OUTPUT_DOMAIN_NAME``: (Default: "") - Domain name (in lowercase) used to construct the names of the output files generated by the :term:`UPP`. If using a predefined grid, ``POST_OUTPUT_DOMAIN_NAME`` defaults to ``PREDEF_GRID_NAME``. If using a custom grid, ``POST_OUTPUT_DOMAIN_NAME`` must be specified by the user. The post output files are named as follows: - - .. code-block:: console - - $NET.tHHz.[var_name].f###.${POST_OUTPUT_DOMAIN_NAME}.grib2 - - Note that this variable is first changed to lower case before being used to construct the file names. - -RUN_PRDGEN Configuration Parameters -===================================== - -Non-default parameters for the ``run_prdgen`` task are set in the ``task_run_prdgen:`` section of the ``config.yaml`` file. - -Basic Task Parameters ---------------------------------- -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``KMP_AFFINITY_RUN_PRDGEN``: (Default: "scatter") - Intel Thread Affinity Interface for the ``run_prdgen`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_RUN_PRDGEN``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_RUN_PRDGEN``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -``DO_PARALLEL_PRDGEN``: (Default: false) - Flag that determines whether to use CFP to run the product generation job in parallel. CFP is a utility that allows the user to launch a number of small jobs across nodes/cpus in one batch command. This option should be used with the ``RRFS_NA_3km`` grid and ``PPN_RUN_PRDGEN`` should be set to 22. - -``ADDNL_OUTPUT_GRIDS``: (Default: []) - Set additional output grids for wgrib2 remapping, if any. Space-separated list of strings, e.g., ( "130" "242" "clue"). Default is no additional grids. - -``TESTBED_FIELDS_FN``: (Default: "") - The file which lists grib2 fields to be extracted for testbed files. Empty string means no need to generate testbed files. - -.. _PlotVars: - -PLOT_ALLVARS Configuration Parameters -======================================== - -Typically, the following parameters must be set explicitly by the user in the configuration file (``config.yaml``) when executing the plotting tasks. - -``COMOUT_REF``: (Default: "") - The directory where the GRIB2 files from post-processing are located. In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will correspond to the location in the experiment directory where the post-processed output can be found (e.g., ``$EXPTDIR/$DATE_FIRST_CYCL/postprd``). In *nco* mode, this directory should be set to the location of the ``COMOUT`` directory and end with ``$PDY/$cyc``. For more detail on *nco* standards and directory naming conventions, see `WCOSS Implementation Standards `__ (particularly pp. 4-5). - -``PLOT_FCST_START``: (Default: 0) - The starting forecast hour for the plotting task. For example, if a forecast starts at 18h/18z, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. If a forecast starts at 18h/18z, but the user only wants plots from the 6th forecast hour on, "starting forecast hour" should be 6. - -``PLOT_FCST_INC``: (Default: 3) - Forecast hour increment for the plotting task. For example, if the user wants plots for each forecast hour, they should set ``PLOT_FCST_INC: 1``. If the user only wants plots for some of the output (e.g., every 6 hours), they should set ``PLOT_FCST_INC: 6``. - -``PLOT_FCST_END``: (Default: "") - The last forecast hour for the plotting task. For example, if a forecast run for 24 hours, and the user wants plots for each available hour of forecast output, they should set ``PLOT_FCST_END: 24``. If the user only wants plots from the first 12 hours of the forecast, the "last forecast hour" should be 12. - -``PLOT_DOMAINS``: (Default: ["conus"]) - Domains to plot. Currently supported options are ["conus"], ["regional"], or both (i.e., ["conus", "regional"]). - -Global Configuration Parameters -=================================== - -Non-default parameters for the miscellaneous tasks are set in the ``global:`` section of the ``config.yaml`` file. - -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`). :numref:`Section %s ` includes further instructions on how to do this. - -``USE_CRTM``: (Default: false) - Flag that defines whether external :term:`CRTM` coefficient files have been staged by the user in order to output synthetic satellite products available within the :term:`UPP`. If this is set to true, then the workflow will check for these files in the directory ``CRTM_DIR``. Otherwise, it is assumed that no satellite fields are being requested in the UPP configuration. Valid values: ``True`` | ``False`` - -``CRTM_DIR``: (Default: "") - This is the path to the top CRTM fix file directory. This is only used if ``USE_CRTM`` is set to true. - - -Ensemble Model Parameters ------------------------------ - -Set parameters associated with running ensembles. - -``DO_ENSEMBLE``: (Default: false) - Flag that determines whether to run a set of ensemble forecasts (for each set of specified cycles). If this is set to true, ``NUM_ENS_MEMBERS`` forecasts are run for each cycle, each with a different set of stochastic seed values. When false, a single forecast is run for each cycle. Valid values: ``True`` | ``False`` - -``NUM_ENS_MEMBERS``: (Default: 1) - The number of ensemble members to run if ``DO_ENSEMBLE`` is set to true. This variable also controls the naming of the ensemble member directories. For example, if ``NUM_ENS_MEMBERS`` is set to 8, the member directories will be named *mem1, mem2, ..., mem8*. This variable is not used unless ``DO_ENSEMBLE`` is set to true. - -.. _stochastic-physics: - -Stochastic Physics Parameters ----------------------------------- - -Set default ad-hoc stochastic physics options. For the most updated and detailed documentation of these parameters, see the `UFS Stochastic Physics Documentation `__. - -``NEW_LSCALE``: (Default: true) - Use correct formula for converting a spatial legnth scale into spectral space. - -Specific Humidity (SHUM) Perturbation Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``DO_SHUM``: (Default: false) - Flag to turn Specific Humidity (SHUM) perturbations on or off. SHUM perturbations multiply the low-level specific humidity by a small random number at each time-step. The SHUM scheme attempts to address missing physics phenomena (e.g., cold pools, gust fronts) most active in convective regions. Valid values: ``True`` | ``False`` - -``ISEED_SHUM``: (Default: 2) - Seed for setting the SHUM random number sequence. - -``SHUM_MAG``: (Default: 0.006) - Amplitudes of random patterns. Corresponds to the variable ``shum`` in ``input.nml``. - -``SHUM_LSCALE``: (Default: 150000) - Decorrelation spatial scale in meters. - -``SHUM_TSCALE``: (Default: 21600) - Decorrelation timescale in seconds. Corresponds to the variable ``shum_tau`` in ``input.nml``. - -``SHUM_INT``: (Default: 3600) - Interval in seconds to update random pattern (optional). Perturbations still get applied at every time-step. Corresponds to the variable ``shumint`` in ``input.nml``. - -.. _SPPT: - -Stochastically Perturbed Physics Tendencies (SPPT) Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -SPPT perturbs full physics tendencies *after* the call to the physics suite, unlike :ref:`SPP ` (below), which perturbs specific tuning parameters within a physics scheme. - -``DO_SPPT``: (Default: false) - Flag to turn Stochastically Perturbed Physics Tendencies (SPPT) on or off. SPPT multiplies the physics tendencies by a random number between 0 and 2 before updating the model state. This addresses error in the physics parameterizations (either missing physics or unresolved subgrid processes). It is most active in the boundary layer and convective regions. Valid values: ``True`` | ``False`` - -``ISEED_SPPT``: (Default: 1) - Seed for setting the SPPT random number sequence. - -``SPPT_MAG``: (Default: 0.7) - Amplitude of random patterns. Corresponds to the variable ``sppt`` in ``input.nml``. - -``SPPT_LOGIT``: (Default: true) - Limits the SPPT perturbations to between 0 and 2. Should be "TRUE"; otherwise the model will crash. - -``SPPT_LSCALE``: (Default: 150000) - Decorrelation spatial scale in meters. - -``SPPT_TSCALE``: (Default: 21600) - Decorrelation timescale in seconds. Corresponds to the variable ``sppt_tau`` in ``input.nml``. - -``SPPT_INT``: (Default: 3600) - Interval in seconds to update random pattern (optional parameter). Perturbations still get applied at every time-step. Corresponds to the variable ``spptint`` in ``input.nml``. - -``SPPT_SFCLIMIT``: (Default: true) - When true, tapers the SPPT perturbations to zero at the model's lowest level, which reduces model crashes. - -``USE_ZMTNBLCK``: (Default: false) - When true, do not apply perturbations below the dividing streamline that is diagnosed by the gravity wave drag, mountain blocking scheme. Valid values: ``True`` | ``False`` - - -Stochastic Kinetic Energy Backscatter (SKEB) Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``DO_SKEB``: (Default: false) - Flag to turn Stochastic Kinetic Energy Backscatter (SKEB) on or off. SKEB adds wind perturbations to the model state. Perturbations are random in space/time, but amplitude is determined by a smoothed dissipation estimate provided by the :term:`dynamical core`. SKEB addresses errors in the dynamics more active in the mid-latitudes. Valid values: ``True`` | ``False`` - -``ISEED_SKEB``: (Default: 3) - Seed for setting the SHUM random number sequence. - -``SKEB_MAG``: (Default: 0.5) - Amplitude of random patterns. Corresponds to the variable ``skeb`` in ``input.nml``. - -``SKEB_LSCALE``: (Default: 150000) - Decorrelation spatial scale in meters. - -``SKEB_TSCALE``: (Default: 21600) - Decorrelation timescale in seconds. Corresponds to the variable ``skeb_tau`` in ``input.nml``. - -``SKEB_INT``: (Default: 3600) - Interval in seconds to update random pattern (optional). Perturbations still get applied every time-step. Corresponds to the variable ``skebint`` in ``input.nml``. - -``SKEBNORM``: (Default: 1) - Patterns: - * 0-random pattern is stream function - * 1-pattern is K.E. norm - * 2-pattern is vorticity - -``SKEB_VDOF``: (Default: 10) - The number of degrees of freedom in the vertical direction for the SKEB random pattern. - - -.. _SPP: - -Parameters for Stochastically Perturbed Parameterizations (SPP) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -SPP perturbs specific tuning parameters within a physics :term:`parameterization ` (unlike :ref:`SPPT `, which multiplies overall physics tendencies by a random perturbation field *after* the call to the physics suite). Patterns evolve and are applied at each time step. Each SPP option is an array, applicable (in order) to the :term:`RAP`/:term:`HRRR`-based parameterization listed in ``SPP_VAR_LIST``. Enter each value of the array in ``config.yaml`` as shown below without commas or single quotes (e.g., ``SPP_VAR_LIST: [ "pbl" "sfc" "mp" "rad" "gwd" ]`` ). Both commas and single quotes will be added by Jinja when creating the namelist. - -.. note:: - SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which :term:`SDF` is chosen when turning this option on. Of the four supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. - -``DO_SPP``: (Default: false) - Flag to turn SPP on or off. SPP perturbs parameters or variables with unknown or uncertain magnitudes within the physics code based on ranges provided by physics experts. Valid values: ``True`` | ``False`` - -``ISEED_SPP``: (Default: [ 4, 5, 6, 7, 8 ] ) - Seed for setting the random number sequence for the perturbation pattern. - -``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"`` | ``"mp"`` - -``SPP_MAG_LIST``: (Default: [ 0.2, 0.2, 0.75, 0.2, 0.2 ] ) - SPP perturbation magnitudes used in each parameterization. Corresponds to the variable ``spp_prt_list`` in ``input.nml`` - -``SPP_LSCALE``: (Default: [ 150000.0, 150000.0, 150000.0, 150000.0, 150000.0 ] ) - Decorrelation spatial scales in meters. - -``SPP_TSCALE``: (Default: [ 21600.0, 21600.0, 21600.0, 21600.0, 21600.0 ] ) - Decorrelation timescales in seconds. Corresponds to the variable ``spp_tau`` in ``input.nml``. - -``SPP_SIGTOP1``: (Default: [ 0.1, 0.1, 0.1, 0.1, 0.1 ] ) - Controls vertical tapering of perturbations at the tropopause and corresponds to the lower sigma level at which to taper perturbations to zero. - -``SPP_SIGTOP2``: (Default: [ 0.025, 0.025, 0.025, 0.025, 0.025 ] ) - Controls vertical tapering of perturbations at the tropopause and corresponds to the upper sigma level at which to taper perturbations to zero. - -``SPP_STDDEV_CUTOFF``: (Default: [ 1.5, 1.5, 2.5, 1.5, 1.5 ] ) - Limit for possible perturbation values in standard deviations from the mean. - - -Land Surface Model (LSM) SPP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Land surface perturbations can be applied to land model parameters and land model prognostic variables. The LSM scheme is intended to address errors in the land model and land-atmosphere interactions. LSM perturbations include soil moisture content (SMC) (volume fraction), vegetation fraction (VGF), albedo (ALB), salinity (SAL), emissivity (EMI), surface roughness (ZOL) (in cm), and soil temperature (STC). Perturbations to soil moisture content (SMC) are only applied at the first time step. Only five perturbations at a time can be applied currently, but all seven are shown below. In addition, only one unique *iseed* value is allowed at the moment, and it is used for each pattern. - -The parameters below turn on SPP in Noah or RUC LSM (support for Noah MP is in progress). Please be aware of the :term:`SDF` that you choose if you wish to turn on Land Surface Model (LSM) SPP. SPP in LSM schemes is handled in the ``&nam_sfcperts`` namelist block instead of in ``&nam_sppperts``, where all other SPP is implemented. - -``DO_LSM_SPP``: (Default: false) - Turns on Land Surface Model (LSM) Stochastic Physics Parameterizations (SPP). When true, sets ``lndp_type=2``, which applies land perturbations to the selected paramaters using a newer scheme designed for data assimilation (DA) ensemble spread. LSM SPP perturbs uncertain land surface fields ("smc" "vgf" "alb" "sal" "emi" "zol" "stc") based on recommendations from physics experts. Valid values: ``True`` | ``False`` - -``LSM_SPP_TSCALE``: (Default: [ 21600, 21600, 21600, 21600, 21600, 21600, 21600 ] ) - Decorrelation timescales in seconds. - -``LSM_SPP_LSCALE``: (Default: [ 150000, 150000, 150000, 150000, 150000, 150000, 150000 ] ) - Decorrelation spatial scales in meters. - -``ISEED_LSM_SPP``: (Default: [ 9 ] ) - Seed to initialize the random perturbation pattern. - -``LSM_SPP_VAR_LIST``: (Default: [ "smc", "vgf", "alb", "sal", "emi", "zol", "stc" ] ) - Indicates which LSM variables to perturb. - -``LSM_SPP_MAG_LIST``: (Default: [ 0.017, 0.001, 0.001, 0.001, 0.001, 0.001, 0.2 ] ) - Sets the maximum random pattern amplitude for each of the LSM perturbations. - -.. _HaloBlend: - -Halo Blend Parameter ------------------------- -``HALO_BLEND``: (Default: 10) - Number of cells to use for "blending" the external solution (obtained from the :term:`LBCs`) with the internal solution from the FV3LAM :term:`dycore`. Specifically, it refers to the number of rows into the computational domain that should be blended with the LBCs. Cells at which blending occurs are all within the boundary of the native grid; they don't involve the 4 cells outside the boundary where the LBCs are specified (which is a different :term:`halo`). Blending is necessary to smooth out waves generated due to mismatch between the external and internal solutions. To shut :term:`halo` blending off, set this to zero. - diff --git a/docs/UsersGuide/source/ContainerQuickstart.rst b/docs/UsersGuide/source/ContainerQuickstart.rst deleted file mode 100644 index 8515e097a3..0000000000 --- a/docs/UsersGuide/source/ContainerQuickstart.rst +++ /dev/null @@ -1,390 +0,0 @@ -.. _QuickstartC: - -==================================== -Container-Based Quick Start Guide -==================================== - -This Container-Based Quick Start Guide will help users build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a `Singularity `__ container. The :term:`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:`MPIs `, and package versions available. Installation via Singularity container reduces this variability and allows for a smoother SRW App build experience. Normally, containers can only run on a single compute node and are not compatible with the `Rocoto workflow manager `__, so users must run each task in the workflow manually. However, the Singularity container described in this chapter has been adapted such that it is able to run across multiple nodes using Rocoto. This makes it an excellent starting point for beginners. The :ref:`non-container build approach ` may still be more appropriate for 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 16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. - -.. attention:: - - * The SRW Application has `four levels of support `__. 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. - * This chapter of the User's Guide should **only** be used for container builds. For non-container builds, see :numref:`Chapter %s ` for a Quick Start Guide or :numref:`Chapter %s ` for a detailed guide to building the SRW App **without** a container. - -.. _DownloadCodeC: - -Download the Container -=========================================== - -Prerequisites: -------------------- - -Users must have an **Intel** compiler and :term:`MPI` (available for free `here `__) in order to run the SRW App in the container provided using the method described in this chapter. Additionally, it is recommended that users install the `Rocoto workflow manager `__ on their system in order to take advantage of automated workflow options. Although it is possible to run an experiment without Rocoto, and some tips are provided, the only fully-supported and tested container option for the ``develop`` branch assumes that Rocoto is pre-installed. - -.. COMMENT: Remove "for the develop branch"? - -Install Singularity -^^^^^^^^^^^^^^^^^^^^^^^ - -To build and run the SRW App using a Singularity container, first install the Singularity package according to the `Singularity Installation Guide `__. This will include the installation of dependencies and the installation of the Go programming language. SingularityCE Version 3.7 or above is recommended. - -.. warning:: - Docker containers can only be run with root privileges, and users cannot have root privileges on :term:`HPCs `. Therefore, it is not possible to build the SRW App, which uses the HPC-Stack, inside a Docker container on an HPC system. However, a Singularity image may be built directly from a Docker image for use on the system. - -Working in the Cloud or on HPC Systems ------------------------------------------ - -For users working on systems with limited disk space in their ``/home`` directory, it is recommended to set the ``SINGULARITY_CACHEDIR`` and ``SINGULARITY_TMPDIR`` environment variables to point to a location with adequate disk space. For example: - -.. code-block:: - - export SINGULARITY_CACHEDIR= - export SINGULARITY_TMPDIR= - -where ``/absolute/path/to/writable/directory/`` refers to a writable directory (usually a project or user directory within ``/lustre``, ``/work``, ``/scratch``, or ``/glade`` on NOAA Level 1 systems). If the ``cache`` and ``tmp`` directories do not exist already, they must be created with a ``mkdir`` command. - -On NOAA Cloud systems, the ``sudo su`` command may also be required: - -.. code-block:: - - mkdir /lustre/cache - mkdir /lustre/tmp - sudo su - export SINGULARITY_CACHEDIR=/lustre/cache - export SINGULARITY_TMPDIR=/lustre/tmp - exit - -.. 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. - -.. _BuildC: - -Build the Container ------------------------- - -.. hint:: - If a ``singularity: command not found`` error message appears in any of the following steps, try running: ``module load singularity``. - -Level 1 Systems -^^^^^^^^^^^^^^^^^^ - -On most Level 1 systems, a container named ``ubuntu20.04-intel-srwapp-develop.img`` has already been built at the following locations: - -.. table:: Locations of pre-built containers - - +--------------+--------------------------------------------------------+ - | Machine | File location | - +==============+========================================================+ - | Cheyenne | /glade/scratch/epicufsrt/containers | - +--------------+--------------------------------------------------------+ - | Hera | /scratch1/NCEPDEV/nems/role.epic/containers | - +--------------+--------------------------------------------------------+ - | Jet | /mnt/lfs4/HFIP/hfv3gfs/role.epic/containers | - +--------------+--------------------------------------------------------+ - | NOAA Cloud | /contrib/EPIC/containers | - +--------------+--------------------------------------------------------+ - | Orion | /work/noaa/epic-ps/role-epic-ps/containers | - +--------------+--------------------------------------------------------+ - -.. note:: - Singularity is not available on Gaea, and therefore container use is not supported on Gaea. - -Users can simply copy the container to their local working directory. For example, on Hera: - -.. code-block:: console - - cp /scratch1/NCEPDEV/nems/role.epic/containers/ubuntu20.04-intel-srwapp-develop.img . - -Users may convert the container ``.img`` file to a writable sandbox. This step is required when running on Cheyenne but is optional on other systems: - -.. code-block:: console - - singularity build --sandbox ubuntu20.04-intel-srwapp ubuntu20.04-intel-srwapp-develop.img - -When making a writable sandbox on Level 1 systems, the following warnings commonly appear and can be ignored: - -.. code-block:: console - - INFO: Starting build... - INFO: Verifying bootstrap image ubuntu20.04-intel-srwapp-develop.img - WARNING: integrity: signature not found for object group 1 - WARNING: Bootstrap image could not be verified, but build will continue. - -Level 2-4 Systems -^^^^^^^^^^^^^^^^^^^^^ - -On non-Level 1 systems, users should build the container in a writable sandbox: - -.. code-block:: console - - sudo singularity build --sandbox ubuntu20.04-intel-srwapp docker://noaaepic/ubuntu20.04-intel-srwapp:develop - -Some users may prefer to issue the command without the ``sudo`` prefix. Whether ``sudo`` is required is system-dependent. - -.. note:: - Users can choose to build a release version of the container (SRW App v2.1.0) using a similar command: - - .. code-block:: console - - sudo singularity build --sandbox ubuntu20.04-intel-srwapp docker://noaaepic/ubuntu20.04-intel-srwapp:release-public-v2.1.0 - - -.. _WorkOnHPC: - -Allocate a Compute Node --------------------------- - -Users working on HPC systems that do **not** have Rocoto installed must `install Rocoto `__ or allocate a compute node. All other users may skip to the :ref:`next step `. - -.. note:: - - All NOAA Level 1 systems have Rocoto pre-installed. - -The appropriate commands for allocating a compute node will vary based on the user's system and resource manager (e.g., Slurm, PBS). If the user's system has the Slurm resource manager, the allocation command will follow this pattern: - -.. code-block:: console - - salloc -N 1 -n -A -t - -To turn on verification tasks in the workflow, include the ``parm/wflow/verify.yaml`` file in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml``. - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' - -The ``verify.yaml`` file includes the definitions of several common verification tasks by default. They are independent of each other, so users may want to turn some off 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 `. - -To turn off a task, simply include its entry from ``verify.yaml`` as an empty YAML entry. For example, to turn off PointStat tasks: - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' - metatask_vx_ens_member: - metatask_PointStat_mem#mem#: - - -More information about configuring the ``rocoto:`` section can be found in :numref:`Section %s `. - -If users have access to NOAA :term:`HPSS` but have not pre-staged the data, the default ``verify.yaml`` taskgroup will activate the tasks, and the workflow will attempt to download the appropriate data from NOAA HPSS. In this case, 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 `__. - -Users who have already staged the observation data needed for METplus (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data and turn off the corresponding task by including them with no entry in ``config.yaml``. - -.. code-block:: console - - platform: - 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 - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' - task_get_obs_ccpa: - task_get_obs_mrms: - task_get_obs_ndas: - - - -.. _GenerateWorkflow: - -Generate the Regional Workflow -------------------------------------------- - -Run the following command from the ``ufs-srweather-app/ush`` directory to generate the workflow: - -.. code-block:: console - - ./generate_FV3LAM_wflow.py - -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 if users have the Rocoto workflow manager installed on their system. - -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.py`` runs the ``setup.py`` script to set the configuration parameters. Second, it symlinks the time-independent (fix) files and other necessary data input files from their location to the experiment directory (``$EXPTDIR``). Third, it creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` file in the ``parm`` 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.py`` script reads three other configuration scripts in order: (1) ``config_defaults.yaml`` (:numref:`Section %s `), (2) ``config.yaml`` (:numref:`Section %s `), and (3) ``set_predef_grid_params.py``. 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 ``config_defaults.yaml`` and ``config.yaml`` in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.py`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in ``$EXPTDIR``. - -.. _WorkflowGeneration: - -.. figure:: _static/SRW_regional_workflow_gen.png - :alt: Flowchart of the workflow generation process. Scripts are called in the following order: source_util_funcs.sh (which calls bash_utils), then set_FV3nml_sfc_climo_filenames.py, set_FV3nml_ens_stoch_seeds.py, create_diag_table_file.py, and setup.py. setup.py calls several scripts: set_cycle_dates.py, set_grid_params_GFDLgrid.py, set_grid_params_ESGgrid.py, link_fix.py, set_ozone_param.py, set_thompson_mp_fix_files.py, config_defaults.yaml, config.yaml, and valid_param_vals.yaml. Then, it sets a number of variables, including FIXgsm, TOPO_DIR, and SFC_CLIMO_INPUT_DIR variables. Next, set_predef_grid_params.py is called, and the FIXam and FIXLAM directories are set, along with the forecast input files. The setup script also calls set_extrn_mdl_params.py, sets the GRID_GEN_METHOD with HALO, checks various parameters, and generates shell scripts. Then, the workflow generation script produces a YAML configuration file and generates the actual Rocoto workflow XML file from the template file (by calling uwtools set_template). The workflow generation script checks the crontab file and, if applicable, copies certain fix files to the experiment directory. Then, it copies templates of various input files to the experiment directory and sets parameters for the input.nml file. Finally, it generates the workflow. Additional information on each step appears in comments within each script. - - *Experiment Generation Description* - -.. _WorkflowTaskDescription: - -Description of Workflow Tasks --------------------------------- - -.. note:: - 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 baseline 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 removing the ``prep.yaml`` file from the default ``taskgroups`` entry in the ``config.yaml`` file before running the ``generate_FV3LAM_wflow.py`` script: - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/coldstart.yaml", "parm/wflow/post.yaml"]|include }}' - -.. _WorkflowTasksFig: - -.. figure:: _static/SRW_wflow_flowchart.png - :alt: Flowchart of the workflow tasks. If the make_grid, make_orog, and make_sfc_climo tasks are toggled off, they will not be run. If toggled on, make_grid, make_orog, and make_sfc_climo will run consecutively by calling the corresponding exregional script in the scripts directory. The get_ics, get_lbcs, make_ics, make_lbcs, and run_fcst tasks call their respective exregional scripts. The run_post task will run, and if METplus verification tasks have been configured, those will run during post-processing by calling their exregional scripts. - - *Flowchart of the Workflow Tasks* - - -The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``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 ``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:: Baseline Workflow Tasks in the SRW App - - +----------------------+------------------------------------------------------------+ - | **Workflow Task** | **Task Description** | - +======================+============================================================+ - | 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. Only | - | | needs to be run once per experiment. | - +----------------------+------------------------------------------------------------+ - | make_sfc_climo | Pre-processing task to generate surface climatology files. | - | | Only needs to be run once per experiment. | - +----------------------+------------------------------------------------------------+ - | get_extrn_ics | Cycle-specific task to obtain external data for the | - | | initial conditions (ICs) | - +----------------------+------------------------------------------------------------+ - | get_extrn_lbcs | Cycle-specific task to obtain external data for the | - | | lateral boundary conditions (LBCs) | - +----------------------+------------------------------------------------------------+ - | make_ics | Generate initial conditions from the external data | - +----------------------+------------------------------------------------------------+ - | make_lbcs | Generate LBCs from the external data | - +----------------------+------------------------------------------------------------+ - | run_fcst | Run the forecast model (UFS Weather Model) | - +----------------------+------------------------------------------------------------+ - | run_post | Run the post-processing tool (UPP) | - +----------------------+------------------------------------------------------------+ - -In addition to the baseline tasks described in :numref:`Table %s ` above, users may choose to run some or all of the METplus verification tasks. These tasks are described in :numref:`Table %s ` below. - -.. _VXWorkflowTasksTable: - -.. table:: Verification (VX) Workflow Tasks in the SRW App - - +-----------------------+------------------------------------------------------------+ - | **Workflow Task** | **Task Description** | - +=======================+============================================================+ - | GET_OBS_CCPA | Retrieves and organizes hourly :term:`CCPA` data from NOAA | - | | HPSS. Can only be run if ``verify.yaml`` is included in a | - | | ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | GET_OBS_NDAS | Retrieves and organizes hourly :term:`NDAS` data from NOAA | - | | HPSS. Can only be run if ``verify.yaml`` is included in a | - | | ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | GET_OBS_MRMS | Retrieves and organizes hourly :term:`MRMS` composite | - | | reflectivity and :term:`echo top` data from NOAA HPSS. Can | - | | only be run if ``verify.yaml`` is included in a | - | | ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT | Runs METplus grid-to-grid verification for 1-h accumulated | - | | precipitation | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_REFC | Runs METplus grid-to-grid verification for composite | - | | reflectivity | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_RETOP | Runs METplus grid-to-grid verification for :term:`echo top`| - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_##h | Runs METplus grid-to-grid verification for 3-h, 6-h, and | - | | 24-h (i.e., daily) accumulated precipitation. Valid values | - | | for ``##`` are ``03``, ``06``, and ``24``. | - +-----------------------+------------------------------------------------------------+ - | VX_POINTSTAT | Runs METplus grid-to-point verification for surface and | - | | upper-air variables | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID | Runs METplus grid-to-grid ensemble verification for 1-h | - | | accumulated precipitation. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_REFC | Runs METplus grid-to-grid ensemble verification for | - | | composite reflectivity. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_RETOP | Runs METplus grid-to-grid ensemble verification for | - | | :term:`echo top`. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_##h | Runs METplus grid-to-grid ensemble verification for 3-h, | - | | 6-h, and 24-h (i.e., daily) accumulated precipitation. | - | | Valid values for ``##`` are ``03``, ``06``, and ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | 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 | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | 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 | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_MEAN_##h | Runs METplus grid-to-grid verification for ensemble mean | - | | 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation. | - | | Valid values for ``##`` are ``03``, ``06``, and ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_##h | Runs METplus grid-to-grid verification for 3-h, 6-h, and | - | | 24h (i.e., daily) accumulated precipitation probabilistic | - | | output. Valid values for ``##`` are ``03``, ``06``, and | - | | ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_REFC | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for composite reflectivity. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_RETOP | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for :term:`echo top`. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT | Runs METplus grid-to-point ensemble verification for | - | | surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT_MEAN | Runs METplus grid-to-point verification for ensemble mean | - | | surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT_PROB | Runs METplus grid-to-point verification for ensemble | - | | probabilities for surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - - -.. _Run: - -Run the Workflow -======================= - -The workflow can be run using the Rocoto workflow manager (see :numref:`Section %s `) or using standalone wrapper scripts (see :numref:`Section %s `). - -.. attention:: - - If users are running the SRW App on a system that does not have Rocoto installed (e.g., `Level 3 & 4 `__ systems, such as MacOS or generic Linux systems), they should follow the process outlined in :numref:`Section %s ` instead of the instructions in this section. - - -.. _UseRocoto: - -Run the Workflow Using Rocoto --------------------------------- - -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, 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 three ways to run the workflow with Rocoto: (1) automation via crontab (2) by calling the ``launch_FV3LAM_wflow.sh`` script, and (3) by manually issuing the ``rocotorun`` command. - -.. 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 - - export EXPTDIR=// - -If the login shell is csh/tcsh, it can be set using: - -.. code-block:: console - - setenv EXPTDIR // - - -.. _Automate: - -Automated Option -^^^^^^^^^^^^^^^^^^^ - -The simplest way to run the Rocoto workflow is to automate the process using a job scheduler such as :term:`Cron`. For automatic resubmission of the workflow at regular intervals (e.g., every 3 minutes), the user can add the following commands to their ``config.yaml`` file *before* generating the experiment: - -.. code-block:: console - - USE_CRON_TO_RELAUNCH: true - CRON_RELAUNCH_INTVL_MNTS: 3 - -This will automatically add an appropriate entry to the user's :term:`cron table` and launch the workflow. Alternatively, the user can add a crontab entry manually using the ``crontab -e`` command. As mentioned in :numref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.py`` (starting with ``*/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 - - */3 * * * * cd && ./launch_FV3LAM_wflow.sh called_from_cron="TRUE" - -where ```` is changed to correspond to the user's ``$EXPTDIR``. 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 * * * *`` (or ``CRON_RELAUNCH_INTVL_MNTS: 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 * * * *`` (or ``CRON_RELAUNCH_INTVL_MNTS: 3``) is the preferred option for cron jobs on non-NOAA Cloud systems. - -To check the experiment progress: - -.. code-block:: console - - 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:: - - 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. - -.. _Success: - -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 - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ========================================================================================================== - 201906151800 make_grid 4953154 SUCCEEDED 0 1 5.0 - 201906151800 make_orog 4953176 SUCCEEDED 0 1 26.0 - 201906151800 make_sfc_climo 4953179 SUCCEEDED 0 1 33.0 - 201906151800 get_extrn_ics 4953155 SUCCEEDED 0 1 2.0 - 201906151800 get_extrn_lbcs 4953156 SUCCEEDED 0 1 2.0 - 201906151800 make_ics 4953184 SUCCEEDED 0 1 16.0 - 201906151800 make_lbcs 4953185 SUCCEEDED 0 1 71.0 - 201906151800 run_fcst 4953196 SUCCEEDED 0 1 1035.0 - 201906151800 run_post_f000 4953244 SUCCEEDED 0 1 5.0 - 201906151800 run_post_f001 4953245 SUCCEEDED 0 1 4.0 - ... - 201906151800 run_post_f012 4953381 SUCCEEDED 0 1 7.0 - -If users choose to run METplus verification tasks as part of their experiment, the output above will include additional lines after ``run_post_f012``. The output will resemble the following but may be significantly longer when using ensemble verification: - -.. code-block:: console - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ========================================================================================================== - 201906151800 make_grid 30466134 SUCCEEDED 0 1 5.0 - ... - 201906151800 run_post_f012 30468271 SUCCEEDED 0 1 7.0 - 201906151800 run_gridstatvx 30468420 SUCCEEDED 0 1 53.0 - 201906151800 run_gridstatvx_refc 30468421 SUCCEEDED 0 1 934.0 - 201906151800 run_gridstatvx_retop 30468422 SUCCEEDED 0 1 1002.0 - 201906151800 run_gridstatvx_03h 30468491 SUCCEEDED 0 1 43.0 - 201906151800 run_gridstatvx_06h 30468492 SUCCEEDED 0 1 29.0 - 201906151800 run_gridstatvx_24h 30468493 SUCCEEDED 0 1 20.0 - 201906151800 run_pointstatvx 30468423 SUCCEEDED 0 1 670.0 - - -Launch the Rocoto Workflow Using a Script -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users who prefer not to automate their experiments can run the Rocoto workflow using the ``launch_FV3LAM_wflow.sh`` script provided. Simply call it without any arguments from the experiment directory: - -.. code-block:: console - - cd $EXPTDIR - ./launch_FV3LAM_wflow.sh - -This script creates a log file named ``log.launch_FV3LAM_wflow`` in ``$EXPTDIR`` or appends information to the file if it already exists. The launch script also creates the ``log/FV3LAM_wflow.log`` file, which shows Rocoto task information. Check the end of the log file periodically to see how the experiment is progressing: - -.. code-block:: console - - 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 40 log.launch_FV3LAM_wflow - -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 similar to this: - -.. code-block:: console - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ====================================================================================================== - 201906151800 make_grid druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 make_orog - - - - - - 201906151800 make_sfc_climo - - - - - - 201906151800 get_extrn_ics druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 get_extrn_lbcs druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 make_ics - - - - - - 201906151800 make_lbcs - - - - - - 201906151800 run_fcst - - - - - - 201906151800 run_post_00 - - - - - - 201906151800 run_post_01 - - - - - - 201906151800 run_post_02 - - - - - - 201906151800 run_post_03 - - - - - - 201906151800 run_post_04 - - - - - - 201906151800 run_post_05 - - - - - - 201906151800 run_post_06 - - - - - - - Summary of workflow status: - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - - 0 out of 1 cycles completed. - 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 task can be found in the task log files located in ``$EXPTDIR/log``. - -The workflow run is complete when all tasks have "SUCCEEDED", and the ``rocotostat`` command outputs a table similar to the one :ref:`above `. - - -.. _RocotoManualRun: - -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 manually. 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, users can load a modified ``wflow_`` modulefile, or they can use a variant on the following commands to load the Rocoto module: - -.. code-block:: console - - module use - module load rocoto - -Some systems may require a version number (e.g., ``module load rocoto/1.3.3``) - -**Run the Rocoto Workflow** - -After loading Rocoto, ``cd`` to the experiment directory and call ``rocotorun`` 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 - - cd $EXPTDIR - 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 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: - -.. code-block:: console - - cd $EXPTDIR/log - vi make_grid.log - -.. 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. - - -.. _RunUsingStandaloneScripts: - -Run the Workflow Using Stand-Alone Scripts ---------------------------------------------- - -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. - -.. attention:: - - When working on an HPC system, users should allocate a compute node prior to running their experiment. The proper command will depend on the system's resource manager, but some guidance is offered in :numref:`Section %s `. It may be necessay to reload the regional workflow (see :numref:`Section %s `). It may also be necessary to load the ``build__`` scripts as described in :numref:`Section %s `. - -#. ``cd`` into the experiment directory. For example, from ``ush``, presuming default directory settings: - - .. code-block:: console - - cd ../../expt_dirs/test_community - -#. Set the environment variable ``$EXPTDIR`` for either bash or csh, respectively: - - .. code-block:: console - - export EXPTDIR=`pwd` - setenv EXPTDIR `pwd` - -#. Set the ``PDY`` and ``cyc`` environment variables. ``PDY`` refers to the first 8 characters (YYYYMMDD) of the ``DATE_FIRST_CYCL`` variable defined in the ``config.yaml``. ``cyc`` refers to the last two digits of ``DATE_FIRST_CYCL`` (HH) defined in ``config.yaml``. For example, if the ``config.yaml`` file defines ``DATE_FIRST_CYCL: '2019061518'``, the user should run: - - .. code-block:: console - - export PDY=20190615 && export cyc=18 - - before running the wrapper scripts. - -#. Copy the wrapper scripts from the ``ush`` 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/ush/wrappers/* . - -#. Set the ``OMP_NUM_THREADS`` variable. - - .. code-block:: console - - export OMP_NUM_THREADS=1 - -#. 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 - -Each task should finish with error code 0. For example: - -.. code-block:: console - - End exregional_get_extrn_mdl_files.sh at Wed Nov 16 18:08:19 UTC 2022 with error code 0 (time elapsed: 00:00:01) - -Check the batch script output file in your experiment directory for a “SUCCESS” message near the end of the file. - -.. _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. For a brief description of tasks, see :numref:`Table %s `. - - +------------+------------------------+----------------+----------------------------+ - | **Stage/** | **Task Run Script** | **Number of** | **Wall Clock Time (H:mm)** | - | | | **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) | - +------------+------------------------+----------------+----------------------------+ - -Users can access log files for specific tasks in the ``$EXPTDIR/log`` directory. To see how the experiment is progressing, users can also check the end of the ``log.launch_FV3LAM_wflow`` file from the command line: - -.. code-block:: console - - tail -n 40 log.launch_FV3LAM_wflow - -.. 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 HPC systems can be viewed in :numref:`Section %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). diff --git a/docs/UsersGuide/source/TechnicalOverview.rst b/docs/UsersGuide/source/TechnicalOverview.rst deleted file mode 100644 index 4eb03e3c7a..0000000000 --- a/docs/UsersGuide/source/TechnicalOverview.rst +++ /dev/null @@ -1,321 +0,0 @@ -.. _TechOverview: - -==================== -Technical Overview -==================== - -This chapter provides information on SRW App prerequistes, code repositories, and directory structure. - -.. _SRWPrerequisites: - -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 (concepts of parameterizations: physical, microphysical, convective) -* Meteorology (in particular, meteorology at the scales being predicted: 25km, 13km, and 3km resolutions) - -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. SRW App `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 - -* >82 GB disk space - - * 53 GB input data for a standard collection of global data, or "fix" file data (topography, climatology, observational data) for a short 12-hour test forecast on the :term:`CONUS` 25km domain. See data download instructions in :numref:`Section %s `. - * 8 GB for full :term:`HPC-Stack` installation - * 3 GB for ``ufs-srweather-app`` installation - * 1 GB for boundary conditions for a short 12-hour test forecast on the CONUS 25km domain. See data download instructions in :numref:`Section %s `. - * 17 GB for a 12-hour test forecast on the CONUS 25km domain, with model output saved hourly. - -* Fortran compiler released since 2018 - - * 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, LLVM clang, GNU) 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 v2.12+ - -* curl - -* wget - -* Lmod - - -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.20+ - -* :term:`MPI` (MPICH, OpenMPI, or other implementation) - - * Only **MPICH** or **OpenMPI** can be built with HPC-Stack. Other implementations must be installed separately by the user (if desired). - -For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew `__ package manager for MacOS. See :doc:`HPC-Stack Documentation: Chapter 3 ` and :numref:`Chapter %s ` for further guidance on installing these prerequisites on MacOS. - -* bash v4.x -* GNU compiler suite v11 or higher with gfortran -* cmake -* make -* coreutils -* gsed - -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 - -.. _SRWStructure: - -Code Repositories and Directory Structure -========================================= - -.. _HierarchicalRepoStr: - -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 tags the appropriate versions of the external repositories associated with the SRW App (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 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, which are documented `here `__. - -.. note:: - The prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The `HPC-Stack `__ repository assembles these prerequisite libraries. The HPC-Stack has already been built on `preconfigured (Level 1) platforms `__. However, it must be built on other systems. See the :doc:`HPC-Stack Documentation ` for details on installing the HPC-Stack. - - -.. _TopLevelDirStructure: - -Directory Structure ----------------------- -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 (see :numref:`Section %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 - ├── (build) - ├── docs - │ └── UsersGuide - ├── etc - ├── (exec) - ├── (include) - ├── jobs - ├── (lib) - ├── manage_externals - ├── modulefiles - ├── parm - ├── (share) - ├── scripts - ├── sorc - │ ├── CMakeLists.txt - │ ├── (gsi) - │ ├── (rrfs_utl) - │ ├── (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 - ├── tests/WE2E - ├── ush - │ ├── bash_utils - │ ├── machine - │ ├── Python - │ ├── python_utils - │ ├── test_data - │ └── wrappers - └── versions - -SRW App SubDirectories -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:numref:`Table %s ` describes the contents of the most important subdirectories. :numref:`Table %s ` provides an in-depth explanation of the ``ufs-srweather-app`` directories. - -.. _Subdirectories: - -.. table:: Subdirectories of the regional workflow - - +-------------------------+----------------------------------------------------+ - | **Directory Name** | **Description** | - +=========================+====================================================+ - | jobs | J-job scripts launched by Rocoto | - +-------------------------+----------------------------------------------------+ - | modulefiles | Files used to load modules needed for building and | - | | running the workflow | - +-------------------------+----------------------------------------------------+ - | scripts | Scripts launched by the J-jobs | - +-------------------------+----------------------------------------------------+ - | tests | Tests for baseline experiment configurations | - +-------------------------+----------------------------------------------------+ - | ush | Utility scripts used by the workflow | - +-------------------------+----------------------------------------------------+ - -.. _ExperimentDirSection: - -Experiment Directory Structure --------------------------------- -When the user generates an experiment using the ``generate_FV3LAM_wflow.py`` script (:numref:`Step %s `), a user-defined experiment directory (``$EXPTDIR``) is created based on information specified in the ``config.yaml`` file. :numref:`Table %s ` shows the contents of the experiment directory before running the experiment workflow. - -.. _ExptDirStructure: - -.. table:: Files and subdirectory initially created in the experiment directory - :widths: 33 67 - - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | **File Name** | **Description** | - +===========================+==============================================================================================================+ - | config.yaml | User-specified configuration file, see :numref:`Section %s ` | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | data_table | :term:`Cycle-independent` input file (empty) | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | field_table | :term:`Tracers ` in the `forecast model | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | input.nml | :term:`Namelist` for the `UFS Weather Model | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | launch_FV3LAM_wflow.sh | Symlink to the ``ufs-srweather-app/ush/launch_FV3LAM_wflow.sh`` shell script, | - | | which can be used to (re)launch the Rocoto workflow. | - | | Each time this script is called, it appends information 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.py``) | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | nems.configure | See `NEMS configuration file | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | suite_{CCPP}.xml | :term:`CCPP` suite definition file (:term:`SDF`) 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, running the SRW App in *community* mode creates the ``fix_am`` and ``fix_lam`` directories (see :numref:`Table %s `) 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 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 symlinks | - | | 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 Rocoto workflow is launched, several files and directories are generated. A log file named ``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_lbcs``) are preprocessing tasks, and these tasks also result in the creation of new files and subdirectories, 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 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 in the ``config.yaml`` file, more than one cycle | - | | directory will be created under the experiment directory. | - +---------------------------+--------------------------------------------------------------------+ - | 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 by its | - | | various tasks. View the files in this directory to determine 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 | The ``launch_FV3LAM_wflow.sh`` script appends its output to this | - | | log file each time it is called. View the last several | - | | 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/TemplateVars.rst b/docs/UsersGuide/source/TemplateVars.rst deleted file mode 100644 index 2677888f5a..0000000000 --- a/docs/UsersGuide/source/TemplateVars.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. _TemplateVars: - -====================== -Template Variables -====================== - -The SRW App's experiment configuration system supports the use of template variables -in ``config_defaults.yaml`` and ``config.yaml``. A template variable --- or "template" --- is an experiment configuration variable that contains references to values of other variables. -These references are **not** set to the values of the referenced variables (or "expanded") when the experiment's variable definitions file (``var_defns.sh``) is generated or sourced. -Instead, they are expanded and evaluated **at run time** when bash's -``eval`` command is used on the template. - -Generic Example -================== - -As an example, consider a hypothetical template variable named ``MY_CMD`` that is defined in ``config_defaults.yaml`` -(or redefined by the user in ``config.yaml``) as follows: - - .. code-block:: console - - MY_CMD: 'cd ${some_dir}' - -Here, ``some_dir`` may be another experiment variable defined in ``var_defns.sh`` or a -local variable defined in a script or function that will evaluate the template. -It is important to use single quotes on the right-hand side of the definition above; -otherwise, bash will try to evaluate ``${some_dir}`` when constructing ``var_defns.sh``, -which may result in an error and/or unexpected behavior (e.g., if ``${some_dir}`` -is not yet defined). The experiment generation system will define ``MY_CMD`` in -``var_defns.sh`` in exactly the same way as in ``config_defaults.yaml`` and/or -``config.yaml``, e.g., ``MY_CMD: 'cd ${some_dir}'``. Then the following code snippet -in a script or function will evaluate the contents of ``MY_CMD`` using a locally-set -value of ``some_dir``: - - .. code-block:: none - - ... - . var_defns.sh # Source the experiment's variable definition file (assuming - # it is in the current directory). This defines the MY_CMD - # template variable (in addition to other variables). - ... - some_dir="20200715" # Set the local variable some_dir. - ... - eval ${MY_CMD} # Use eval to evaluate the contents of MY_CMD. The value of - # some_dir specified in this file a few lines above is substituted - # for ${some_dir} in MY_CMD before MY_CMD is evaluated. - -Graphics Plotting Example -============================ - -When attempting to generate graphics plots from a forecast, users have the option to -produce difference plots from two experiments that are on the same domain and -available for the same cycle starting date/time and forecast hours. -To generate difference plots, users must use the template variable ``COMOUT_REF`` -to indicate where the :term:`GRIB2` files from post-processing are located. - -In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will -take the form ``/path/to/expt_dirs/expt_name/$PDY$cyc/postprd``, where ``$PDY`` refers -to the cycle date in YYYYMMDD format, and ``$cyc`` refers to the starting hour of the cycle. -(These variables are set in previous tasks based on the value of ``DATE_FIRST_CYCL``.) -Given two experiments, ``expt1`` and ``expt2``, users can generate difference plots by -setting ``COMOUT_REF`` in the ``expt2`` configuration file (``config.yaml``) as follows: - -.. code-block:: console - - COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd' - -The ``expt2`` workflow already knows where to find its own post-processed output, so -``COMOUT_REF`` should point to post-processed output for the other experiment (``expt1``). - -In *nco* mode, this directory should be set to the location of the first experiment's -``COMOUT`` directory (``${COMOUT}`` in the example below) and end with ``${PDY}/${cyc}``. -For example: - -.. code-block:: console - - COMOUT_REF: '${COMOUT}/${PDY}/${cyc}/' - diff --git a/docs/UsersGuide/source/Tutorial.rst b/docs/UsersGuide/source/Tutorial.rst deleted file mode 100644 index f96e39ef52..0000000000 --- a/docs/UsersGuide/source/Tutorial.rst +++ /dev/null @@ -1,586 +0,0 @@ -.. _Tutorial: - -============= -Tutorials -============= - -This chapter walks users through experiment configuration options for various severe weather events. It assumes that users have already (1) :ref:`built the SRW App ` successfully and (2) run the out-of-the-box case contained in ``config.community.yaml`` (and copied to ``config.yaml`` in :numref:`Step %s ` or :numref:`Step %s `) to completion. - -Users can run through the entire set of tutorials or jump to the one that interests them most. The five tutorials address different skills: - - #. :ref:`Severe Weather Over Indianapolis `: Change physics suites and compare graphics plots. - #. :ref:`Cold Air Damming `: Coming soon! - #. :ref:`Southern Plains Winter Weather Event `: Coming soon! - #. :ref:`Halloween Storm `: Coming soon! - #. :ref:`Hurricane Barry `: Coming soon! - -Each section provides a summary of the weather event and instructions for configuring an experiment. - -.. _fcst1: - -Sample Forecast #1: Severe Weather Over Indianapolis -======================================================= - -**Objective:** Modify physics options and compare forecast outputs for similar experiments using the graphics plotting task. - -Weather Summary --------------------- - -A surface boundary associated with a vorticity maximum over the northern Great Plains moved into an unstable environment over Indianapolis, which led to the development of isolated severe thunderstorms before it congealed into a convective line. The moist air remained over the southern half of the area on the following day. The combination of moist air with daily surface heating resulted in isolated thunderstorms that produced small hail. - -**Weather Phenomena:** Numerous tornado and wind reports (6/15) and hail reports (6/16) - - * `Storm Prediction Center (SPC) Storm Report for 20190615 `__ - * `Storm Prediction Center (SPC) Storm Report for 20190616 `__ - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/IndySevereWeather18z.gif - :alt: Radar animation of severe weather over Indianapolis on June 15, 2019 starting at 18z. The animation shows areas of heavy rain and tornado reports moving from west to east over Indianapolis. - - *Severe Weather Over Indianapolis Starting at 18z* - -Data -------- - -On `Level 1 `__ systems, users can find data for the Indianapolis Severe Weather Forecast in the usual input model data locations (see :numref:`Section %s ` for a list). The data can also be downloaded from the `UFS SRW Application Data Bucket `__. - - * FV3GFS data for the first forecast (``control``) is located at: - - * https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/FV3GFS/grib2/2019061518/ - - * HRRR and RAP data for the second forecast (``test_expt``) is located at: - - * https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/HRRR/2019061518/ - * https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#input_model_data/RAP/2019061518/ - -Load the Regional Workflow -------------------------------- - -To load the regional workflow environment, source the lmod-setup file. Then load the workflow conda environment. From the ``ufs-srweather-app`` directory, run: - -.. code-block:: console - - source etc/lmod-setup.sh # OR: source etc/lmod-setup.csh when running in a csh/tcsh shell - module use /path/to/ufs-srweather-app/modulefiles - module load wflow_ - -where ```` is a valid, lowercased machine name (see ``MACHINE`` in :numref:`Section %s ` for valid values). - -After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate regional_workflow``. For example, a user on Hera with permissions on the ``nems`` project may issue the following commands to load the regional workflow (replacing ``User.Name`` with their actual username): - -.. code-block:: console - - source /scratch1/NCEPDEV/nems/User.Name/ufs-srweather-app/etc/lmod-setup.sh hera - module use /scratch1/NCEPDEV/nems/User.Name/ufs-srweather-app/modulefiles - module load wflow_hera - conda activate regional_workflow - -Configuration -------------------------- - -Navigate to the ``ufs-srweather-app/ush`` directory. The default (or "control") configuration for this experiment is based on the ``config.community.yaml`` file in that directory. Users can copy this file into ``config.yaml`` if they have not already done so: - -.. code-block:: console - - cd /path/to/ufs-srweather-app/ush - cp config.community.yaml config.yaml - -Users can save the location of the ``ush`` directory in an environment variable (``$USH``). This makes it easier to navigate between directories later. For example: - -.. code-block:: console - - export USH=/path/to/ufs-srweather-app/ush - -Users should substitute ``/path/to/ufs-srweather-app/ush`` with the actual path on their system. As long as a user remains logged into their system, they can run ``cd $USH``, and it will take them to the ``ush`` directory. The variable will need to be reset for each login session. - -Experiment 1: Control -^^^^^^^^^^^^^^^^^^^^^^^^ - -Edit the configuration file (``config.yaml``) to include the variables and values in the sample configuration excerpts below. - -.. Hint:: - - To open the configuration file in the command line, users may run the command: - - .. code-block:: console - - vi config.yaml - - To modify the file, hit the ``i`` key and then make any changes required. To close and save, hit the ``esc`` key and type ``:wq`` to write the changes to the file and exit/quit the file. Users may opt to use their preferred code editor instead. - -Start in the ``user:`` section and change the ``MACHINE`` and ``ACCOUNT`` variables. For example, when running on a personal MacOS device, users might set: - -.. code-block:: console - - user: - RUN_ENVIR: community - MACHINE: macos - ACCOUNT: none - -For a detailed description of these variables, see :numref:`Section %s `. - -Users do not need to change the ``platform:`` section of the configuration file for this tutorial. The default parameters in the ``platform:`` section pertain to METplus verification, which is not addressed here. For more information on verification, see :numref:`Chapter %s `. - -In the ``workflow:`` section of ``config.yaml``, update ``EXPT_SUBDIR`` and ``PREDEF_GRID_NAME``. - -.. code-block:: console - - workflow: - USE_CRON_TO_RELAUNCH: false - EXPT_SUBDIR: control - CCPP_PHYS_SUITE: FV3_GFS_v16 - PREDEF_GRID_NAME: SUBCONUS_Ind_3km - DATE_FIRST_CYCL: '2019061518' - DATE_LAST_CYCL: '2019061518' - FCST_LEN_HRS: 12 - PREEXISTING_DIR_METHOD: rename - VERBOSE: true - COMPILER: intel - -.. _CronNote: - -.. note:: - - Users may also want to set ``USE_CRON_TO_RELAUNCH: true`` and add ``CRON_RELAUNCH_INTVL_MNTS: 3``. This will automate submission of workflow tasks when running the experiment. However, not all systems have :term:`cron`. - -``EXPT_SUBDIR:`` This variable can be changed to any name the user wants. This tutorial uses ``control`` to establish a baseline, or "control", forecast. Users can choose any name they want, from "gfsv16_physics_fcst" to "forecast1" to "a;skdfj". However, the best names will indicate useful information about the experiment. For example, this tutorial helps users to compare the output from two different forecasts: one that uses the FV3_GFS_v16 physics suite and one that uses the FV3_RRFS_v1beta physics suite. Therefore, "gfsv16_physics_fcst" could be a good alternative directory name. - -``PREDEF_GRID_NAME:`` This experiment uses the SUBCONUS_Ind_3km grid, rather than the default RRFS_CONUS_25km grid. The SUBCONUS_Ind_3km grid is a high-resolution grid (with grid cell size of approximately 3km) that covers a small area of the U.S. centered over Indianapolis, IN. For more information on this grid, see :numref:`Section %s `. - -For a detailed description of other ``workflow:`` variables, see :numref:`Section %s `. - -To turn on the plotting for the experiment, the YAML configuration file -should be included in the ``rocoto:taskgroups:`` section, like this: - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' - - -For more information on how to turn on/off tasks in the worklfow, please -see :numref:`Section %s ` - -In the ``task_get_extrn_ics:`` section, add ``USE_USER_STAGED_EXTRN_FILES`` and ``EXTRN_MDL_SOURCE_BASEDIR_ICS``. Users will need to adjust the file path to reflect the location of data on their system (see :numref:`Section %s ` for locations on `Level 1 `__ systems). - -.. code-block:: console - - task_get_extrn_ics: - EXTRN_MDL_NAME_ICS: FV3GFS - FV3GFS_FILE_FMT_ICS: grib2 - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/UFS_SRW_App/develop/input_model_data/FV3GFS/grib2/${yyyymmddhh} - -For a detailed description of the ``task_get_extrn_ics:`` variables, see :numref:`Section %s `. - -Similarly, in the ``task_get_extrn_lbcs:`` section, add ``USE_USER_STAGED_EXTRN_FILES`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. Users will need to adjust the file path to reflect the location of data on their system (see :numref:`Section %s ` for locations on Level 1 systems). - -.. code-block:: console - - task_get_extrn_lbcs: - EXTRN_MDL_NAME_LBCS: FV3GFS - LBC_SPEC_INTVL_HRS: 6 - FV3GFS_FILE_FMT_LBCS: grib2 - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/UFS_SRW_App/develop/input_model_data/FV3GFS/grib2/${yyyymmddhh} - -For a detailed description of the ``task_get_extrn_lbcs:`` variables, see :numref:`Section %s `. - -Users do not need to modify the ``task_run_fcst:`` section for this tutorial. - -Lastly, in the ``task_plot_allvars:`` section, add ``PLOT_FCST_INC: 6`` and ``PLOT_DOMAINS: ["regional"]``. Users may also want to add ``PLOT_FCST_START: 0`` and ``PLOT_FCST_END: 12`` explicitly, but these can be omitted since the default values are the same as the forecast start and end time respectively. - -.. code-block:: console - - task_plot_allvars: - COMOUT_REF: "" - PLOT_FCST_INC: 6 - PLOT_DOMAINS: ["regional"] - -``PLOT_FCST_INC:`` This variable indicates the forecast hour increment for the plotting task. By setting the value to ``6``, the task will generate a ``.png`` file for every 6th forecast hour starting from 18z on June 15, 2019 (the 0th forecast hour) through the 12th forecast hour (June 16, 2019 at 06z). - -``PLOT_DOMAINS:`` The plotting scripts are designed to generate plots over the entire CONUS by default, but by setting this variable to ["regional"], the experiment will generate plots for the smaller SUBCONUS_Ind_3km regional domain instead. - -After configuring the forecast, users can generate the forecast by running: - -.. code-block:: console - - ./generate_FV3LAM_wflow.py - -To see experiment progress, users should navigate to their experiment directory. Then, use the ``rocotorun`` command to launch new workflow tasks and ``rocotostat`` to check on experiment progress. - -.. code-block:: console - - cd /path/to/expt_dirs/control - rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - -Users will need to rerun the ``rocotorun`` and ``rocotostat`` commands above regularly and repeatedly to continue submitting workflow tasks and receiving progress updates. - -.. note:: - - When using cron to automate the workflow submission (as described :ref:`above `), users can omit the ``rocotorun`` command and simply use ``rocotostat`` to check on progress periodically. - -Users can save the location of the ``control`` directory in an environment variable (``$CONTROL``). This makes it easier to navigate between directories later. For example: - -.. code-block:: console - - export CONTROL=/path/to/expt_dirs/control - -Users should substitute ``/path/to/expt_dirs/control`` with the actual path on their system. As long as a user remains logged into their system, they can run ``cd $CONTROL``, and it will take them to the ``control`` experiment directory. The variable will need to be reset for each login session. - -Experiment 2: Test -^^^^^^^^^^^^^^^^^^^^^^ - -Once the control case is running, users can return to the ``config.yaml`` file (in ``$USH``) and adjust the parameters for a new forecast. Most of the variables will remain the same. However, users will need to adjust ``EXPT_SUBDIR`` and ``CCPP_PHYS_SUITE`` in the ``workflow:`` section as follows: - -.. code-block:: console - - workflow: - EXPT_SUBDIR: test_expt - CCPP_PHYS_SUITE: FV3_RRFS_v1beta - -``EXPT_SUBDIR:`` This name must be different than the ``EXPT_SUBDIR`` name used in the previous forecast experiment. Otherwise, the first forecast experiment will be overwritten. ``test_expt`` is used here, but the user may select a different name if desired. - -``CCPP_PHYS_SUITE:`` The FV3_RRFS_v1beta physics suite was specifically created for convection-allowing scales and is the precursor to the operational physics suite that will be used in the Rapid Refresh Forecast System (:term:`RRFS`). - -.. hint:: - - Later, users may want to conduct additional experiments using the FV3_HRRR and FV3_WoFS_v0 physics suites. Like FV3_RRFS_v1beta, these physics suites were designed for use with high-resolution grids for storm-scale predictions. - -Next, users will need to modify the data parameters in ``task_get_extrn_ics:`` and ``task_get_extrn_lbcs:`` to use HRRR and RAP data rather than FV3GFS data. Users will need to change the following lines in each section: - -.. code-block:: console - - task_get_extrn_ics: - EXTRN_MDL_NAME_ICS: HRRR - EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/UFS_SRW_App/develop/input_model_data/HRRR/${yyyymmddhh} - task_get_extrn_lbcs: - EXTRN_MDL_NAME_LBCS: RAP - EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/UFS_SRW_App/develop/input_model_data/RAP/${yyyymmddhh} - EXTRN_MDL_LBCS_OFFSET_HRS: '-0' - -HRRR and RAP data are better than FV3GFS data for use with the FV3_RRFS_v1beta physics scheme because these datasets use the same physics :term:`parameterizations` that are in the FV3_RRFS_v1beta suite. They focus on small-scale weather phenomena involved in storm development, so forecasts tend to be more accurate when HRRR/RAP data are paired with FV3_RRFS_v1beta and a high-resolution (e.g., 3-km) grid. Using HRRR/RAP data with FV3_RRFS_v1beta also limits the "spin-up adjustment" that takes place when initializing with model data coming from different physics. - -``EXTRN_MDL_LBCS_OFFSET_HRS:`` This variable allows users to use lateral boundary conditions (LBCs) from a previous forecast run that was started earlier than the start time of the forecast being configured in this experiment. This variable is set to 0 by default except when using RAP data; with RAP data, the default value is 3, so the forecast will look for LBCs from a forecast started 3 hours earlier (i.e., at 2019061515 --- 15z --- instead of 2019061518). To avoid this, users must set ``EXTRN_MDL_LBCS_OFFSET_HRS`` explicitly. - -Add a section to ``config.yaml`` to increase the maximum wall time (``WTIME_RUN_POST``) for the postprocessing tasks. The wall time is the maximum length of time a task is allowed to run. On some systems, the default of 15 minutes may be enough, but on others (e.g., NOAA Cloud), the post-processing time exceeds 15 minutes, so the tasks fail. - -.. code-block:: console - - task_run_post: - WTIME_RUN_POST: 00:20:00 - -Lastly, users must set the ``COMOUT_REF`` variable in the ``task_plot_allvars:`` section to create difference plots that compare output from the two experiments. ``COMOUT_REF`` is a template variable, so it references other workflow variables within it (see :numref:`Section %s ` for details on template variables). ``COMOUT_REF`` should provide the path to the ``control`` experiment forecast output using single quotes as shown below: - -.. code-block:: console - - task_plot_allvars: - COMOUT_REF: '${EXPT_BASEDIR}/control/${PDY}${cyc}/postprd' - -Here, ``$EXPT_BASEDIR`` is the path to the main experiment directory (named ``expt_dirs`` by default). ``$PDY`` refers to the cycle date in YYYYMMDD format, and ``$cyc`` refers to the starting hour of the cycle. ``postprd`` contains the post-processed data from the experiment. Therefore, ``COMOUT_REF`` will refer to ``control/2019061518/postprd`` and compare those plots against the ones in ``test_expt/2019061518/postprd``. - -After configuring the forecast, users can generate the second forecast by running: - -.. code-block:: console - - ./generate_FV3LAM_wflow.py - -To see experiment progress, users should navigate to their experiment directory. As in the first forecast, the following commands allow users to launch new workflow tasks and check on experiment progress. - -.. code-block:: console - - cd /path/to/expt_dirs/test_expt - rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - -.. note:: - - When using cron to automate the workflow submission (as described :ref:`above `), users can omit the ``rocotorun`` command and simply use ``rocotostat`` to check on progress periodically. - -.. note:: - - If users have not automated their workflow using cron, they will need to ensure that they continue issuing ``rocotorun`` commands to launch all of the tasks in each experiment. While switching between experiment directories to run ``rocotorun`` and ``rocotostat`` commands in both directories is possible, it may be easier to finish the ``control`` experiment's tasks before starting on ``test_expt``. - - -Compare and Analyze Results ------------------------------ - -Navigate to ``test_expt/2019061518/postprd``. This directory contains the post-processed data generated by the :term:`UPP` from the forecast. After the ``plot_allvars`` task completes, this directory will contain ``.png`` images for several forecast variables including 2-m temperature, 2-m dew point temperature, 10-m winds, accumulated precipitation, composite reflectivity, and surface-based CAPE/CIN. Plots with a ``_diff`` label in the file name are plots that compare the ``control`` forecast and the ``test_expt`` forecast. - -Copy ``.png`` Files onto Local System -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users who are working on the cloud or on an HPC cluster may want to copy the ``.png`` files onto their local system to view in their preferred image viewer. Detailed instructions are available in the :ref:`Introduction to SSH & Data Transfer `. - -In summary, users can run the ``scp`` command in a new terminal/command prompt window to securely copy files from a remote system to their local system if an SSH tunnel is already established between the local system and the remote system. Users can adjust one of the following commands for their system: - -.. code-block:: console - - scp username@your-IP-address:/path/to/source_file_or_directory /path/to/destination_file_or_directory - # OR - scp -P 12345 username@localhost:/path/to/source_file_or_directory path/to/destination_file_or_directory - -Users would need to modify ``username``, ``your-IP-address``, ``-P 12345``, and the file paths to reflect their systems' information. See the :ref:`Introduction to SSH & Data Transfer ` for example commands. - -.. _ComparePlots: - -Compare Images -^^^^^^^^^^^^^^^^^^ - -The plots generated by the experiment cover a variety of variables. After downloading the ``.png`` plots, users can open and view the plots on their local system in their preferred image viewer. :numref:`Table %s ` lists the available plots (``hhh`` corresponds to the three-digit forecast hour): - -.. _DiffPlots: - -.. table:: Sample Indianapolis Forecast Plots - - +-----------------------------------------+-----------------------------------+ - | Field | File Name | - +=========================================+===================================+ - | 2-meter dew point temperature | 2mdew_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | 2-meter temperature | 2mt_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | 10-meter winds | 10mwind_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | 250-hPa winds | 250wind_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Accumulated precipitation | qpf_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Composite reflectivity | refc_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Surface-based CAPE/CIN | sfcape_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Sea level pressure | slp_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Max/Min 2 - 5 km updraft helicity | uh25_diff_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - -Each difference plotting ``.png`` file contains three subplots. The plot for the second experiment (``test_expt``) appears in the top left corner, and the plot for the first experiment (``control``) appears in the top right corner. The difference plot that compares both experiments appear at the bottom. Areas of white signify no difference between the plots. Therefore, if the forecast output from both experiments is exactly the same, the difference plot will show a white square (see :ref:`Sea Level Pressure ` for an example). If the forecast output from both experiments is extremely different, the plot will show lots of color. - -In general, it is expected that the results for ``test_expt`` (using FV3_RRFS_v1beta physics and HRRR/RAP data) will be more accurate than the results for ``control`` (using FV3_GFS_v16 physics and FV3GFS data) because the physics in ``test_expt`` is designed for high-resolution, storm-scale prediction over a short period of time. The ``control`` experiment physics is better for predicting the evolution of larger scale weather phenomena, like jet stream movement and cyclone development, since the cumulus physics in the FV3_GFS_v16 suite is not configured to run at 3-km resolution. - -Analysis -^^^^^^^^^^^ - -.. _fcst1_slp: - -Sea Level Pressure -````````````````````` -In the Sea Level Pressure (SLP) plots, the ``control`` and ``test_expt`` plots are nearly identical at forecast hour f000, so the difference plot is entirely white. - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/slp_diff_regional_f000.png - :align: center - - *Difference Plot for Sea Level Pressure at f000* - -As the forecast continues, the results begin to diverge, as evidenced by the spattering of light blue dispersed across the f006 SLP difference plot. - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/slp_diff_regional_f006.png - :align: center - - *Difference Plot for Sea Level Pressure at f006* - -The predictions diverge further by f012, where a solid section of light blue in the top left corner of the difference plot indicates that to the northwest of Indianapolis, the SLP predictions for the ``control`` forecast were slightly lower than the predictions for the ``test_expt`` forecast. - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/slp_diff_regional_f012.png - :align: center - - *Difference Plot for Sea Level Pressure at f012* - -.. _fcst1_refc: - -Composite Reflectivity -`````````````````````````` - -Reflectivity images visually represent the weather based on the energy (measured in decibels [dBZ]) reflected back from radar. Composite reflectivity generates an image based on reflectivity scans at multiple elevation angles, or "tilts", of the antenna. See https://www.weather.gov/jetstream/refl for a more detailed explanation of composite reflectivity. - -At f000, the ``test_expt`` plot (top left) is showing more severe weather than the ``control`` plot (top right). The ``test_expt`` plot shows a vast swathe of the Indianapolis region covered in yellow with spots of orange, corresponding to composite reflectivity values of 35+ dBZ. The ``control`` plot radar image covers a smaller area of the grid, and with the exception of a few yellow spots, composite reflectivity values are <35 dBZ. The difference plot (bottom) shows areas where the ``test_expt`` plot (red) and the ``control`` plot (blue) have reflectivity values greater than 20 dBZ. The ``test_expt`` plot has significantly more areas with high composite reflectivity values. - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/refc_diff_regional_f000.png - :align: center - - *Composite Reflectivity at f000* - -As the forecast progresses, the radar images resemble each other more (see :numref:`Figure %s `). Both the ``test_expt`` and ``control`` plots show the storm gaining energy (with more orange and red areas), rotating counterclockwise, and moving east. Thus, both forecasts do a good job of picking up on the convection. However, the ``test_expt`` forecast still indicates a higher-energy storm with more areas of *dark* red. It appears that the ``test_expt`` case was able to resolve more discrete storms over northwest Indiana and in the squall line. The ``control`` plot has less definition and depicts widespread storms concentrated together over the center of the state. - -.. _refc006: - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/refc_diff_regional_f006.png - :align: center - - *Composite reflectivity at f006 shows storm gathering strength* - -At forecast hour 12, the plots for each forecast show a similar evolution of the storm with both resolving a squall line. The ``test_expt`` plot shows a more intense squall line with discrete cells (areas of high composite reflectivity in dark red), which could lead to severe weather. The ``control`` plot shows an overall decrease in composite reflectivity values compared to f006. It also orients the squall line more northward with less intensity, possibly due to convection from the previous forecast runs cooling the atmosphere. In short, ``test_expt`` suggests that the storm will still be going strong at 06z on June 15, 2019, whereas the ``control`` suggests that the storm will begin to let up. - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/refc_diff_regional_f012.png - :align: center - - *Composite Reflectivity at f012* - -.. _fcst1_sfcape: - -Surface-Based CAPE/CIN -`````````````````````````` - -Background -"""""""""""" - -The National Weather Service (:term:`NWS`) defines Surface-Based Convective Available Potential Energy (CAPE) as "the amount of fuel available to a developing thunderstorm." According to NWS, CAPE "describes the instabilily of the atmosphere and provides an approximation of updraft strength within a thunderstorm. A higher value of CAPE means the atmosphere is more unstable and would therefore produce a stronger updraft" (see `NWS, What is CAPE? `__ for further explanation). - -According to the NWS `Storm Prediction Center `__, Convective Inhibition (CIN) "represents the 'negative' area on a sounding that must be overcome for storm initiation." In effect, it measures negative buoyancy (-B) --- the opposite of CAPE, which measures positive buoyancy (B or B+) of an air parcel. - -.. - More CAPE/CIN info: https://www.e-education.psu.edu/files/meteo361/image/Section4/cape_primer0301.html - -Interpreting the Plots -"""""""""""""""""""""""" - -CAPE measures are represented on the plots using color. They range in value from 100-5000 Joules per kilogram (J/kg). Lower values are represented by cool colors and higher values are represented by warm colors. In general, values of approximately 1000+ J/kg can lead to severe thunderstorms, although this is also dependent on season and location. - -CIN measures are displayed on the plots using hatch marks: - - * ``*`` means CIN <= -500 J/kg - * ``+`` means -500 < CIN <= -250 J/kg - * ``/`` means -250 < CIN <= -100 J/kg - * ``.`` means -100 < CIN <= -25 J/kg - -In general, the higher the CIN values are (i.e., the closer they are to zero), the lower the convective inhibition and the greater the likelihood that a storm will develop. Low CIN values (corresponding to high convective inhibition) make it unlikely that a storm will develop even in the presence of high CAPE. - -At the 0th forecast hour, the ``test_expt`` plot (below, left) shows lower values of CAPE and higher values of CIN than in the ``control`` plot (below, right). This means that ``test_expt`` is projecting lower potential energy available for a storm but also lower inhibition, which means that less energy would be required for a storm to develop. The difference between the two plots is particularly evident in the southwest corner of the difference plot, which shows a 1000+ J/kg difference between the two plots. - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/sfcape_diff_regional_f000.png - :width: 1200 - :align: center - - *CAPE/CIN Difference Plot at f000* - -At the 6th forecast hour, both ``test_expt`` and ``control`` plots are forecasting higher CAPE values overall. Both plots also predict higher CAPE values to the southwest of Indianapolis than to the northeast. This makes sense because the storm was passing from west to east. However, the difference plot shows that the ``control`` forecast is predicting higher CAPE values primarily to the southwest of Indianapolis, whereas ``test_expt`` is projecting a rise in CAPE values throughout the region. The blue region of the difference plot indicates where ``test_expt`` predictions are higher than the ``control`` predictions; the red/orange region shows places where ``control`` predicts significantly higher CAPE values than ``test_expt`` does. - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/sfcape_diff_regional_f006.png - :width: 1200 - :align: center - - *CAPE/CIN Difference Plot at f006* - -At the 12th forecast hour, the ``control`` plot indicates that CAPE may be decreasing overall. ``test_expt``, however, shows that areas of high CAPE remain and continue to grow, particularly to the east. The blue areas of the difference plot indicate that ``test_expt`` is predicting higher CAPE than ``control`` everywhere but in the center of the plot. - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/fcst1_plots/sfcape_diff_regional_f012.png - :width: 1200 - :align: center - - *CAPE/CIN Difference Plot at f012* - -Try It! ----------- - -Option 1: Adjust frequency of forecast plots. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For a simple extension of this tutorial, users can adjust ``PLOT_FCST_INC`` to output plots more frequently. For example, users can set ``PLOT_FCST_INC: 1`` to produce plots for every hour of the forecast. This would allow users to conduct a more fine-grained visual comparison of how each forecast evolved. - -Option 2: Compare output from additional physics suites. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users are encouraged to conduct additional experiments using the FV3_HRRR and FV3_WoFS_v0 physics suites. Like FV3_RRFS_v1beta, these physics suites were designed for use with high-resolution grids for storm-scale predictions. Compare them to each other or to the control! - -Users may find the difference plots for :term:`updraft helicity` particularly informative. The FV3_GFS_v16 physics suite does not contain updraft helicity output in its ``diag_table`` files, so the difference plot generated in this tutorial is empty. Observing high values for updraft helicity indicates the presence of a rotating updraft, often the result of a supercell thunderstorm capable of severe weather, including tornadoes. Comparing the results from two physics suites that measure this parameter can therefore prove insightful. - -.. _fcst2: - -Sample Forecast #2: Cold Air Damming -======================================== - -Weather Summary ------------------ - -Cold air damming occurs when cold dense air is topographically trapped along the leeward (downwind) side of a mountain. Starting on February 3, 2020, weather conditions leading to cold air damming began to develop east of the Appalachian mountains. By February 6-7, 2020, this cold air damming caused high winds, flash flood advisories, and wintery conditions. - -**Weather Phenomena:** Cold air damming - - * `Storm Prediction Center (SPC) Storm Report for 20200205 `__ - * `Storm Prediction Center (SPC) Storm Report for 20200206 `__ - * `Storm Prediction Center (SPC) Storm Report for 20200207 `__ - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/ColdAirDamming.jpg - :alt: Radar animation of precipitation resulting from cold air damming in the southern Appalachian mountains. - - *Precipitation Resulting from Cold Air Damming East of the Appalachian Mountains* - -Tutorial Content -------------------- - -Coming Soon! - -.. _fcst3: - -Sample Forecast #3: Southern Plains Winter Weather Event -=========================================================== - -Weather Summary --------------------- - -A polar vortex brought arctic air to much of the U.S. and Mexico. A series of cold fronts and vorticity disturbances helped keep this cold air in place for an extended period of time resulting in record-breaking cold temperatures for many southern states and Mexico. This particular case captures two winter weather disturbances between February 14, 2021 at 06z and February 17, 2021 at 06z that brought several inches of snow to Oklahoma City. A lull on February 16, 2021 resulted in record daily low temperatures. - -**Weather Phenomena:** Snow and record-breaking cold temperatures - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SouthernPlainsWinterWeather.jpg - :alt: Radar animation of the Southern Plains Winter Weather Event centered over Oklahoma City. Animation starts on February 14, 2021 at 6h00 UTC and ends on February 17, 2021 at 6h00 UTC. - - *Southern Plains Winter Weather Event Over Oklahoma City* - -.. COMMENT: Upload a png to the SRW wiki and change the hyperlink to point to that. - -Tutorial Content -------------------- - -Coming Soon! - -.. _fcst4: - -Sample Forecast #4: Halloween Storm -======================================= - -Weather Summary --------------------- - -A line of severe storms brought strong winds, flash flooding, and tornadoes to the eastern half of the US. - -**Weather Phenomena:** Flooding and high winds - - * `Storm Prediction Center (SPC) Storm Report for 20191031 `__ - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/HalloweenStorm.jpg - :alt: Radar animation of the Halloween Storm that swept across the Eastern United States in 2019. - - *Halloween Storm 2019* - -Tutorial Content -------------------- - -Coming Soon! - -.. _fcst5: - -Sample Forecast #5: Hurricane Barry -======================================= - -Weather Summary --------------------- - -Hurricane Barry made landfall in Louisiana on July 11, 2019 as a Category 1 hurricane. It produced widespread flooding in the region and had a peak wind speed of 72 mph and a minimum pressure of 992 hPa. - -**Weather Phenomena:** Flooding, wind, and tornado reports - - * `Storm Prediction Center (SPC) Storm Report for 20190713 `__ - * `Storm Prediction Center (SPC) Storm Report for 20190714 `__ - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/HurricaneBarry_Making_Landfall.jpg - :alt: Radar animation of Hurricane Barry making landfall. - - *Hurricane Barry Making Landfall* - -Tutorial Content -------------------- - -Coming Soon! diff --git a/docs/UsersGuide/source/VXCases.rst b/docs/UsersGuide/source/VXCases.rst deleted file mode 100644 index 2198ce10c4..0000000000 --- a/docs/UsersGuide/source/VXCases.rst +++ /dev/null @@ -1,313 +0,0 @@ -.. _VXCases: - -============================ -Verification Sample Cases -============================ - -Introduction -=============== - -The goal of these sample cases is to provide the UFS community with datasets that they can modify and run to see if their changes can improve the forecast and/or reduce the model biases. Each case covers an interesting weather event. The case that was added with the v2.1.0 release was a severe weather event over Indianapolis on June 15-16, 2019. In the future, additional sample cases will be provided. - -Each sample case contains model output from a control run; this output includes ``postprd`` (post-processed) and ``metprd`` (MET verification-processed) directories. Under the ``postprd`` directory, users will find the :term:`UPP` output of the model run along with plots for several forecast variables. These can be used for a visual/qualitative comparison of forecasts. The ``metprd`` directory contains METplus verification statistics files, which can be used for a quantitative comparison of forecast outputs. - -Prerequisites -================ - -This chapter assumes that users have already (1) built the SRW App v2.1.0 successfully and (2) installed MET and METplus on their system. - -For instructions on how to build the v2.1.0 release of the SRW App, see the v2.1.0 release documentation on :ref:`Building the SRW App `. The release code is used to provide a consistent point of comparison; the ``develop`` branch code is constantly receiving updates, which makes it unsuited to this purpose. Users will have an easier time if they run through the out-of-the-box case described in :numref:`Chapter %s ` before attempting to run any verification sample cases, but doing so is optional. - -For information on MET and METplus, see :numref:`Section %s `, which contains information on METplus, links to a list of existing MET/METplus builds on `Level 1 & 2 `__ systems, and links to installation instructions and documentation for users on other systems. - -Indianapolis Severe Weather Case -========================================== - -Description --------------- - -A severe weather event over the Indianapolis Metropolitan Area in June 2019 resulted from a frontal passage that led to the development of isolated severe thunderstorms. These thunderstorms subsequently congealed into a convective squall line. The frontal line was associated with a vorticity maximum originating over the northern Great Plains that moved into an unstable environment over Indianapolis. The moist air remained over the southern part of the area on the following day, when the diurnal heating caused isolated thunderstorms producing small hail. - -There were many storm reports for this event with the majority of tornadoes and severe winds being reported on June 15th, while more severe hail was reported on June 16th. A link to the Storm Prediction Center's Storm Reports can be found here: - - * `Storm Prediction Center Storm Report for 20190615 `__ - * `Storm Prediction Center Storm Report for 20190616 `__ - -Set Up Verification ------------------------ - -Follow the instructions below to reproduce a forecast for this event using your own model setup! Make sure to install and build the latest version of the SRW Application (v2.1.0). ``develop`` branch code is constantly changing, so it does not provide a consistent baseline for comparison. - -.. _GetSampleData: - -Get Data -^^^^^^^^^^^ - -On `Level 1 `__ systems, users can find data for the Indianapolis Severe Weather Forecast in the usual data locations (see :numref:`Section %s ` for a list). - -On other systems, users need to download the ``Indy-Severe-Weather.tgz`` file using any of the following methods: - - #. Download directly from the S3 bucket using a browser. The data is available at https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#sample_cases/release-public-v2.1.0/. - - #. Download from a terminal using the AWS command line interface (CLI) if installed: - - .. code-block:: console - - aws s3 cp https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#sample_cases/release-public-v2.1.0/Indy-Severe-Weather.tgz Indy-Severe-Weather.tgz - - #. Download from a terminal using wget: - - .. code-block:: console - - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/sample_cases/release-public-v2.1.0/Indy-Severe-Weather.tgz - -This tar file contains :term:`IC/LBC ` files, observation data, model/forecast output and MET verification output for the sample forecast. Users who have never run the SRW App on their system before will also need to download the fix files required for SRW App forecasts and the NaturalEarth shapefiles required for plotting. Users can download the fix file data from a browser at https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/fix_data.tgz or visit :numref:`Section %s ` for instructions on how to download the data with wget. NaturalEarth files are available at https://noaa-ufs-srw-pds.s3.amazonaws.com/NaturalEarth/NaturalEarth.tgz. See the :ref:`Graphics ` chapter of the release documentation for more information. - -After downloading ``Indy-Severe-Weather.tgz`` using one of the three methods above, untar the downloaded compressed archive file: - -.. code-block:: console - - tar xvfz Indy-Severe-Weather.tgz - -Record the path to this file output using the ``pwd`` command: - -.. code-block:: console - - cd Indy-Severe-Weather - pwd - -.. note:: - - Users can untar the fix files and Natural Earth files by substituting those file names in the commands above. - -Load the Regional Workflow -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First, navigate to the ``ufs-srweather-app/ush`` directory. Then, load the regional workflow environment: - -.. code-block:: console - - source - module use - module load wflow_ - -Users running a csh/tcsh shell would run ``source `` in place of the first command above. - -After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate regional_workflow``. - -Configure the Verification Sample Case -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Once the regional workflow is loaded, copy the out-of-the-box configuration: - -.. code-block:: console - - cd - cp config.community.yaml config.yaml - -where ```` is replaced by the actual path to the ``ufs-srweather-app/ush`` directory on the user's system. - -Then, edit the configuration file (``config.yaml``) to include the variables and values in the sample configuration excerpt below (variables not listed below do not need to be changed or removed). Users must be sure to substitute values in ``<>`` with values appropriate to their system. - -.. note:: - Users working on a `Level 1 platform `__ do not need to add or update the following variables: ``MET_INSTALL_DIR``, ``METPLUS_PATH``, ``MET_BIN_EXEC``, ``CCPA_OBS_DIR``, ``MRMS_OBS_DIR``, and ``NDAS_OBS_DIR`` - -.. code-block:: console - - user: - ACCOUNT: - platform: - MODEL: FV3_GFS_v16_SUBCONUS_3km - MET_INSTALL_DIR: # Example: MET_INSTALL_DIR: /contrib/met/10.1.1 - METPLUS_PATH: # Example: METPLUS_PATH: /contrib/METplus/METplus-4.1.1 - # Add MET_BIN_EXEC variable to config.yaml - MET_BIN_EXEC: bin - CCPA_OBS_DIR: - MRMS_OBS_DIR: - NDAS_OBS_DIR: - workflow: - EXPT_SUBDIR: - DATE_FIRST_CYCL: '2019061500' - DATE_LAST_CYCL: '2019061500' - FCST_LEN_HRS: 60 - workflow_switches: - RUN_TASK_VX_GRIDSTAT: true - RUN_TASK_VX_POINTSTAT: true - task_get_extrn_ics: - # Add EXTRN_MDL_SOURCE_BASEDIR_ICS variable to config.yaml - EXTRN_MDL_SOURCE_BASEDIR_ICS: - USE_USER_STAGED_EXTRN_FILES: true - task_get_extrn_lbcs: - # Add EXTRN_MDL_SOURCE_BASEDIR_LBCS variable to config.yaml - EXTRN_MDL_SOURCE_BASEDIR_LBCS: - USE_USER_STAGED_EXTRN_FILES: true - task_run_fcst: - WTIME_RUN_FCST: 05:00:00 - PREDEF_GRID_NAME: SUBCONUS_Ind_3km - -.. hint:: - To open the configuration file in the command line, users may run the command: - - .. code-block:: console - - vi config.yaml - - To modify the file, hit the ``i`` key and then make any changes required. To close and save, hit the ``esc`` key and type ``:wq``. Users may opt to use their preferred code editor instead. - -For additional configuration guidance, refer to :numref:`Section %s `. - -Generate the Experiment -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Generate the experiment by running this command from the ``ush`` directory: - -.. code-block:: console - - ./generate_FV3LAM_wflow.py - -Run the Experiment -^^^^^^^^^^^^^^^^^^^^^ - -Navigate (``cd``) to the experiment directory (``$EXPTDIR``) and run the launch script: - -.. code-block:: console - - ./launch_FV3LAM_wflow.sh - -Run the launch script regularly and repeatedly until the experiment completes. - -To check progress, run: - -.. code-block:: console - - tail -n 40 log.launch_FV3LAM_wflow - -Users who prefer to automate the workflow via :term:`crontab` or who need guidance for running without the Rocoto workflow manager should refer to :numref:`Section %s ` for these options. - -If a problem occurs and a task goes DEAD, view the task log files in ``$EXPTDIR/log`` to determine the problem. Then refer to :numref:`Section %s ` to restart a DEAD task once the problem has been resolved. For troubleshooting assistance, users are encouraged to post questions on the new SRW App `GitHub Discussions `__ Q&A page. - -Generate Plots -^^^^^^^^^^^^^^^^^ - -The plots are created using the graphics generation script that comes with the SRW App v2.1.0 release. Information on the plots and instructions on how to run the script can be found in :doc:`Chapter 12 ` of the v2.1.0 release documentation. If the python environment is already loaded (i.e., ``(regional_workflow)`` is visible in the command prompt), users can navigate to the directory with the plotting scripts and run ``plot_allvars.py``: - -.. code-block:: console - - cd - python plot_allvars.py 2019061500 0 60 6 / SUBCONUS_Ind_3km - -Compare ----------- - -Once the experiment has completed (i.e., all tasks have "SUCCEEDED" and the end of the ``log.launch_FV3LAM_wflow`` file lists "Workflow status: SUCCESS"), users can compare their forecast results against the forecast results provided in the ``Indy-Severe-Weather`` directory downloaded in :numref:`Section %s `. This directory contains the forecast output and plots from NOAA developers under the ``postprd`` directory and METplus verification files under the ``metprd`` directory. - -Qualitative Comparison of the Plots -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Comparing the plots is relatively straightforward since they are in ``.png`` format, and most computers can render them in their default image viewer. :numref:`Table %s ` lists plots that are available every 6 hours of the forecast (where ``hhh`` is replaced by the three-digit forecast hour): - -.. _AvailablePlots: - -.. table:: Sample Indianapolis Forecast Plots - - +-----------------------------------------+-----------------------------------+ - | Field | File Name | - +=========================================+===================================+ - | Sea level pressure | slp_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Surface-based CAPE/CIN | sfcape_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | 2-meter temperature | 2mt_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | 2-meter dew point temperature | 2mdew_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | 10-meter winds | 10mwind_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | 250-hPa winds | 250wind_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | 500-hPa heights, winds, and vorticity | 500_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Max/Min 2 - 5 km updraft helicity | uh25_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Composite reflectivity | refc_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - | Accumulated precipitation | qpf_regional_fhhh.png | - +-----------------------------------------+-----------------------------------+ - -Users can visually compare their plots with the plots produced by NOAA developers to see how close they are. - -Quantitative Forecast Comparision -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -METplus verification ``.stat`` files provide users the opportunity to compare their model run with a baseline using quantitative measures. The file format is ``(grid|point)_stat_PREFIX_HHMMSSL_YYYYMMDD_HHMMSSV.stat``, where PREFIX indicates the user-defined output prefix, HHMMSSL indicates the forecast *lead time*, and YYYYMMDD_HHMMSSV indicates the forecast *valid time*. For example, one of the ``.stat`` files for the 30th hour of a forecast starting at midnight (00Z) on June 15, 2019 would be: - -.. code-block:: console - - point_stat_FV3_GFS_v16_SUBCONUS_3km_NDAS_ADPSFC_300000L_20190616_060000V.stat - -The 30th hour of the forecast occurs at 6am (06Z) on June 16, 2019. The lead time is 30 hours (300000L in HHMMSSL format) because this is the 30th hour of the forecast. The valid time is 06Z (060000V in HHMMSSV format). - -The following is the list of METplus output files users can reference during the comparison process: - -.. code-block:: console - - # Point-Stat Files - point_stat_FV3_GFS_v16_SUBCONUS_3km_NDAS_ADPSFC_HHMMSSL_YYYYMMDD_HHMMSSV.stat - point_stat_FV3_GFS_v16_SUBCONUS_3km_NDAS_ADPUPA_HHMMSSL_YYYYMMDD_HHMMSSV.stat - - # Grid-Stat Files - grid_stat_FV3_GFS_v16_SUBCONUS_3km_REFC_MRMS_HHMMSSL_YYYYMMDD_HHMMSSV.stat - grid_stat_FV3_GFS_v16_SUBCONUS_3km_RETOP_MRMS_HHMMSSL_YYYYMMDD_HHMMSSV.stat - grid_stat_FV3_GFS_v16_SUBCONUS_3km_APCP_01h_CCPA_HHMMSSL_YYYYMMDD_HHMMSSV.stat - grid_stat_FV3_GFS_v16_SUBCONUS_3km_APCP_03h_CCPA_HHMMSSL_YYYYMMDD_HHMMSSV.stat - grid_stat_FV3_GFS_v16_SUBCONUS_3km_APCP_06h_CCPA_HHMMSSL_YYYYMMDD_HHMMSSV.stat - grid_stat_FV3_GFS_v16_SUBCONUS_3km_APCP_24h_CCPA_HHMMSSL_YYYYMMDD_HHMMSSV.stat - - -Point STAT Files -``````````````````` - -The Point-Stat files contain continuous variables like temperature, pressure, and wind speed. A description of the Point-Stat file can be found :ref:`here ` in the MET documentation. - -The Point-Stat files contain a potentially overwhelming amount of information. Therefore, it is recommended that users focus on the CNT MET test, which contains the `RMSE `__ and `MBIAS `__ statistics. The MET tests are defined in column 24 'LINE_TYPE' of the ``.stat`` file. Look for 'CNT' in this column. Then find column 66-68 for MBIAS and 78-80 for RMSE statistics. A full description of this file can be found `here `__. - -To narrow down the variable field even further, users can focus on these weather variables: - - * 250 mb - wind speed, temperature - * 500 mb - wind speed, temperature - * 700 mb - wind speed, temperature, relative humidity - * 850 mb - wind speed, temperature, relative humidity - * Surface - wind speed, temperature, pressure, dewpoint - -**Interpretation:** - -* A lower RMSE indicates that the model forecast value is closer to the observed value. -* If MBIAS > 1, then the value for a given forecast variable is too high on average by (MBIAS - 1)%. If MBIAS < 1, then the forecasted value is too low on average by (1 - MBIAS)%. - -Grid-Stat Files -```````````````````` - -The Grid-Stat files contain gridded variables like reflectivity and precipitation. A description of the Grid-Stat file can be found :ref:`here `. - -As with the Point-Stat file, there are several MET tests and statistics available in the Grid-Stat file. To simplify this dataset users can focus on the MET tests and statistics found in :numref:`Table %s ` below. The MET tests are found in column 24 ‘LINE_TYPE’ of the Grid-Stat file. The table also shows the user the columns for the statistics of interest. For a more detailed description of the Grid-Stat files, view the :ref:`MET Grid-Stat Documentation `. - -.. _GridStatStatistics: - -.. table:: Grid-Stat Statistics - - +----------------+----------+-----------------+----------------------+ - | File Type | MET Test | Statistic | Statistic Column | - +================+==========+=================+======================+ - | APCP | NBRCTS | FBIAS | 41-43 | - +----------------+----------+-----------------+----------------------+ - | APCP | NBRCNT | FSS | 29-31 | - +----------------+----------+-----------------+----------------------+ - | REFC and RETOP | NBRCTS | FBIAS, FAR, CSI | 41-43, 59-63, 64-68 | - +----------------+----------+-----------------+----------------------+ - -**Interpretation:** - -* If FBIAS > 1, then the event is over forecast, meaning that the prediction for a particular variable (e.g., precipitation, reflectivity) was higher than the observed value. If FBIAS < 1, then the event is under forecast, so the predicted value was lower than the observed value. If FBIAS = 1, then the forecast matched the observation. -* FSS values > 0.5 indicate a useful score. FSS values range from 0 to 1, where 0 means that there is no overlap between the forecast and observation, and 1 means that the forecast and observation are the same (complete overlap). -* FAR ranges from 0 to 1; 0 indicates a perfect forecast, and 1 indicates no skill in the forecast. -* CSI ranges from 0 to 1; 1 indicates a perfect forecast, and 0 represents no skill in the forecast. diff --git a/docs/UsersGuide/source/WE2Etests.rst b/docs/UsersGuide/source/WE2Etests.rst deleted file mode 100644 index 185faa777d..0000000000 --- a/docs/UsersGuide/source/WE2Etests.rst +++ /dev/null @@ -1,412 +0,0 @@ -.. _WE2E_tests: - -================================== -Workflow End-to-End (WE2E) Tests -================================== -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 from start to finish. 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 (:term:`J-jobs`, -:term:`ex-scripts`), and other auxiliary scripts to ensure that these scripts function correctly. Tested 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. Currently, it is up to the external repositories that the App clones (:numref:`Section %s `) to check that changes to those repositories 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.) - -WE2E tests are grouped into two categories that are of interest to code developers: ``fundamental`` and ``comprehensive`` tests. "Fundamental" tests are a lightweight but wide-reaching set of tests designed to function as a cheap "`smoke test `__ for changes to the UFS SRW App. The fundamental suite of test runs common combinations of workflow tasks, physical domains, input data, physics suites, etc. -The comprehensive suite of tests covers a broader range of combinations of capabilities, configurations, and components, ideally including all capabilities that *can* be run on a given platform. Because some capabilities are not available on all platforms (*e.g.*, retrieving data directly from NOAA HPSS), the suite of comprehensive tests varies from machine to machine. -The list of fundamental and comprehensive tests can be viewed in the ``ufs-srweather-app/tests/WE2E/machine_suites/`` directory, and are described in more detail in :doc:`this table `. - -.. note:: - - There are two additional test suites, ``coverage`` (designed for automated testing) and ``all`` (includes *all* tests, including those known to fail). Running these suites is **not recommended**. - -For convenience, the WE2E tests are currently grouped into the following categories (under ``ufs-srweather-app/tests/WE2E/test_configs/``): - -* ``default_configs`` - This category tests example config files provided for user reference. They are symbolically linked from the ``ufs-srweather-app/ush/`` directory. - -* ``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 input data from different external models. Note that in community mode, all output from the Application 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 input data from different external models. Note that in NCO mode, an operational run environment is used. This involves a specific directory structure and variable names (see :numref:`Section %s `). - -* ``verification`` - This category specifically tests the various combinations of verification capabilities using METPlus. - -* ``release_SRW_v1`` - This category was reserved for the official "Graduate Student Test" case for the Version 1 SRW code release. - -* ``wflow_features`` - This category of tests ensures that the workflow completes successfully with particular features/capabilities activated. - -Some tests are duplicated among the above categories via symbolic links, both for legacy reasons (when tests for different capabilities were consolidated) and for convenience when a user would like to run all tests for a specific category (*e.g.* verification tests). - -The script to run the WE2E tests is named ``run_WE2E_tests.py`` and is located in the directory ``ufs-srweather-app/tests/WE2E``. Each WE2E test has an associated configuration file named ``config.${test_name}.yaml``, where ``${test_name}`` is the name of the corresponding test. These configuration files are subsets of the full range of ``config.yaml`` experiment configuration options. (See :numref:`Chapter %s ` for all configurable options and :numref:`Section %s ` for information on configuring ``config.yaml``.) For each test, the ``run_WE2E_tests.py`` script reads in the test configuration file and generates from it a complete ``config.yaml`` file. It then calls the ``generate_FV3LAM_wflow()`` function, which in turn reads in ``config.yaml`` 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.yaml`` for each test is placed in its experiment directory. - -As with any other experiment within the App, the -Python modules required for experiment generation must be loaded before ``run_WE2E_tests.py`` -can be called. See :numref:`Section %s ` for information on loading the Python -environment on supported platforms. Note also that ``run_WE2E_tests.py`` assumes that all of -the executables have been built (see :numref:`Section %s `). If they have not, then ``run_WE2E_tests.py`` will still generate the experiment directories, but the workflows will fail. - -.. note:: - - The full list of WE2E tests is extensive and some larger, high-resolution tests are computationally expensive. Estimates of walltime and core-hour cost for each test are provided in :doc:`this table `. - -Running the WE2E Tests -================================ - -Users may specify the set of tests to run in one of three ways. First, users can pass the name of a single test or list of tests to the script. Secondly, they can pass an option to run the ``fundamental`` or ``comprehensive`` suite of tests. Finally, users can create a text file, such as ``my_tests.txt``, which contains a list of the WE2E tests to run (one per line). Any one of these options can be passed to the ``run_WE2E_tests.py`` script via the ``--tests`` or ``-t`` option. - -For example, to run the tests ``custom_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 commands from the ``WE2E`` working directory (``ufs-srweather-app/tests/WE2E/``): - -.. code-block:: console - - echo "custom_ESGgrid" > my_tests.txt - echo "grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16" >> my_tests.txt - -For each specified test, ``run_WE2E_tests.py`` will generate a new experiment directory and, by default, launch a second function ``monitor_jobs()`` that will continuously monitor active jobs, submit new jobs, and track the success or failure status of the experiment in a ``.yaml`` file. Finally, when all jobs have finished running (successfully or not), the function ``print_WE2E_summary()`` will print a summary of the jobs to screen, including the job's success or failure, timing information, and (if on an appropriately configured platform) the number of core hours used. An example run would look like this: - -.. code-block:: console - - $ ./run_WE2E_tests.py -t my_tests.txt -m hera -a gsd-fv3 -q - Checking that all tests are valid - Will run 2 tests: - /user/home/ufs-srweather-app/tests/WE2E/test_configs/wflow_features/config.custom_ESGgrid.yaml - /user/home/ufs-srweather-app/tests/WE2E/test_configs/grids_extrn_mdls_suites_community/config.grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.yaml - Calling workflow generation function for test custom_ESGgrid - - Workflow for test custom_ESGgrid successfully generated in - /user/home/expt_dirs/custom_ESGgrid - - Calling workflow generation function for test grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - - Workflow for test grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 successfully generated in - /user/home/expt_dirs/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - - calling function that monitors jobs, prints summary - Writing information for all experiments to WE2E_tests_20230418174042.yaml - Checking tests available for monitoring... - Starting experiment custom_ESGgrid running - Updating database for experiment custom_ESGgrid - Starting experiment grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 running - Updating database for experiment grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - Setup complete; monitoring 2 experiments - Use ctrl-c to pause job submission/monitoring - Experiment custom_ESGgrid is COMPLETE - Took 0:19:29.877497; will no longer monitor. - Experiment grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 is COMPLETE - Took 0:29:38.951777; will no longer monitor. - All 2 experiments finished - Calculating core-hour usage and printing final summary - ---------------------------------------------------------------------------------------------------- - Experiment name | Status | Core hours used - ---------------------------------------------------------------------------------------------------- - custom_ESGgrid COMPLETE 18.02 - grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 COMPLETE 15.52 - ---------------------------------------------------------------------------------------------------- - Total COMPLETE 33.54 - - Detailed summary written to /user/home/expt_dirs/WE2E_summary_20230418181025.txt - - All experiments are complete - Summary of results available in WE2E_tests_20230418174042.yaml - -.. note:: - - These examples assume that the user has already built the SRW App and loaded the appropriate python environment as described in :numref:`Section %s `. - -As the script runs, detailed debug output is written to the file ``log.run_WE2E_tests``. This can be useful for debugging if something goes wrong. You can also use the ``-d`` flag to print all this output to screen during the run, but this can get quite cluttered. - -The final job summary is written by the ``print_WE2E_summary()``; this prints a short summary of experiments to screen, and prints a more detailed summary of all jobs for all experiments in the indicated ``.txt`` file. - -.. code-block:: console - - $ cat /user/home/expt_dirs/WE2E_summary_20230418181025.txt - ---------------------------------------------------------------------------------------------------- - Experiment name | Status | Core hours used - ---------------------------------------------------------------------------------------------------- - custom_ESGgrid COMPLETE 18.02 - grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 COMPLETE 15.52 - ---------------------------------------------------------------------------------------------------- - Total COMPLETE 33.54 - - Detailed summary of each experiment: - - ---------------------------------------------------------------------------------------------------- - Detailed summary of experiment custom_ESGgrid - in directory /user/home/expt_dirs/custom_ESGgrid - | Status | Walltime | Core hours used - ---------------------------------------------------------------------------------------------------- - make_grid_201907010000 SUCCEEDED 13.0 0.09 - get_extrn_ics_201907010000 SUCCEEDED 10.0 0.00 - get_extrn_lbcs_201907010000 SUCCEEDED 6.0 0.00 - make_orog_201907010000 SUCCEEDED 65.0 0.43 - make_sfc_climo_201907010000 SUCCEEDED 39.0 0.52 - make_ics_mem000_201907010000 SUCCEEDED 120.0 1.60 - make_lbcs_mem000_201907010000 SUCCEEDED 201.0 2.68 - run_fcst_mem000_201907010000 SUCCEEDED 340.0 11.33 - run_post_mem000_f000_201907010000 SUCCEEDED 11.0 0.15 - run_post_mem000_f001_201907010000 SUCCEEDED 13.0 0.17 - run_post_mem000_f002_201907010000 SUCCEEDED 16.0 0.21 - run_post_mem000_f003_201907010000 SUCCEEDED 16.0 0.21 - run_post_mem000_f004_201907010000 SUCCEEDED 16.0 0.21 - run_post_mem000_f005_201907010000 SUCCEEDED 16.0 0.21 - run_post_mem000_f006_201907010000 SUCCEEDED 16.0 0.21 - ---------------------------------------------------------------------------------------------------- - Total COMPLETE 18.02 - - ---------------------------------------------------------------------------------------------------- - Detailed summary of experiment grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - in directory /user/home/expt_dirs/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - | Status | Walltime | Core hours used - ---------------------------------------------------------------------------------------------------- - make_grid_201907010000 SUCCEEDED 8.0 0.05 - get_extrn_ics_201907010000 SUCCEEDED 5.0 0.00 - get_extrn_lbcs_201907010000 SUCCEEDED 11.0 0.00 - make_orog_201907010000 SUCCEEDED 49.0 0.33 - make_sfc_climo_201907010000 SUCCEEDED 41.0 0.55 - make_ics_mem000_201907010000 SUCCEEDED 83.0 1.11 - make_lbcs_mem000_201907010000 SUCCEEDED 199.0 2.65 - run_fcst_mem000_201907010000 SUCCEEDED 883.0 9.81 - run_post_mem000_f000_201907010000 SUCCEEDED 10.0 0.13 - run_post_mem000_f001_201907010000 SUCCEEDED 11.0 0.15 - run_post_mem000_f002_201907010000 SUCCEEDED 10.0 0.13 - run_post_mem000_f003_201907010000 SUCCEEDED 11.0 0.15 - run_post_mem000_f004_201907010000 SUCCEEDED 11.0 0.15 - run_post_mem000_f005_201907010000 SUCCEEDED 11.0 0.15 - run_post_mem000_f006_201907010000 SUCCEEDED 12.0 0.16 - ---------------------------------------------------------------------------------------------------- - Total COMPLETE 15.52 - - -One might have noticed the line during the experiment run that reads "Use ctrl-c to pause job submission/monitoring". The ``monitor_jobs()`` function (called automatically after all experiments are generated) is designed to be easily paused and re-started if necessary. If you wish to stop actively submitting jobs, simply quitting the script using "ctrl-c" will stop the function, and give a short message on how to continue the experiment. - -.. code-block:: console - - Setup complete; monitoring 1 experiments - Use ctrl-c to pause job submission/monitoring - ^C - - - User interrupted monitor script; to resume monitoring jobs run: - - ./monitor_jobs.py -y=WE2E_tests_20230418174042.yaml -p=1 - -The full list of options for any of these scripts can be found by using the ``-h`` flag. The examples below demonstrate several of the more common options for ``run_WE2E_tests.py``. - -#. To run the tests listed in ``my_tests.txt`` on Hera and charge the computational - resources used to the "rtrr" account: - - .. code-block:: - - ./run_WE2E_tests.py --tests=my_tests.txt --machine=hera --account=rtrr - - This will create the experiment subdirectories for the two sample WE2E tests in the directory ``${HOMEdir}/../expt_dirs``, where ``HOMEdir`` is the top-level directory for the ufs-srweather-app repository (usually set to something like ``/path/to/ufs-srweather-app``). Thus, the following two experiment directories will be created: - - .. code-block:: - - ${HOMEdir}/../expt_dirs/custom_ESGgrid - ${HOMEdir}/../expt_dirs/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - - Once these experiment directories are created, the script will call the ``monitor_jobs()`` function. This function runs ``rocotorun`` in the background to monitor the status of jobs in each experiment directory, tracking the status of jobs as they run and complete, and submitting new jobs when they are ready. The progress of ``monitor_jobs()`` is tracked in a file ``WE2E_tests_{datetime}.yaml``, where {datetime} is the date and time (in ``yyyymmddhhmmss`` format) that the file was created. - -#. Our second example will run the fundamental suite of tests on Orion, charging computational resources to the "gsd-fv3" account, and placing the experiment subdirectories in a subdirectory named ``test_set_01``: - - .. code-block:: - - ./run_WE2E_tests.py -t fundamental -m hera -a gsd-fv3 --expt_basedir "test_set_01" -q - - In this case, the full paths to the experiment directories will be: - - .. code-block:: - - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta - ${HOMEdir}/../expt_dirs/test_set_01/nco_grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_timeoffset_suite_GFS_v16 - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v15p2 - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v17_p8 - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_HRRR_suite_HRRR - ${HOMEdir}/../expt_dirs/test_set_01/grid_SUBCONUS_Ind_3km_ics_HRRR_lbcs_RAP_suite_WoFS_v0 - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUS_25km_ics_NAM_lbcs_NAM_suite_GFS_v16 - - - The ``--expt_basedir`` option is useful for grouping various sets of tests. It can also be given a full path as an argument, which will place experiments in the given location. - - The ``-q`` flag (as used in the first example shown above), is helpful for keeping the screen less cluttered; this will suppress the output from ``generate_FV3LAM_wflow()``, only printing important messages (warnings and errors) to screen. As always, this output will still be available in the ``log.run_WE2E_tests`` file. - -#. By default, the job monitoring and submission process is serial, using a single task. For test suites that contain many experiments, this means that the script may take a long time to return to a given experiment and submit the next job, due to the amount of time it takes for the ``rocotorun`` command to complete. In order to speed this process up, provided you have access to a node with the appropriate availability (e.g., submitting from a compute node), you can run the job monitoring processes in parallel using the ``-p`` option: - - .. code-block:: - - ./run_WE2E_tests.py -m=jet -a=gsd-fv3-dev -t=all -q -p 6 - - Depending on your machine settings, this can reduce the time it takes to run all experiments substantially. However, it should be used with caution on shared resources (such as HPC login nodes) due to the potential to overwhelm machine resources. - -#. This example will run the single experiment "custom_ESGgrid" on Hera, charging computational resources to the "fv3lam" account. For this example, we submit the suite of tests using the legacy :term:`cron`-based system: - -.. note:: - - This option is not recommended, as it does not work on some machines and can cause system bottlenecks on others. - - .. code-block:: - - ./run_WE2E_tests.py -t=custom_ESGgrid -m=hera -a=fv3lam --use_cron_to_relaunch --cron_relaunch_intvl_mnts=1 - -The option ``--use_cron_to_relaunch`` means that, rather than calling the ``monitor_jobs()`` function, the ``generate_FV3LAM_wflow()`` function will create a new :term:`cron` job in the user's cron table that will launch the experiment with the workflow launch script (``launch_FV3LAM_wflow.sh``). By default this script is run every 2 minutes, but we have changed that to 1 minute with the ``--cron_relaunch_intvl_mnts=1`` argument. This script will run until the workflow either completes successfully (i.e., all tasks SUCCEEDED) or fails (i.e., at least one task fails). The cron job is then removed from the user's cron table. - - -Checking test status and summary -================================= -By default, ``./run_WE2E_tests.py`` will actively monitor jobs, printing to screen when jobs are complete (either successfully or with a failure), and print a summary file ``WE2E_summary_{datetime.now().strftime("%Y%m%d%H%M%S")}.txt``. -However, if the user is using the legacy crontab option, or would like to summarize one or more experiments that are either not complete or were not handled by the WE2E test scripts, this status/summary file can be generated manually using ``WE2E_summary.py``. -In this example, an experiment was generated using the crontab option, and has not yet finished running. -We use the ``-e`` option to point to the experiment directory and get the current status of the experiment: - - .. code-block:: - - ./WE2E_summary.py -e /user/home/PR_466/expt_dirs/ - Updating database for experiment grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_HRRR_suite_RRFS_v1beta - Updating database for experiment grid_RRFS_CONUS_25km_ics_GSMGFS_lbcs_GSMGFS_suite_GFS_v16 - Updating database for experiment grid_RRFS_CONUS_3km_ics_FV3GFS_lbcs_FV3GFS_suite_HRRR - Updating database for experiment specify_template_filenames - Updating database for experiment grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_RAP_suite_HRRR - Updating database for experiment grid_RRFS_CONUScompact_3km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta - Updating database for experiment grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_2017_gfdlmp_regional - Updating database for experiment grid_SUBCONUS_Ind_3km_ics_HRRR_lbcs_RAP_suite_HRRR - Updating database for experiment grid_RRFS_CONUS_3km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - Updating database for experiment grid_RRFS_SUBCONUS_3km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - Updating database for experiment specify_DOT_OR_USCORE - Updating database for experiment custom_GFDLgrid__GFDLgrid_USE_NUM_CELLS_IN_FILENAMES_eq_FALSE - Updating database for experiment grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - ---------------------------------------------------------------------------------------------------- - Experiment name | Status | Core hours used - ---------------------------------------------------------------------------------------------------- - grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_HRRR_suite_RRFS_v1 COMPLETE 49.72 - grid_RRFS_CONUS_25km_ics_GSMGFS_lbcs_GSMGFS_suite_GFS_v16 DYING 6.51 - grid_RRFS_CONUS_3km_ics_FV3GFS_lbcs_FV3GFS_suite_HRRR COMPLETE 411.84 - specify_template_filenames COMPLETE 17.36 - grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_RAP_suite_HRRR COMPLETE 16.03 - grid_RRFS_CONUScompact_3km_ics_HRRR_lbcs_RAP_suite_RRFS_v1be COMPLETE 318.55 - grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_2017_g COMPLETE 17.79 - grid_SUBCONUS_Ind_3km_ics_HRRR_lbcs_RAP_suite_HRRR COMPLETE 17.76 - grid_RRFS_CONUS_3km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 RUNNING 0.00 - grid_RRFS_SUBCONUS_3km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 RUNNING 0.00 - specify_DOT_OR_USCORE QUEUED 0.00 - custom_GFDLgrid__GFDLgrid_USE_NUM_CELLS_IN_FILENAMES_eq_FALS QUEUED 0.00 - grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS QUEUED 0.00 - ---------------------------------------------------------------------------------------------------- - Total RUNNING 855.56 - - Detailed summary written to WE2E_summary_20230306173013.txt - -As with all python scripts in the App, additional options for this script can be viewed by calling with the ``-h`` argument. - - -.. _WE2ETestInfoFile: - -WE2E Test Information File -================================== - -If the user wants to see consolidated test information, they can generate a file that can be imported into a spreadsheet program (Google Sheets, Microsoft Excel, etc.) that summarizes each test. This file, named ``WE2E_test_info.txt`` by default, is delimited by the ``|`` character, and can be created either by running the ``./print_test_info.py`` script, or by generating an experiment using ``./run_WE2E_tests.py`` with the ``--print_test_info`` flag. - -The rows of the file/sheet represent the full set of available tests (not just the ones to be run). The columns contain the following information (column titles are included in the CSV file): - -| **Column 1** -| The primary test name followed (in parentheses) by the category subdirectory where it is - located. - -| **Column 2** -| Any alternate names for the test followed by their category subdirectories - (in parentheses). - -| **Column 3** -| The test description. - -| **Column 4** -| The relative cost of running the dynamics in the test. This gives an - idea of how expensive the test is relative to a reference test that runs - a single 6-hour forecast on the ``RRFS_CONUS_25km`` predefined grid using - its default time step (``DT_ATMOS: 40``). To calculate the relative cost, the absolute cost (``abs_cost``) is first calculated as follows: - -.. code-block:: - - abs_cost = nx*ny*num_time_steps*num_fcsts - -| Here, ``nx`` and ``ny`` are the number of grid points in the horizontal - (``x`` and ``y``) directions, ``num_time_steps`` is the number of time - steps in one forecast, and ``num_fcsts`` is the number of forecasts the - test runs (see Column 5 below). [Note that this cost calculation does - not (yet) differentiate between different physics suites.] The relative - cost ``rel_cost`` is then calculated using - -.. code-block:: - - rel_cost = abs_cost/abs_cost_ref - -| where ``abs_cost_ref`` is the absolute cost of running the reference forecast - described above, i.e., a single (``num_fcsts = 1``) 6-hour forecast - (``FCST_LEN_HRS = 6``) on the ``RRFS_CONUS_25km grid`` (which currently has - ``nx = 219``, ``ny = 131``, and ``DT_ATMOS = 40 sec`` (so that ``num_time_steps - = FCST_LEN_HRS*3600/DT_ATMOS = 6*3600/40 = 540``). Therefore, the absolute cost reference is calculated as: - -.. code-block:: - - abs_cost_ref = 219*131*540*1 = 15,492,060 - -| **Column 5** -| The number of times the forecast model will be run by the test. This - is calculated using quantities such as the number of :term:`cycle` dates (i.e., - forecast model start dates) and the number of ensemble members (which - is greater than 1 if running ensemble forecasts and 1 otherwise). The - number of cycle dates and/or ensemble members is derived from the quantities listed - in Columns 6, 7, .... - -| **Columns 6, 7, ...** -| The values of various experiment variables (if defined) in each test's - configuration file. Currently, the following experiment variables are - included: - - | ``PREDEF_GRID_NAME`` - | ``CCPP_PHYS_SUITE`` - | ``EXTRN_MDL_NAME_ICS`` - | ``EXTRN_MDL_NAME_LBCS`` - | ``DATE_FIRST_CYCL`` - | ``DATE_LAST_CYCL`` - | ``INCR_CYCL_FREQ`` - | ``FCST_LEN_HRS`` - | ``DT_ATMOS`` - | ``LBC_SPEC_INTVL_HRS`` - | ``NUM_ENS_MEMBERS`` - - -Modifying the WE2E System -============================ -This section describes various ways in which the WE2E testing system can be modified -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 -in the header of the file. - - -.. _AddNewTest: - -Adding a New Test ---------------------- -To add a new test named, e.g., ``new_test01``, to one of the existing test categories, such as ``wflow_features``: - -#. 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.yaml`` and, if necessary, move it to the ``wflow_features`` category directory. - -#. Edit the header comments in ``config.new_test01.yaml`` so that they properly describe the new test. - -#. Edit the contents of ``config.new_test01.yaml`` by modifying existing experiment variable values and/or adding new variables such that the test runs with the intended configuration. - - diff --git a/docs/UsersGuide/source/_static/JenkinsCICD.png b/docs/UsersGuide/source/_static/JenkinsCICD.png deleted file mode 100644 index 48c30bde1a7e267cf69c3b13ee3f514b22284e2b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 86714 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%0Al_>o4(;#k*IOfc%I4;FWCunGjHy|N78HdM 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

p-njJJ-!{vE8UDsbBhpumS8=9PvA76 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 diff --git a/docs/UsersGuide/source/_static/RRFS_CONUS_13km.sphr.native_wrtcmp.png b/docs/UsersGuide/source/_static/RRFS_CONUS_13km.sphr.native_wrtcmp.png deleted file mode 100644 index 2d1ed25b6859866af89144e9da6e76e9770fa16b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 104826 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

aU+^XLOf8+({CPFq&Y|Tl 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 XfBW_O>YJMd8Gyjk)z4*}Q$iB}iLZ@H diff --git a/docs/UsersGuide/source/_static/RRFS_CONUS_25km.sphr.native_wrtcmp.png b/docs/UsersGuide/source/_static/RRFS_CONUS_25km.sphr.native_wrtcmp.png deleted file mode 100644 index bc321d6d740cdd8f27c35d28a5d9c08aa975413f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 103357 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∓mdRA~wtp$^}`yU-_nGe|fsJ{5_ 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

B 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

yxXj={h4MpC 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

A`6BYnfba7$)scIC+I-ki=6* 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 z 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∋zw~hjcn?Ylp)6h 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

DGfq2Er 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%0A*q0}EHv-)x@mJHFH(ss#J|XhU&09F1@k7C zes$yZ%b;T55h$<%raB9i8_Pc<`0j`iXpb;afKTUMCK$2Em{Kh+JeI&9z6iM=HX63s zKM9A0E`V4XK^ksQiX*MT=4)6C zg9S3201zV5{BS7ayO17V85j?kC&bNmtvSZw4Sf-BaH#@!K&UlZf)7cwkO<>3gV(uf zB9hW~Qx=4S+9m9bdIcm?bbMnDg>hxE-q@EvU=2^Sd5aSA^qG>wwxs!@sp2IJJ+BBX!80bjf0d1v*59{Lmq_}kg zDN0NhYl`7qW8n(pEuV#KTeC61?Cyz3n5>|`YbdrTrc{6PFyojq14W5u|I++i1O4~q zJcx1Cu&5bxFOFyFD+>i2g9^wRm1Ihe^=`}zRVPN}mcjI0GPMM3x?1j@#x23ZFm=2D z)d{Yd%;_*>uQM|(Kl}T5JD+crGV={lMJkubtQ#_|p?Ht9HQbC^M}2Ij_YKz;N}xxq z`BRms`%`@0qGJa#oeQ32Zj6SzkmX_UnC%VkcbSCZe0^)_Jm)@ItDi=P@fukXX;sX0 zc33$o%HKF07$xTnc`^n`kR`^M&`B*J%oPE)9`2bKa#H+@!Fu_ zKWH4~M6oWPq=CE0#F4VcbsJOLfS_Em&-LA82|_t0lXlaGni*rAbM^PpUTWvI3)gMC zGC2hTH*aMyI__#fI62L|X?ybYMu*&cnPX2;&8iwEDqwuA0NhxY^^4Af?~9wWSRck` zV$p}tiYp;d=cMK;>_wB{{ah`RVLpLV9v|-x3CKy z0Z(R8H${YE{|(CoF7hJ25VT zt+h`spXyRBkZ}}y-$bcuqQyi$qp@Ok%I3-Vl>OK(IW~ZN`s(^le?TkB*f#ZJGA!A> z8T5m(^BfpY0hAPIOI9-a=d%91fFnFMKA2KAny~8UV3^&EDudov`iQcUe{6fx5@hxpS>REzp2|N@tnzjSXWoTH+H>A-tu%R&uCUxP4!5|H{?+}U~ zy|Nl!;|+(xRlI1S^<6}RHne#k-kz16%sR)R3`J*l@s4($0_zsvo7o=K3uNP54H&u8 z>Lw9;9xUZ__4A`kRzhi$k;g;`E!_Q+^9hF$;7%xD3FuP<6?w(@EPv!7j}~^+ImKok zf6j7j8aY>D^B|~_WW-E0kK-qDv#)C^l&&cz@wdm0*(FET%Q<~h83uP^Ux5-&h2}`+ z{xQ$G7A%t10Z&U*&NkHsCck{Ai?|p)`(ble?|!l*?tw-)>W(R-moDsyL2WPBM}I({ z*uqa%&-_S2LmVDzRxA|NqGDw=EIN~?P#5#5;8e1|-v?#NAq5nXP0T8b_- z*{g?-gNy)o9ThC8DNaQh^VTPk0~H-L80>{!!4O75pGNpOvCfGqpMnd8!It7NC!w*i z$vs_yHsIZ0W+*t5jyxrhz#F!~%xyH3zf!JIDVtaALU#mfyKS=QgEi?9J;xR-7SWj0 z(MpA252Sr~ekHt$QHLnuQ>N%>aw?0DytkwrcC?5+(}R>aCwbv)iqM%hUDGc^gh_xg zsoX!4rz72KF)2J^7yV3=J4k~mnm%c6=6}0vZQaH`R_z$S7gB*ZG3-ZN7l=LGeC(%k ztfZ%r>}6!Q+zTR3Ch#)@y^~{f&vdb5vCQ#HTePZCJEy37m zTULHgiG@5)4+rWojTZWtLfl-PG=b=7nn9ad$lQ)U7C1uwr<&kz;(6IceRlrUVZZy0 z4JXJEUZ^B~)gVv7wxK*nf~jH+#cG$JglHj6Z}{_1%-t&?P@Z9pn9wlI`F!A13wiT* zmZ*?W`n8ryKSs7)k@SbZw48iDrEy#J7(5GpEJjwYgEyG7O_M#r=$5gXZ2h=lq&dm~ zzF=ZZ2>b(a=&@O0HO9qpLGycRg@L8~<$~Tr@s9dYq%+$7dZ(8WF*@@EBKZy8A>xXW z%sVCdF1*^$c@mz=sV)}DbG;sqpP&62kR9XH0{<9sQhsi)JIpXe{=7p#B0Fw$88U9+ zhlpjJ>;?`R5UD&{jEZOL|?j6j=_oH3>OJuh_6AS{YDScCRi*m-U&0;VuyB-sr*3 zUe-(-*ORnY``|61fOw+5J$kne%x(`cjcTvc=@`xAPE+qISO{=#|5{Yh#hh}!8ZXy% z?OB8>BXV(8gt1Zm018686A^97ay-jp+`InRssh^+q%XmIrY`l88yS<5mzE50W(wYV zh>)rV^*#+6KYE>&FmKxL{;?FXEDuLGj}1!!M<*)(NEey8VhVN(1~^z^so+^p`WaX) z8|yUKru9qt)yp=(rHJ-l{}W_QW5QP1=8C3WQ5D{LR0<7I2}v2aXw67{cd4vot2Bcf z&{0aMM@EVvk?r!DW;?h(BC%m*0Vi9Tn0_}mOy3I@p8K00`Dl*MM}#*fMjNat@Lm_{ zaE|DeHfXgWqxA+ACrl5hts?MHarrS=oZ#WeiK!ki?)!Z1qnkVv=smODxiRp!Gq3Pm zusE-@rl8a@mBC)bEQLRrdtp8>eDL93rD{8r%5;_@+Ba@;<;5t07P3x)2JqUO|7kl@ zK-#+k6K$w>o03CDAM#@cZY6+*j-Uk(%Vvf8GhfNck=R0~#G`x=VgM(@sM`?=bfVoN zVR%AXIHO!l7|fz*f`m}BoeVNf0%EpnpiDrCZA36z_X7i5W66R{kK6WG{ROhkULAXg zRtG|^ZjF6)jf4WDV7XU4^bYdxZ7T9q_o99s>D1SvQSROPQbXMaq;&;98Kg69`Z1TM zM%OpVrYVJil9Tp(^*|GcZ3v@oWXT^GN;HrsmT9=p%o}`l#^1p4?v>Wrm z(S2Jf*N!8lU~QT@)#dFt_im3gPV;TikBK&*J8aLzgK$p@P=D~Si)m5F@mlh89<*4_ zn)?|Qi7xpAHJRyTCAX<3kt33+9_NgEQqUOrYn_-egiP%%a-}{3AZ||h8_c0K0R&(y zzwOx=-kqr_zQfh$!?&&Bf^3f~5nzZWz_Mp8qjHelto8}65vIQnP1Uxt{L`=k#rdqObSs9;SFRIMzMU~;7 zBm*w0lAMH-dA4RqIvf{ckw@o3{mL3O^P^z9!$AhL+ z)S;ggV`Ry@4Reij1(g*QbFI@l``-vVIHh=`Icb4+dL{urN}ikw4dRtI zTz{`(5E`vgHGqY;7BRoBw?4dEbmpyXQM$FPi#llkOU!yro05b1^?EV$5>H_xk2Ank z9_yE|V8C(6r)G|c9dmveJ?prh6qLUf7!_h>ue#?buy`}}c&?*Zd|)kktL!@X0Y~=) z@spnN&&jpH!6}^0tZ;{=fXc-H0{Rg6lO`U&&}ha21||`bqG)uH6z79)?D_%FXcWzn zY4c5At+{pasT7_Ou6!LB2TpLjdD@3!xxYUXyXGj$GyJd_*gmJz_gnNK7_P~^r{n-5 z59o7%St)bHv2=Ek)kmk_=)erCSV(WZz`zieDac5E^lBtc@SM|-kK@(&tP;IGLZ7z= zy(-IgReZxBd&F3=3t`RRV`A?As?29YNXJ58lf)`_O9-2g;>I`>+4D)u%QBi)44ly$ zgx4k&fSrAka3S;ir>Nqy86%O)+@K&jQ29lKXr`*KZ1M|Df|Gw_#dVC;P0Y~+W|o|Q zQ!*7*!>1Nj4AE%H+;=uq!GDq;uAp+t>uLB865I(KEIb5=$l7;Ch0w|YBa5|$lTMc| zrLK`>qC|oTq6LOb0&yBwVramOETLssF^KqpnBEspBTX~GIEG&>s-UH&G|%_=r;n`Y zBIC~U-k*4-SD2UoS(MDDoyeS;!mMjM!EZv zW|DLb_Aj>iRN)mPIBrv zk&V;blM9S2a~cizF_&G`MINFCe^n|9+7x6z5c$mWuR7GL&)KUF{R_P4MLIxNEo$&7 zN*Y?E0f79-!;IDJ4G{ zCszm59a-9+0%F+iEfOuRVoKxBy@-O->c`E6hufPw%eSZ{E$Q^IhW z_U|0Ow~v9a=uF-)@Q5Z~4m^#fM-)Mssqj#P+V){QP6)@bXahiWuMjJI=s z;Z^RSMK2_ZYtYxoScCY0)Ivq8$>f81pD!3%vwM6}839I|dJx<;_v`Hzk^iZkS3_0? zRu7sy!3^9b)vuz+L&Kh?iy0n<&Ted<<`^+e9;>`y?f#QGUF;{=?GPX%?@xS@H#tx7 zAmfAD{(g|jw`kX4k+2OAGhBlRAlGQ_TCmGm6CGr0cs@~m1^~DgB+02x()({ixTi$w z1pygrCa$W0X;+BOuo}CVjppu%P~d4uvzQlbDO1qNuV!-O_oq6m$Te*`ZKB7Y9T)%b zoKLn_N+&dNU^FZ~^M1}L3Nn6#@Wct@c{@}_cA1jc4D*(TNFZdW!tb@ny@oii%VYoh z2L~+B>8Qczk-pAz{@=q`$ja~`>I-Edt_IZq^95KLFu(zN7}hth3rYX?JiwEHzrk?w zM?$a)`@c^W3>?4>CW!d27r^~_4O(pTNf-a?1qgJn2T&wpUY8*L&pZ9k+pwj?8hzkV zkGKEtQ{lcIK*%3_R}sX+3KugbE-;$?&y$Yhz?tgim8`^C|Ihz4gAqYWH}B_hY{Y*(PW$@! z|NqZ7FrS)ja&%jQTq$v zHnIm~De3#LnBEd@0C9Dns~a$mWW5?XCSJcG4tJbdvfJlEI}TWvo`H&cc8crQ z?!EC0pzc`~D|Y?%g5lrT+yedW#>B+3bzV-w{cUr1r-`wH4l%+F{_E7OYV&$ZJZMYy z)i-v~)(M2_1S$8s6faAs^;2RK>wrFXpLoh!?i!$B3Z>t_vY~=rfWwDE`;P$CvFhN} zLTtGDByjwrC=>Vy?$Mft!&9ZV`q0=7E&><9{{{(-v)RRdWJ8;NI|p88Sygx5jyjqG zQZXk$OuM;f_$p+-1`PFOGaGh-*W=u7`geE3;zrJso0xzJb$^gO@G|tQ_8nFR6Wq_4 za0EE!&>mvz>=~oyt8}p6IS>dpysCpB8TVi&?N&vg(z3g=;`EgcbUVb~qVFW2Z18ScKRCSHn+71g}QzIr0 zR$E-m7rPca&pmt|F#+0b)!C)F57r&vl$tBw4g8kUV31J4Dgybb<_KK&Ag^dT*{;sH z61I6;q>}6@p6#(cV3!f|Z_}&8wfS|z(Y}|a-?UqZO6=p<|+Su?p0x+e!7*c^Kl(KISgPcjgOd&kMGH$E%J+=;;+17 zK4Mq`hXf4f2no&N_7#bz+{eJH5&DA|z}r=QuI~hpHOC*5P4hcf*UuNk0Ex(mV{c0> zFr4iLC|phs+qpG%T!gWYuTuQmLR!qahS~!>+Or~xr$fY5b7@Kr6@+mPpntNI4Tei) z$vSg%a?9!(724A~@B@O5=2tKMiUsW$8S~zVgc5@;Fy%C~r&Q7U=HJC^u#I{K;6|2O z7Y)7Ed6}&&``<;7&eGW{KHujfi85feSmsSx_)MU#0Pw;Ya^J%ONY$-Ig6~HyqISNa z1X}9+^KTxNorA1SGupb^FZ#}%9^}f6Uo4hKlUo+MZX0v#>FxcT*e8n|=Yv32gsS!jJm&TEFyZ7`FQV0gfeUU2 z$h&BxufCX3F9q!GNsp>O-!JIF`tA4oSy>grz+UfX_S$Z+_BQFV}{irW&gnw9bq z+#S>oFi{#u)^ifpf$(Hyv16Y%=bFY>>9LToli{T__U#(Rj;xN3!D3lRTiS^s*w@Fe zleLQ-1NKXCNbNsJeP#C^tMkahEZ}s`cjJWENPPlLyt*6jNj(fbQD2~A=0Ig_+I;2j z`dmn5TAwO|;fkhfSo->}t4inB=dA)QHZbQbMMTSI;VCgyekWIflJpt+phSTRS zlch3_wq9#4!;{Xaj~>;2>y-_wcff7^j#;lHjz-VWFV5beh&8wF75I8a4e+5SFGsIW zkHq~Ka779H9QkIzLVLSo$CMJid~7u376%}pJo~XB!EbF>sN1hQBU@083|Fx`DqA4~ zs^9)&6a1R~;8QsrM8tjE^xM3Gl_pvRY`Nn_$?*vxv_5xZAaPHYQsa{{Tvjm$RMf?l zlV5=mypj$Yr(<->ar7=$sCD`#TT;);sD)u^c=xl~cfNv44PPGeYC7F7UHJ~W z^~W>@u*`0{(CZPkz&eF!-RJ&fc9EfLTzLXQPk@p$Wx2a~MVZKe*80XIPlPH!tvok* zc5UrYj{o>n?IXa4DWFya=Ypv_AmdAVraXKT&Y#r5C%58p`-U zLu}-_$^o)LJKpe4W;syN9Ljo?sjC$3rS8PFsU_djX;f$G16K5VujQZXw7!;Z*IAn# z4$)H*CZDjD+&@*35a!q;FkA|4>!G)S_GKi0XLSR&0AF+Gnd1qSN}(oCdh57lrgOlF zzK`EdD_>N^3QeGIa?6Rz4ue;USae`r)!#RUro%)xj5bhU9In5TGo>!sUHBQHOc)Xf z$u^kvQEyBj%4S>|5n4e;RnfYx{MrcsS-@*7gV9`8eb$tV1n4VYchYU}bDAz7)j^%u z!KJL~hYXIiSSwq~g{&4tTK_0yBWX~T7aK>NQT=>28)NkT@zrXEA8IpLht4BnqtdaM zQ9V}}KQT4at}=MXf>M0Wg8Qtbt zpf&>RcWU8>{9L)*HFFDtVNw()QO1DNwj6Cs^eIyFolUOGntkR`Z~9sPD`p>jh#fjC zhb^*iAv+@5IVIcg*be>8r*CI2l^nFKW@s}J35lNVEaK00F!*F-oWg^Unym~ zj6wW{hAj8ty-|{~{xsh=eio#JN23orYpPKJjAv#`taMYlPWGWHQ36q~@z=fIC`>BU zRw-2PGHvkB*Gh7@jS2mYtF&JxvwG8e7gNcECHD4jwy7L~?*(IO71sVw8?w(!78^i1;Ow7mHJa~2p&z1&%d)>dpO!ELoS zRev2Ti;Ix$Ntl_&7*7;Nk*D)lu@)Lq3@QKc=q$7frtB9{mc`zQzE81O<4Trb2t^qR6ITP(N20E6s*|vKjMLLFLI{=1}?QHv%p)ggHx8 zh6%7~ri8T++^EzJ-oaam|5e$U2eX}qahz6IHLd%q(IzG|j;?N9siUpshfo??6_zrN zAvBG&Y|_+GM@t=%C5oymLbXduNJ^`kD2-BAZ5++2Qc4rlsDwuCZnFQ?A3L+}zt6ny z%scPQ`+lF#Jn!>OU3Vw)5uXlkXy+p49!C%7Nr1$;rcoue6*F(WE2-?9&z+-+IxY!O zo3$-9PmEujnYcN!fSf16=d#`S5XVMKY3B%rJB<+d9& z#iD85MQ>0pI^LRUDmD?nyh6VzNcIf!hxKW>2Rm8JLGx*Q#w>yBs91xRYb*&YA(EK@2oTEfvE*Sm< zAv0R%^$IC>@f^TdS*_L2@>V@k8Ge{~YD5RcW7fD92nkd7a_KO6!^Q!1ssE_q0|*5rouh_g>}?1{X0G_N#mT_J$;R+Qj01Kqcrkn z)4cB?(XD}4d{hff(oXRO&t!E9A?CSkaMZLvXy?@+wpsfUtknA2d3!r3x8=`1oue&b zzWo{$KDl}p*CY3+LZlL$^1)!Hbdy(rP$VHc}ff9{@(4cmcFZ=~BAC)*8bn`0yVH!Vv92Yc3b@#?1sgsHioa(R!kMs9; zhAr#q%WF}jGzP*gt!{9X7F-T<>P5;(>Kh}Q!I$|4SDOilFF_@N%TJ}w3pB#&vkgUz zi-CF%D!oA0A#^!3MFAN^TjDLMYW#7cMai@rMM6&|Z%*rO=x30Q@<*3O&=L{i#aqOQ zlPCA4p^ap0W0VvJ+C@Dgz-sdK5jV7fy}N11f6VBY=!F5J-_w)RVRvQd-n;EX(5{u( zda{5b%GY`~?J<$@A5?w#lr9zNZV>5`mhSHEMx-0g+KTt{e&7FR zj3dLbHfvvf&7QwWn394d3L*g_1Ox<%w3L_%1OyZ|@c#`64tS$A;b#pzAe~esMIcIt ziS~eBluWgx&E(}F=zz~42q;KQ2xxE<;0Gea5(4JWX9x&t;0XZ%oeBBBZ!@9(eG7%1 z3H{&aH{gaT4?DiVAljB{TFzSXay-U%HjIWQc1EU*A8hQw4IubF@BkleOq~tMKG?js zb>jKJPw}S(5AYfMnu&t!PZMWrehMvlB{ESvM^iEmMrKB43IRkiGBQ3#6EhwaF^T8y zz;FB%7S7K0JWNb(Zf=ZjZy4;{yihF5zw(&yw9B7m zujtgrXf%Q+q@W=if;xO^hHrIo)kZhbu1!7Tt9rw`m6GJve>Ge*B_|^#hK>#c11T&7 ze)uDjDK$ea^ydfok&%HwP=6lGP$D#&692amC0S5*JGuzL$l1{8ZazHr zb2IWxl!sVlf()%k(PW|mOWXNYuFvG>GV^4SULXPNjcOp7AT_?c2y~I91wZ>cBB|vX z>v_+F@$|pfAcRAqG?bf*c*WG%A_kMGH=7zO*Z4(+c1?)xNI@=-k~V3}YDlMJRkf$` z3tH)pY>k!2*qjq=TztCmm}}|y`_&g@MX#K8-}?A>oklz$SZgI@Q;HP2oS}!?;)?qzC8VZLv%$WRy51UiP80@O^extDvRxglIg#D5) znOG&SC-Wg%c_yVE%A#?OUVaQuAdwx)R-G%LrLXHP`CRfyD$6TQYdIH}>Jk3=^F$Hb zEx}lQIt6Z2k!%X{{?ZS8|IyHAI;)2RXe9NThl+?xAwuIg59b8lB4J!;7Bd#kYpc$7 z%#R`kMp<==mQxk_o;X$h6bX@58Y3&vYSwcXhU!pocpfJfMR#1rlKIxvMnTj=yx8ge zJ8PVzSAXev^(6?DW&ar|3yo6zhF8v@I%>OYwkxeHJ%&X}WFa193eU@Ue~~A$p&BIz zVhdt#-%*A;+;-6+h=YnqnIJKz+SmZm-|GeJOG~j84K^PsPpiUvR;=Zu zV$HgYvOxD&jI7F97TNVjA(qRhFgoQ{oIml^WJeU__e!nrlp1@3J>nx_|FUK=2w0^$ z3|~w8%7ZQJL(98}Ib{rmu$jnxxdb$e4UFW_QxUYm?bl1vf+I^Nt}-7D_BsuT_m&B7 z5zV$>)u!>la-uC7ILC6zL{l3pMHPajtA4p?uQm>O0@(4mZyuE~ey^-4`@>1AaeuSi zY|gMd?`px>!R<`Ckr2x&4+RX&N0vO_$2&=wAf;K1!AiCop9OM{)hX@NB20z&I=Nkm zI)%gG8LD?o%!LY-k6iF{_IAB%-o8Z06&t!spJgZ}hJA|(EEP%d0n>-m<{LTc{o+oQ41Ui% z(OwuO-D(RA`3!+HjWT`tr~5NBs+TWEM+BeV!#Pjn%by=sjU+#5nyi1s)6cxVz7A(o z{$(TF@At}H{5$6AYl>$|)&fqB3uGro_kO`C^6GMvSd^Bcq$TjOM8&uuUxj_EdA3lQ z@=O38`9<3VFltVWz-{PoDz|9eq9c-g66?nua}yKvYLwCUkwn~|^*#2e^d&ieFFK8k zHMksrHZUk9M*F|gyWcG?zP&x4P;@6aBcf`xA)rGgwAfG6Cq05@Ul-_JAF(^ zpD&m0CfjfI1q}KrD9qxJYbZ#dYIIa7nb(bR$$3J4GD{S`VLhCFH;Qw4Rl#?)%|Gt* zXOXj=kplB{cL_TYyVi$VcLFSFY3cWjEW_uQmu4c$1q#IJOW!n^Ja*FD>K_hD8;9$Q zJM#UH*Nl@6&-csI`lFxO960uU5|H(awniTN&6hiAh1;ud)tf!9^3!*dZQ-cnO&#dFOsVJg1*L0#HO3}^Zb6T7 zQzwZz)cvD|6-9*PNKhN*`FS|D__I2%4d~stEz05>i$f)(1@DoCEHCMzuLpT2oQU)I!49ea1&n(>q&;GNv}u}g;Iu?-K} zq-!hyd%F!M;B===_t{=(a{z?~w>xM}L|jFaVc!J^cEuI7I(Q>W9zOnRJf=ntZSc$4 z(sNttGDA*$O&0p-$8FpliQj~}ElgkGdZg3e*O!$in=tNq+#E88hf@vfixQMiO--%u z?Cn|N$3qGb9F)QTAIYO1OZ9uC$Gc7Avb5JRhf2Mo! zQVt_rOI^H5Hl=&A)>Jh7{l1TB!xf2K4)L8z9NaohS5a|^Bz6|Fj0=wNc$L!|0>OG> zl-=oocXXKl)2(FvL{4;U+P z;1|JBHOEtfmFG!TAVa@H%g9{{E8=Ub7}pUZFk1NN)NuM(!9Y`=el4YC{PO9K4zz~@ zkKdtAv-RQ~=3H*e?94Z&%X*s-%Y=O|8w}(nn8_zYlmnG|0s@#D<#JXOHss5kVBtr# znO4-ByGgTg<;M62)!0<-lo6`VD#sBevuR5i?oWU0n|wKLuxV%bbrLD8z+Qn00VGB* z9%r-=qRN@~X|IHh)o7dsfgy?Mj|@K}BMWMGFBMOUhVg;9u3Txjd*M5EEG@I)Jkg*b zl|;bZs$wDKM~9e?*ziGpCsy{rCd!BKw|RN|#;YpY*34MduvZ1R2DZ&D7rq9^I+JhJ z5u&Vc2b1Gb$D*_*pq>DM`^TJzoDmTMeYDmq!;HaA^IZSryyX@vEvc$-^5QHy&lE$B zMk1seldwWZX`z6`ed;tTpz4P+HRqDmUe{B=i#9R;CiGqmjOk29b`5rU=4jA2^Dmum zo7A;M|9T8<_!#ISYmu6Hn9;QKJIIDo3cPtL#(1Bn8QZW8u`PHMOf$B%5old@#iH?G zZ*Y|kg2m6E?)R~g%s*O+TXS1Y7Aj=@gxoyVO@TLFU}bn#ZY^LlZN*x5?TzQ-f?oA| zCxVM(Y&pfH+2Zyi>3<%_uL!@~W!DvJdUNW(-N-;($bfN!8mQw6*m-~bmU<>YNiAN@ z_b2^fFR&|uDhixOM`k?ne{X=1&=IeiYaPv=2|U2B10C2FbD^o^e{b#pYpmV7?0ag` zKd)$&8B9pXR&$^Jd-J^T|2LPE<|g^^BXx2s<43vtN@B|Cj@wy<|J*kSu!kj(xj*$y z*~pQR|6xm^zki4c2jg{*hZgBV*z=))paAjkaS=YUZL67JY(DMPUUVJDSaj#>l)`rc z@y7fmOwU#Z8OQ?0Y8L_DlLJbg;DhSjHe|KS6YXs)THQDUWlEAf8MDLv?Fh!Lqb(*5 z%^S%OT*#n{e}WMPG731=sGvyg0|=2%2Jf;*%wDM|2{A~RO0LuDv``I2##+1@RO$`- zdw6Z`FrAy^bpiPPKE#1EZC6k|d=C4snI??ye>#@D`foii0CF=F>*y%3o+?!6Fd~Qx zhXNM-kJN?RLjBH>CD=@ohe)PmK+A1jEN;E>&z;|a?ekitlU4V5?g?BN`+010Io;k~ zzGpTe$96=+7R^k=U2p2np1n8H?MHt8Mo}C%tpfcUmEnbX?k{SygHWG|C&Lu zof<$#$+mc>d@f_$9_j7pLw+kH#DBj?b~20{7dnVdMl+rYw2vUDB> zR`G-MS(z{f1A;YzeDmi(4OTvhCo{I={&NRBVIfeLIK=5@m;Ep@+DZIiV!9Vr?++v} zl`BaAbQp(0qo{kdm;^O{Is>`?IX$mCEY7#KZGtTJ4Cn7cY2cv%SHHiarDT5_M6?($ zVQqexb?pwn>paYTHs^6SlU+)gqB?S-jJ+&j<(}yO3E_GF5@2Eh#ijWqubUm4Q#iag z2!^FVNtwxugHFOdYuA}EHyU#>K|19&_%vw*dqerm#0~%x|E`zScWwvhRYuEQ>{DoS zwf7u39hats1VwoknhPP8G=I0aic-B`9&vv*yYH{8i>k}>r`I zg}<`4Z&=BnM|B5}T5g^0@f-VlT8pOT%S&Z5tJ0f8Vbpmv3lV;7Zi}fZ7WHrXO(I%` z{$Z}ATyoa=$63S!XjqTdkSBiJxeK%LYMh;tBk|8}mR|^14ns4Z&rRG^?;VRxOB}{1 zR&Z@}D_>xTg=QxzGxTzn*LGEoKboZV=D57MqIIkc5mKpE(-g~ zK!E?}Hdd#>!fRt7rJm|5?|l@V&W0Rd+{)DiQiY0P@p5VXQhjMUMCxgA)-ERE9E$ry zX1CALKxNHOAT~KwW%~Mgo5A2gsv;1FetMV=YZZ7=Mh?eGWe`s>#PPaa^S5;x+Ht3O z$8!|!qFXSa9&s6tc||ay6z&9B?0ad$OqJL?dFvj^JwB5n7ZF%2hAckv1~GM@ZY}sl zd+mf%s>S;L{8_0_X|OM#!L3EN66%rVbGhPsw;QLA94gOx7t-xn(E`P~*EE=r4-D3P^~Q zFhrn@>)=pTdg@hnJ7Vc=xPOwFzA#R z-S?sQ==|M9s5(@crw;9?x1FEfPiL2;{77Jp(UnMaeh~!vLKFT=xdx^eO6ecvDVc%! z0l&Cd&*7{wOD+2KGuO9@xRFR_oxT#tsjVJQv6D37Mh-10hJjiQKGdM6W=UtzGd$K%-R4Oc1 zG;XT#fqqm`2y0mN@k&sWmCPJ|RMcOe+aAoGTyyF_XKtfS`+urTP0SXtY7=~soU%LY z8UDJYjyoW<^?uLR@!f=jLUN5X4yEWXWCov$1Es?)@wI{|9hm(&5^ja%FA59lDiy;W z6g2f=t@zMlvnAK2cqmO--(i0S*$qkLP07qj51rWOiNjgV#u_uoE;`*ceML+)eVZb*Uve}f1+0sGj75sg7+%!U^_=Yk}4Prx9kDXTupA4FLNc@vha{)=u1qV6eNy!U0!+Hce#m8A3jU`55 z`OUOvF4qQ~m)4bdEHyT?|4VKyBEu0oOLE9&bGSv3{cJt=9nGr^WO8l1;Jvc49L8|9 zb2aKuX2c?V2qf*z{zR1Dd{^YXORY@L7T3;im#_xrUUNKV{o0nwh&1LtzeI7`9hsS# z0D^T@KfVuQgT>*h3ZUQ}XbaWtQ@jaP>c1>DG53ko#7xd89f=b9$I4)2kM;@?JiX&2 z@K)5EuiZqqW^gUz?oSe2bMwzq9uO*}#B_2;in-nornGIfo*%te z#I~Dr9L4elp#)lW&hKDhd=ZUfd`j^uTgPP+=Ur6VJrG3kmlYLSrcMaf{ZZGBN2z~$ zJ+Hun54lJiV z2@5-fzWV0GL7C%5HSCgpkul-ejK2(*JIWU~u*n;ETBw;#B3exEe#ES;{LFDY>Gy4* zeT=i@tF;&$4zF+$Sfnb102)W8=_L(9i~L-LFoo-P0U1!jBxXsmQ-GK=VNS6VN9=E@ zC|T|9-be0r!8FV3IE89iOZwPF>x0jMi_*3_u~IL7Q!PW|i+q)aIcQ92Lw21zO0&3Z zBrF`so$gX#k~DqAP_+MzBMbka5!<>=-puR6>g(?#^-2ca@(QvF9Z?v&xVz$R9B%S& z>VT!xv&7ITdQFaxy81RF6(+11qEU>o=4YidY{-iFiOPD0C|k3e6lCP1^k?DZO=VU1 zZLgOpa!#yd*if4wiCbP=LhJE%P7~w{e9;*T&%oL(i{Y%m@2DqAMljBebinsgCR_ID zlBepvSTyvI))A2B^%y2r5Fh?2ir(8-MjO;FTIv#3kd)vOPl=ToRn8bWRU*pF+vB2) z8ee<3M8%=g9aeUTEZLAg0l9tOeM{dUK}qZ{_C7s%ktUa1m=y+zAtQ+<1clZKCrm0 z-`w1sZ>QLer@1ZneRtU%^{=&AFth#PeRtV(Upc^-6BmbVwcN!0aC=bZy!BNxdFBT2 zhIdz<9yuA_*2e}T;~S;NT-Y|9Nc0a5=FZpH%*@SJTVlEFjenf4u{N(TaH3Ra^Djh0 z#!_<@ZK7L3^+gg3ULEk-L*xA*Bmif@fG!?bh^dJagiRUe`uHk^K_RPSHJ^@294f^( zwn{|yS5Z~9oFRncf%GGf5~c4{9!;u-F}bmDTM~M`m3JvRqIm;ZG!Jg!#0+_0Ugc5- zU$V_IgCkV+9#;3uY?~+h##d+_mviQ{EG(a*iFqYZ2svIl@AA6+VmlUOVv5oCIuZBS z%?jCV^M^ja-iVpN(R?c$f=ax8A5kEN%E4mk$c zazbiDi?=a=vf-w5Et9AI^7AKauC^Zq#;5+DtmCO_g^@$?)-^#vF#FTr3BN$UpZ(!v zPEtZxq+LZVE-5+jMNvSy_34q<8chgQB8s4k0CD41HvV;%ezONl)`yEJ&7lZf1|2cC zC6|Po)(bIVVaSL3vypQkWHWv?BB;3H`_v3<{p9BfDiFyF>-j_}368r?HoDn4sR}-v zW07J_rwIBAu-h&s+SaeZ6|43P;|p~JK~h6( z*6adCj&R3jB<6B{%Xp!dKrM5T-iZ_%PvybO8<@BD+sXHD4XEpT{{~<%39NBZbp0`JMN-lVhRMjZ%2W!aa-qRhVP>?H#S{?D?HDXLcg3JIVDxX z^pF^1L~~qv>QIfCSqrhG(<7eZks63e%E&s;LByi03iR214l@?U+JC}IQ=JPnF!Yam z^cCz&5rP7_-Y06t{lpAvrwLsoy?af zG@ihn7?p}76--CysF~3p*v5H}HlA%dlFok)3}3+nx4qs(ZHUIk_RGGxH6R{kCK(=T@U7f4Xu>`Nwd zYrnutOM^c#gaq+SM*(O(bX1(fwoec%0u7PrKi(5Oob2n2o3sn|rogRCrjy(`@hzQQ zNY&QyCd)yncpWJM;d5Re3zE@2fs0AiuF>J4p{-$jg{0linl@}!=UpXg>_m7G$S*MS z1biQuQ}~%li9Iam!%|a;ZUGWU5QBn30retE1uF}wtj-php6`y8+(3klIxg7Mu_U$m zCh7+S2F{U+GP!lW5N7(WX0aDlhMZaCtC)>|=EiAGCoWP6n_-uQC-I~}Du0tg=`O@2 z_UyyG#`ygK1y*gzep!}3Gg_gB#3ONsV^=M&4=KGbW2h!&A zaalIger%@?uPE3v`#zkHNpjypnFY@n_%3lKqWC=&?{GHJL!3$G~U2fq#shD`VFJE2wKP#r@kCN@2 zn--Ng#k;~nYD%z@n)X$&ZO5mL z{G$NNajfRuAL5!=L_{@Z$Z|#lzRS{O2K*7r4YnNLQ)?rX1m1SGfKvO13htIyWCWQ6 zl>hC?GGbA2BU3`(-vxXG?yFg2Q=9`9f>5Ew#H`+9pmJRcSf-?{)F^|i_J$cJ zb=HL@h2+76cdO7MRe|APynGgJvdkFWoxW*+BJ@Zye^5Hgdc16@SfJ}+C&O2vqN0K$ zr>fsk;8F|TN9&E*;5%PBF-P@y=xYAxsWF??jYB|ptc~93)G&(4aj$cw9_cs7Ik|eG zz<$POxKs9)*JuB-oLtgE?YktNELW|>^k|)N)M1dRDY&#y)Ca@J=tVP1OF2Pxj};pT zwGAJO0NN(3dPiYoyjbsWelcTk=J*iUi)=C!6#tWER38X7CAn!?L95*#QS6XbggJ&DMj$2L>w4% zu!s?mVkyi83Kp^Ijz(#j9&=!aI{XWEnz3*aGV4b z)EUgFI2pg2G*pP91&hq7|LD=Wumqf9qUI>I{@d@my1^VGqL5IK^6=G|y_?#fpTwnm zHjvNWsH#)VCEe9W_aYcmX`9knFEFL1eOTa1B8`5ts*!FynjC)ElpU>Yr)z*CO*l!F z7~C18r1rsKg;>(}g8VgM^!O-tyD~m8S2gC;Ml|mSos2-r9%jvUzA!g& zb!+N(r61w22xQ(tozX92N!4;%Prr_a=wPAnU!JQn-<#I8Gc9yBTSXJRA4Mk4p8G8v z;1;DEO9_9ReY8+VXr91@62-*U)>h!--E#|wI(-I=AjH@9^aXNFgP-0QHTN5Z5kc$3 zdS>eR?hMjr##EFTd-YNB<}vtFx9P;b?B`L&mJ$m>M5@8v45x{bd*^LI#2ojMXXm4X zyOvhsiCu+dwdOcCj_w?SxnC}7a}6|_XWYa#!PaI(tSb7PjV$U3I{M*I*hnlFeZBP5 zG{1ugh{;1rM-}ocRF0`V4k_9rx~2yzw_n%q+3sVOeVM9kkV5yL2Hwefeq z8e@2A9#%X`5Cqtw^7!d@U!S~Q@EBg(MaFs+D!>*&jgvek0x#sKe@R?&fSHL_btvs zD2K~fFV{|kpo+JLkg(=Tn>l|a!b(Kxz&WlL&5kjEx^l#bLLk^^q|()sg(&?m7NxV* z`mK?F6nK980CDcKh&{3!{DS7#=LZ-ngT(33Xo2>*sLQe;fmN>X39df11F^P{AiMd|3X zom7yNSk-#Zv({B&2qoJg=k;|*5z6Wwjt|5_5zf)GyiaV*@bUJk`H^}Jna9ujD+gqI z3R|F%AfWw<_rqqKe=BUTRloZiE*Z;S0=${!xw~>@UHG(|VO-COOShx>t`=x}v0!PK zAgJgWENZ#cPG=wq?&%**5*={;IV71hYkAj1xOc4#5(_EbAEu3HzDV`eQ6#3Owt47OEFOnM6EP zUq}9N1i5(IAYD(~`f)bL3Qx?zR6Ncazy}b0g!m<#$glBGn{wHOx0K+qf`QUhByDV0 zj7LX+7$vRUlf->PWkusmxWBPbl65U-Ni(hzVg2U3;gX2*w3rR2^`d2!5CV&w4H7-^ z@wa*;DpApavM+o9lQ}vHC=_Opc2{dmT9h8D$J%)t-2xWF1~%JJp60_xOdlbO$h~`E z0d&X!WB<%-W;u-3`%@$=#3khEiEULbtw2A&NTE@LKqa!bi^)nBRj`9hI+kG77ps38q=svbs+kiXVX}OGo+i>08BLszp0hd|`>mU%dzfHbcB7)5n`oXuH*CL} z6y!x!y}M^QkC|{@3)3Y#HSS1ga9s9AnwB3&;Fkhe!zoWra~-^Q(7tC4MT#4Y5s?c|?Lhfp{NA#UYa3Gy`5o_) zahqIk1f!!pGNymJ7L;&rSK@~po*s-~H1Duk9rmsQ*pmvsryu{+ z6W#6dt;@?ukIv)mX0O9%_1N=ls%9|6^h+k8Mm8?^xEphGwu5JlZTQ*2!J))-6zRm} z*YUC4@Vjq232YLjNY@Cn<4|$cLtWcB6XLrs9fvK1rEW-l?+xEPMd}wc8DIOf(c%aY zk4jjuC>*$Vv#_x>eBm5s8eqE@Rf<$PHvYBv1Hg)$7^Som<-zWtP)ya@=<>^UQ<1G| z5FqOAgd%<#)r!1V#G9|UXTH;US;E(j>iD~@2c1AY#+$)NqUI&n#E(ECz7Mg)aY~qr zJntu!cS1sNU9~2O#)?Hg#8OTZMk`5`Y+0>kXGhsjE~!?N%2UVERymp6yfNiDwfJO- ztBf9+C=|fy+~4~;!gG1vAHC@zI_`^5lsYHI}`@aZ^0LD%#g8? zO$XvDmR5GLl;dk756Cj$h^RkVAoherHZbqB)wSsd^mj8m@tt&HrQUx7JU1eS06uKy zH@oG^2M_+CKVx8gsFanJiHfb86{Mdk6fHijVrBJxeR@z7 zkz^Oji)>b_ADmQ)Zyd_DqT@rO#=v$F3AeFp)rreL)kqx{=y}BD#px507@EwLJ4Gt# zKy@nhI{i&1Y5v#-jrR7l>Sz98VgvSG`w$DXSz}?_)m4}P=$-E&q&|tp>n{8lo`+SH z^8m&C#M9mDDbP?#4WE}%WGs$>vJpF${%%p(U(X|@o(s$U{nu7}cx!(^ZKta+wLr3i zpMtaE$JUm>4BI2kj{==YT z7!VJ=b86^2KTF8y2&JcvCO;+VAkX$96{Km&&CszP$fImf=CBx2f&4WiSwG}K&V*Pc zmo71D?MJ2{RN1K>7PmGtQ=g{W8>zP!Oons=){~qImE+|D-1ZRIA18?RB&Z!+k3r z@=_>NyeA>Xhjz~<&G7YnXmK;*Wg*8t>Ky#HOS;}=;*Wm3i{EVRPHB$J{HCF3Ke1$v zVpYDUkb%MHJQ3&F_|BDl_9$T`SRO`!H-^1LSzWzd{2u?k-^t0zVK3~Zz77%J;SZ%Z zB1<7<*hk_~Oc>RW!7R{?XExX%~s^VQqNcE zj);w?;~98;n!qx6jS#=wjbR)%X%Ewnw-OS^*vchQ8BDe+2l~L4#jFnk(s%^7OkV}G zQ5t8ctIA-rArv?W|!IyI&N>zFbi5Pk{*5J@lX-!g?T=SCc{Xnx(l{%bqdK zgB3)zM%bbv*Dq2#tCR5t-XlmMHBDxnez(G~5mPsSoNEQ*M)f>ER_*;;VG9aoaLAnN z>x5B_Ozg)p4GYHYd#3bl-|DdWV!AKQ*gq_mcq23S3K9LW@QB)$y|45X$e<-9O$sJR z2D^$4>!?PyoeD$V7%EK?E!?B_`#=zz&KW?izB#Uaj> z!2v@`@k8GC6*M-eQ6UxS{P&<~-4Ndj%P#tfXi}5f+qw0e^#AIFbNZiS|Xi zo6#!D(T7>mjCP#}d8F`g0UJH9SY{ZG(=F^3`*Y;?T8?8SDy~j_5s!~|b{uxQMCZGk z7u7B~yZ5Bt=gQPrT5u|mOimx-2w};P;PF%!4E;8Sk)w6pKf5%&Ki~@To(`VSLc+y{b!1 zKu_>oG6dqhaz-RXR4#n{gS4Z5nV%^{imQ={xMGK1^N40Tkj@K=mVN87pX_vvrpC&S z8r2l~3$vOf^&j`7xH}%%(iKY&_nE0)gOskAzOP7G-yvOX!tHhPhm@{vpcjlt$I3=< zXQq=y{}xT>ySp1D*5=_W1rzxDmGvovh>FG&Eb%2QN)Stl{4vrtUMMxLN6U8>k#cm# zZ4ib{5T#PQ_n(ArCZZD}C?Q&?3iW4@;eFteMMo2~9Aj)4R$eh)aVl&?%VMz?3&A(F z73E38cd8gsn?{ZJK(vi1P#Pu~9-B2lbm#hHBjUTY zHC(pHyY)5>2@(HDm(U-QZ}|sbNaaP$I$t}GjRY}_v251H&snEiP#%8F^{lQE$nmqC zqnXlM+OTTa(OxBSalsHV451HACM%rrgQS|m08r#ph2)jiL&_xg`!iX#bOk_wAap}&NZO&>&zS*D`u#;IZHpUx3Tv(^EQNu z4j_5$52%iZ-Z_C(ICcnRbnY^9+53yX7!hxy zkn@-puvbK=`(qiQ7ef;fkTrC$8Vga`SU@s0tV8k2Myf)qNIL{w;bO^D%&Ayi^0hMV z>Wjxvj&_J(IYg*`D8fEBdj14xCUhCC9-1f^IOoXUHCknu=B62ZLuMF>68Wta=?NV( z6ixE6&@sdAZdCK2on{V4lRxPa3m7rctWSm64nKd0%r|UivW6Wh)3(OY74##)kBea- zCW;zKaJ=I3@kj<{ohYqOE&E1BMu4dKLnWGDfgC%!t8ub9jqCIGYTQQ4G&+^wQB?+J ze`oc4^jM^zqJ}Dpdb0`sjU9Eo=P|mRcdUMu%z$3~Zq)ZOE(z zMHTn7;IicCV19o8BLe6Nv`-Cr1@4Je>UcAv3=+R#aoWYjr~OgwdP|~{1DAU<4doj- z+>z{XO{)^nm<{y7DN81*A`^NERMJ4{g0uD?!?A|n&@za(7gJX20H6#l*F?lqq#?;L zG3{nGj$y5@Tu87(sd{3BYloUr(TeCa!~oPIZ)2lK_M=k$>emsTPm6`$g?FDA^>tY_yqY%|wyv=0 zBNr)X25>PX0qqamLvCp5xyT2aUqd;vi(?ZW5W)DP)jwEtT)W0&lw=U{++G2#!dA6V zv7Ph!=-a^?1HPdr3#^(WQiWzU{fO!2jzXP_ex`4X^PolpGfSmEDS!e%1ALq?$gU(N z^LhohJQ^MHa6(&BGh0m-R)edHNBR=kKgz3U=bC0eE4VFKz|^{)$U2N8o9JC%@gFj% z$A?-MT{FX*{J`_0V7R!r;IE|K7N7bWpY4*td|6`w1jC9w^%|x{sxi#8OhwRtzkuls zX*Xtc`Jtf3hP@RqP@^I7SIm-IS`*;WL}=nDDI>V_oObZRz<8>Qg<9t(DdPkc)>@7~^&nXIBBc4bjg=^&vT;xFI# z&CKPDm7jbb1VG|oAx9(tbXdCggDj6HknanMOc|Dxk6qT3IJ4KnKnzN^RWhAYq|dJS zzakDXj=TrVgy&|l6MwL0KotgnzK(v^V5Q3J|6VO0T`V+ny+|3bM~1D7Se*jmoQcLG zWA8-3=s-Rs@G_?_7!T&cgR@Jdew=vF2n6?{A@_N{nI*z3sK)KFn#tXmYARHK7DVKC ziZ<%0&RxdJ(Y9Xew(l)^hDyGL0+^f;lFe=TB^zrjHQ!=d_adGsT5EF>D#=I=DoV5E zzIPfxi^F*O!}8#p^+%*oT0AQaKUw~1u_lKkTWzeW))uVJ-7Pv3$Ra(E~2d6E7SPr#=$xZ9_ZE%iO2hDBXX#D(_}u~ z&dHShY;){=KVQ1;xY0Ar7O;cV@S!lbl>0_0dpcw{9y1@mER6rAO&j#oJ&}bP(wGv; zc(BIIBjFRbQ%JYb&wpj>>q}Fk%+7gPDkvey*Brnaz4bdgHXqWtN3x^PXQQ&9f7+&B z>kr`qt1CnX^AB8cFvq72!?p_>OCZT@nMpvYYAWnQ&hY4wQd}{X{FKo*u*2}{>6fEO zybOasig!`@sMv}?Z6pt}l?WE;k@QE{kJy~%f|?jp2Yvq=+6ur#uKCfAKFxE8QDc3- zcELMlu)P%MAL1Fv>yBzH`z8}EdXNdP200`xD6jqMw6M9j%>N0rGD%wzwa{PvCv^xM zm(o`-oC)IA<=!f7M&$Otb;mO1s`aLx(#uUL4w}&B7*&%g-lv=cWmaA^1i~XtHd`1uxZDJ|q)(E-EFkldi?uOxGS=@{uoR7FI z(CXuyCZGOPLbSum)hvp02rd>vl;(C%e$;qQnu2$Z2@tG|NIvGa8_{AMf;c>TEmay* zL}mlIKrL>?88sW$?~D&u+dqiN9eYAL-j`Y*C)Ipi>Go5=>y^!?AZY2Is}4ThLkA<% zN5nJLvBKES7QY$X4}Mg_?#VsfPCfReA4j1?d|B*CLuFI(`i=glz~v^UFDm0Bqox%o z?>RP(RRc*HsKXOXx3(uzT7Tuy-*Vd#x*_`XQhvqkp+>}w{=7Z$^T!b6#{C)l-hZ)vO?Y#j;sc(FJf7;xXeqFJ~`f0aR4OxJq{ET6sYZd)u;D-Yax#2RsR*sX06`$18cm} zKm{@KBV+%dVOEQ;w%u3sS!SovH9eY4Mr>w6&njAZsU$3nadk+ft=Ss{C;6{XA=2+! zsW@nz0KmLRV7@oltdKCJ#Mly3BO!GzX<$S;2*5OSEMP)%HZJB`bOm5N$DHWaH7#l-V8cTTe1F1V-FU55v+~Jb%z>2u4zCL=pOG<>AYq*8 zY~^H=95czD(UeLAU?vpp=}6d9Tdeqg;Le5Vc>8ZwQ2^K6g?>7^bz_c1lb;{fq$XUB zI)xaaE^?uywOReF5oCmf`V$f$A`6BE(i5e>`K-u0R9z}7Y~%MMUQ#_(6P>E(^*2U^ z^_~H=hOhyLHvq_8^T-@}pJS2=}oi z(V_$jTw*wODyDD0RU&YV{wxba(N(8~6}obQ3P4g_ zc8xS(k<1>)a)ox9|I3)NC_#sbM$S>q;@;#hn)emBa-gFWz#oLh>k(E;=WN89spV*# zglEsXZWx5gF=E!`CVvv$i_vIqPxPxM91SY=Oe^!Z)fWY$H^D_5i(sqnm(RzM3N z4AYMryXnq4CfH;&8G%copq~dV_!5 z?Y-A;aere$=b?v@$A+g2gA)ALeGl-v11naQhDrsnS6E>(k0%mBm!=k{YSy6vO2~z^>Y7E~nk85%NL$Cpu=t0Cqsq<20WE zcF+%<5?zJ0lMgG6OWXX(U)7o+Hc9ng0hxYL@tw9YsUmBgDW>NGAo9vG@%gpaXJ+iyp2|Ch7$r5KyDyB=nf@`;us?XF zderoMV5ZGR4N_C13Y$H0`%vo5e}4;ruD3O_#)1eO_06m)+|aEm8S3+RzQM1dU{ohe zU3ETSsuJ+T4^%2_j?M3R&dpHpb1yWNYorlOx|ld|gt1u?n*49pXs{U`$bx6nnFno4 z$EFN89dsfloJU$diHK9a3~M$4T!tEhg}7=1jlt;*|HRl|GfXIgqy3T0oMa?#%J(oI z!19yJSr>hmBdZ8kBfDoSQTP5|`Pf%L>;bFOs>b*V`gN0^l{X7S3R6TgoBeP_WdZPV zNzE=#CG5|lf0vYb3S5$*`Fmh50z!3mD+>Pp{@A#<8Z9U`B`8mbo7GyJ#!P8418>UK zjtnAM#(WE!#uZQ2AZuVj0;Fz+E zBt0R&VD`JcJd$NfVI6hJdSJ(Wj1wPkdBTY&KFd>}Q0(iFZ|eJUGDzhD1r}bV-6HR4 zI9v6SB7zn7OdQ%hH=@Vl#iiqtl6(3(vm4m6hdWYKFZNYPrlDy5AmDMqexqN`dtajO zQROab`DYnRK&2?1xP-*KPF|;bUtb@a-7+7K+pknzOvH^a_>jAaL{DRj$uvEXHkal@ zZN#V{#nILHvDx@~KHFuv$L=zRY@O+yXOnTF|vXX(z_*QC!?+lrk-y=>$ zL}V9;A?5=pjk5-zM4JMcg@xrDz^P6ovKZGtd@F4Tw*^2u)HGVr-c2Xnglrb0WXrYy zd;?rpJq{$%Xaof_cw7&qj$5Au*e%C{5_tFF#j*x|gGfpc$U$&$t+y`qsXP>7LSl>3 zI#;MU0A^sU1%-B!wcFJ@Zb*i{Vtq!BZR;UxvRKpjZ11XtHF>$k5S8J<5FX`6Uf{p_ zh<9KKgn>dhF`X8p-&JR8Q=pVY%Iz3rHA&MDxxBnQS#Bu$tAy8OU(9XM0p4b=@?%(g zf`N~;Zk=r&0HK|zFz&Gc7lQ-vRMj*dm)?<)7>@U|ZJUs355VzR0(dYs!*-bPhzQDR z*v}_GweAFvvE9u}(5EmkFbFo<8BTLva+w(ek|uVy0IqZJC3KJaHw^}A0-O2jEC8Mu zi-?H0o1bE9zRKnd=~n}B!-V(w~aFrd_$B$?B0cmSZu!402>+fOku zXo^qAzE3&IITB+)QE&GXB?ZN9)rde2fT;xH&1TzMTVscFRS`*At02S)B$(u=>F>G| zrFxBpq9Lfx0LbdZ>%r-4h;sr+>l8j|?7dJ(sz|6?C3m-jyVL0$nv-`ZqfY{K&Y_i`a1v~rH`{Fhp`+FE} zph_l$!52kdt(;`qe{)-3isRz{A?h0g``VhXW3x$Pn++PM@p>ItJL=c1scrmgWT2P|yrGzVvlODpr)Y{Z` z33PK&EpksUL(^=2brb41)URaDLIC8P>MU>W_#)ku0go6?0XOPIa^4hCkWUuxh}_%k+X_! zu_0x>f*j2Q{H}?n>8B<ZlWvX`~d~Pzi0vtin9-5!DI7<53&z_$BTEm9$Y!XuvLW zCCC%$Uqioiy*MtS`zd#Kfl(kh-x1;c^0+k=m)&a;*r_D{mNE_CXeYu;oS*mcn{C!o z!lkXP=|0pgbbTI8zJ^oVX{j^<>ORC*;C(=pwjBP|X9JWA2;9)jiNi5oX!VhfnD`Q+ zS_#UJ)4r{p=i;u`9+(U;z+zOmv{rIXc({V&D;Ac8(=-*E=y}1}sG*W9{aTira!kKW zXzN&Z0>=5s8Z57kVC6b5#$vS?72XX%n_&Vm$eIH9A@G=8?nZKW zJ?r=ffbA$fc8+{l~>)oo=L?^nQ*CizH<6fc{ojEv81QWWq%48-n~EQ2 zGP}x266=4x*O>@^C(24Z^B%ssWxQWf2pPi+hq^Qbfg{(?>-ZB9GYrWosVTk=V&cg> z0|4=+FPst|=s$cF@BnYBS9PQwh0l`RZ821i$MlU3lsZ`dP$oR*?-LVsVL9o{L_qqv znVM^QLl2tDntvbd#eJNdv9|P;pe_ocDbWot?W)Lp; z*10CgXx4CqYpaXvK7#?ks=P^{XwkwjICKW5_;asR@OGusZ-u?fUb~A&3!R7=f_0ZZ z52{s7nIH}n4zeCC+5X%=-+_A=Wom;4yYrA;kCAUFVC&_z)wt)6TvsyFu=4M~kZ`Gj zlx&O(uD|bBMK7CGkK{lC_54MJ@7iBSDcF4pvwXto0FR$*PKxIXK1vWtx`iem`6OrC z2mXST+bGaxxBdh7U1|?hvT@4_6b&q);D2o2tuG&tCls5Y_Vti6R|5KWHZlZGY_k?! zs9rfGSSb@| zYdzF=<}%Xo)cpJJL)bHi?W7MuoHBeT2C%!*G1Vqn6%dJku-kL|{Kin=X2jfjPycKj zV*Tb#Vg%TeU#;k6@kS^LU*C2YTv$%B5$8ok6}y-6HA408p@b)8KW;impd}RO05YNd zSw>cZ*pKIP=_=>L0aCf{Fsf`?qt1SvK+td-wx_#*BK@Lfl%)b)K~afcn%53XFx0|j z(p>U2I)pX>XbIWJJ072Bd4gNW^K7#C`E(ZP(YpfcWwG*~vuj zB!heKF5Z%#n>!P23Hxx(=m`MQmSBH1od&>ne`m5990>dY5gU8v?uktH%tY7}2qa79 zyoj%#pjN;Az0Fd7)RF|ML2cyg71^SZ7!HELYP*rd^2jE z)&6UO2sP{Tezi`Mk(V!GDBf(GD6w1WfoU<*h}rx9tU&Ss0gQInGPnPTWiex`kt11Kp5Em%$6ghQUSp1BFg&HV=z zLGnP+q5p&!ev*_C0G$doD$9|g58@Kl#4|)IQ`d#c9Z6r*3OF!7XlJP=%PE9{3yTb) zENVJq69}?eCZAUPZb4Q{V@m))uwGmhqooWna{GBXG|hZ1-xw1kOE2Ip`e~m#F0Mjz z!J}egiU9@`4x2TWFK0fKtjRFt4=*8r2tqM`;-K~jgr8LO^wD^tRPu~K@L4+wE2>d_ z$iC^-cfW?nzAnEggV&ZL3=6CrYdx)ws12WIn~y-vYafu;;q{u+xAB7Y2G~gr-p}77 zA|mp&Y+HlnGrM#A33~XvYE?Z0NDEMtkOaJ)zrV%GdyW5wB=6%cmCnRM`5cgiabkM5 zZ;o2{I>`7M?NZt3Cs}B4-DV3N&RRB2nU>>{;-mLHDKt!sPnxd0cQfChFJzrMZ*J+T z51C(HKma5f`>WX0P6nINP|W@l`-hIp;olhUGa{a@4|3Ka$W%gO7Po86CV0Kslqybo zzGctz{dvg;yo_6aex&t!lH1+aW6kAcapohEUP!8+JZ;{by!E(YMt|>X0_b0401;2u zwsIsfBV%+S;xa2VG}LK8KdYcIcZ+C4>*I#O&|4qw3f(|0lgYMk82Du60Z7DX4-J); z58YA9aNKx)c1i4fd$RI5%%?{;=zm^K+4ArOuo+R% zli<&x2k__0ad6&rO-)s!?#Z%LBDe}q`vZZ|Qn_vq(<6cC>i};@yA(c~$(F;poc*^m z+SCakih~xACmiZH6qSjKe-(yGS_<4hyqt`%KNw^>-&ah=dlkyPHaoo`^8G`R zZSKwis-?pN&GbNj&2JzYAIWa1u4dR=*1vLd$VKG2c@hnFaTuqjkuuSsP$$biwqE_NLbnIb)HuehT@ZnQCk^m$@e5x8EiBw3(}|1*;A($O$1}7HKo7v(9)O$HBj@u) zAF?~X^Iu@Hd0mGuT(LOpiR_RSLAsEwF|n{Dh@N0!VXZrRJi)UmbA-J_wpRL_5Df!d zKk&*sA&BeSJG_?wCsT9zO)ySC^WqHrk}2ZW zcb9pWWzueMIKC2JC|=lk^#QBb>!I<3pd|xQS{{YWj&~@G%-erxVl94-Y)aeVB#7jP zSGyLZLw**dy3lnsEmIbXuPkTudFio~46UTHTN zB$Vj|+QA?26>H78ye`!o-#2#(JpI9Gl-&BzE&u*+_NxsR(n5^LYx;Vn+HlaU4WXg1 z$OuiMX0Z%Eb93{Vmme|$*uV}8Aj#)0_aS;xyMb+U>SSv_AQeTL;K`t$Ynd=BUOoUn zkTOy&`j}?U6arZbgM21-sb@Ki&WDC>R)HeL~o#V-8* z@+mAVm$99l9hdzUh->#BfiY6I7y+6FZ15?H;SSck8ry3ieBWodf(1rjt{|YU z9|MuzeGRw97sl6llV=gM?r~C8X(G_h(DhR1;FLM%hACj=7mK^=1XMNqq`eya=(Y+V zz@kwaNd8pLZ13_$7zv5T?t;(sg?@@bK1WC4-hC5bE0)b3Jq*0N$bkTb2)A0PBR56O zqN=U(=>p}4nH21b6hv^KcUg0z+-Wlh1s!Og#mMV!?DNDt+?P@;3nEeGjN-j|=2!*b z8`)!bHdJlYQ#9Ovnq$8d_;&u5<)sv%uD-=k9=Zpc{t2Nk8v7X;Wi-f&+5hgsC8pZT z>r$(NKTn}s*Z_SOF&vkGff``{gn=j*x`8z4>t#sm6EqOGm620cNXHzD`rlqc7C_qc zpo1%dDT0GuL#O-stqAMD00m(JJf0f;OU;XJe`PGl=Y>z$*dzT?@6D`(ojp&2$^vvX za&pP_G{>MSf=i{0bA?r97>pt;7sV8L8_IIY6xF)FuPUYtMKNCz(-Y-zlR`)~bMs1n zo^=V;gk1+9>)@karO(P27GW%z{&At@f$pGZkc0Ex=U~%wK;P4IsnZNN>b+0hI01Yq*a0=7k zId`doo*D8VlvPt^1M8tDP0K2%#UAfEmlIVAl84yum&7LD0O_)RoKNN!d60vi>z@l1 zVIe{M3b1zmFy*Fz8lEmqtPkDkxm6jZU7F&#bkYTkh+a>M;^)!&nZ+6fJBK*bB zgMES*I)^{mA*PXR@Lp(Hf0$*OT$=NEpJv(H-@lATo^mNjGV5}KsqqmJ32KFv?o-uH z*lMYLpM_{ri(^=(612Y{-?v2QY`CT!W9DJ7dRv#lJ-}zQBCE;Pd*zz#A^i``J()qxN_n+4K)%~FHU^Chp8~`v)TP#Q^{IRG3Qr%` zS!6mYNhRvkQ0v4M3{T47i=RMp^+;IN-K9Th6=g%kpT7Xxd2CHz=fMaIawzOx-2`?c z5vy|3^MfU_!Vh{*;yg^mdjU-?;|y(Qjm(F_2pw3MEFP6+#QhN1?F_~Y=7hGBNkPypOXyI4)J~&<4-Zpz@5;`C0fJ|P=BlNHukcbV%ktAs4 zU&GPmA$r^*#aBsVLx4=N({{PT#J8t^Z-3JxtdG7to!eFswgnml@Y(D7F(L4LYxvCx z1RQf^rg1=Cpt+Y0!Xr;{ZMv!9k>eBwTx(CG#{7e;Fi~~AuyPZER0q&t29EyLHyE6O zYF35y#|I^vrlE_V|E_1c1=1-W!ZuWiXFq$5cf9!Eb~zW-6bJ&#iAMX}5Yj@XKwpSH zvL;{ix`+H0R}Jua(1_OVPyiGaX&d@Xc7^JIRx^Og-Ubgw!svuzY~SLAT4}UOeWWFL zzkCbOgMx7LtK51m*n}6Gpsp_TX%G{5XRwL7CmZK{m<9>2A)l5NI0-NsEJuPw`Bz9WA^9al-wRC_#CpKV^xsAbY~V~6$ydp^YnNdSYBxYJBnu&vZd6!j~xsz z@3|CGbVc=ieH@U^X8FMDa(Ur+zfOOWQg;z?X)5YDTOHG%3$j5%62R)~gf_#6vG&q0 zwjcJ#IkVcg4yp#LS&D$swY-S+%SMXAj*+T?3{(&ng%OML4(t$kjj-@?Pr3ySyk{nm zTJ{$d*-C;fVd`)jrE!zgf6rvIG4zFt!zumZz*Fn+@}_U?sg5ecl~sk!ZT%#^+38xFm6IEq z#ox_HBo!8`s!n`EE-_f{Z?s^bpa{XoHlPg^CdskVBGa(b%enlZPoKj*upYSzOX8Qi zwA(NCUxPzSdc_C+A$s{-i~_?4abfFs4!$}Fjl6*@=8p~e90DM<1_XozN-v^z(u4J| z4*D>qp3!sB#1Es9K^r1vKTRfz`QL%7Z~v+_n;bBPde)zR!{WRlNP4~=+_Z| z!hVWAWO*JakFZ+Uc`TSIE%mIgh)i=X#N?jn$iZATnVeb{1~msV-m{zKQqb?8QREGnt6Ji_0=h)Yyf{s5RxF;X+-m0|1st!oAyIF>=2qQ?1SP z+v|N-!;RaQ>2lNi6Y zM;KM^TPu&5EF6xNw2MuiS7Z7?xFIQ}WZ^?ejTi+xm4mV0Zvh7jYk+s5O)D;x$joHl z4rFrK%Z5>Y(ZqfZXDXA;{9(}Hnsgp6iHdd2)vXj9d36^-m3ElQ2Kr(@>Bhe0cIngS zKxGpqiHbLf=O#GKx8Zr*7yVuli=W8+?1eh?zRiS?xbbw= z`2d*-4w+*c$Se&<=1F-V^VcBusD-ztw)ZDAc$j3lP0i>yPnx81MV!>X>THgX-upsUa34ivS$(c9ohQ6 zHZL-$Cod(^Z64K$$rX^o0{>|@2A*(NsnUsY>5ES!68cw}4-;!EXi?@-qkA)7FzA{5 zikeonF6V?qUU^U()htrXD zm3%V6PI!^ZFb-%iSxKs>X`)8PkV|Bjk_Y!^4J!wGEu0TPt3e42ugy#m=&f>$Mc7!i z#$dkSptsv>19N;$^nBvvO8VsIfv!)gg!_!g_+v;)f^Wev5F%!NM5LPFK`V2jQmLL# z_yRYNhd(mCv90s`B^ZohKRX~nWXcvUr z)%ELOV!yB?kswDS7*}alj!x|;H8&L?%iR4>@%cBZy`&HjBrfSJp-#ASjwJpG=w- z(bjBGuNx$QOg*}4S70fFKUH@~8yS#g<#R3e19Yx-1=mWq$Bzh=@93NcUxyor^x^#j zoPrM?GDVLv~&|0^Enwv$2BHL~>|;on1IwUULp1?9;6LOw8s@uJ_k z=3#1@i9{JAz=%mrMIkk~6;`qKz458Lq0-so2QjIA732iSmmHRf1x^4WCP~$sH~Z

&r9!=S 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 bAYz)ocg3Quy7>FhyQGUa&}{8j=N zaII#XJMnvZa8DWa7l7R}Jf6n-34Rv0AH7yN>GYa6OX>dLGPg3FH-UrPL3Y~TRxFXV zwj|>=t)<=Qn0uxjChjg;9Vz`{3U%y8IQM34IJ;0bRg@R4OIcy=a$KyW(*jeTLuZ^lHNS#un-;TqGW0_t<;PCU8 zB8@_e=#KgQ(E2`L7-S)h^E*|&<#-2u-3Bt=x^j*pF|x`K7VPmJ{Lv55cg<1#eCNf; zyBs-kg+!?GHRIp%>^pUB3Vxi6G56Wcurw+&T_3F4` zjth_Ea*Tz=MG+vYDqz{55c^1r_3!Lt)vdMgjS5)Cd+ey9Cs3By_KV6+c zagGVnGSc2zIuUN7swlKuk*NIY*I2ojaN;%0#_cjHR467GV%nGE9J{C9)Fz}P8(%xG zw$m)K9Si-B;YL~1+oB)ap^S0hA?>x`x?s}}Yf>WQ0VK$~lHtF;#~xFy9$NbV_nT4; zEk6_8!pD{^dzpmYBlHrbbhV}r{fGtiXyQsQ%ZZY|EgZSO74K|^pnxuhzVeZ> zSQ;uw4vCoRLxpVkqXt*x#^>L#$VekCr>5fL@bWZo7t~$hscd;hT&7umPBHZAx3c4e zOWk4z)E}NQn!@L&-v_iMQjNyt;c35OpvS{Diocy8iuA3FZI-82Ri^axyW5z$Zk8?J zo{>>iK@ZTSyl_&9M_u8B;5Bo}n-t9A20XZq<1 zb^enrD`0`nUgn*|;uuBz*`Ye|>GD#>Wy(=tp7GK1`)~5cio-}eI8wp!pW@H|^8Dqa z1#mbM{NT*n?a5Sl>nsv@)aMcc$lH?N6liaQ-`2h>_7?J}S~^`Yop0bfUtm4uG$#vs z4m;#PF7EU~FF`h5fc9H(GiFQNTQ3u8>tI+K-5E{oO*=GN>Dy|>5rYZ6V0Q)v8ULSL zp0_=VFSoWl>JH~<#bXVbu3Cg-*?pX9?(I)-8%yP1TB)C&eoq`fO8N=U;TXU&D);fxKOb6ejEd+t=HO`MOvKD$q;HU&rz^&f8`o|mCt z?il| z>)~>dy&jp53x!0EN80U;Qsr)_ghT&Fr;=I;CzFb5Li^}U4*zj8Rp4+X6z1;Nitnzi0KTOoU zzzUilXd;3c;2kBQkAtSU*38xdDD-@_#Mct2y3i;OOvldgxlAiRkRW)4D}6(bS@ONq ziqmSM&_U;ewSaMfe6;E^2nH52c!prv+ z)tOfI`wb&7$OYB1eJ*v}Us_wJy}y6f7cmm~b&OZ~rQeO@FNGkGwQK{@PM9gVJCq|Y zuk^K-6Y8%4jh69g_B3JFGEKmfFO8eh=kIIn>YxL)prF6gu()e!newFws~}$wvM}S< zwa%A+=Fjp7%}rqA!8Arw6}fD#Fa^YsKnb~{mOHyfVAf>Wf){Iwtlhpdg}#^&jgN=Y z>o;V!=Sfl{SP@P+fM`ELEs#vV)Jn3Q^V25?KI*zlan!_d>pH9y^k& zWVXjfghM6KtmP`zQJ6k0z79HCDk#MC{ce_fHW`DfC~>*HbeUUAq3?4jr-hjmppp#-$_#&S)N!}vIF*%QP zN!7|hg(d_GetuCPT*Oy>PZR23TrXb|AsN7h=KPvG5;ZVT58wJHkauP>r*mCO6ct-aa^H^G(VQ-h9x4X)34bwr+Cm5`L3zZ6mBmFE`QCIZ zGvjx^cUl+y^N2tHo(dibmJgD3dRljJNB*g!=LnO57@D8+Xb+uYQVrDXw=kiP-;cqb?H5R1a~okvEmZABb& zxO*dFgwgo2a#5lq1U3XyoE+qZlc;_-FTgTcWJA)iRw3^P1IXVZD?Y9r4_AUpGcd$K zeHJm`?+Gh)92oNH2bb@YD79eJY2Bh-B9I_Y$8#%yHw)e~g-lbM95&ln|no7dP?p9)S1+$KUmk^R%gZy5CpwdeSsNCc@Ah{o^Gd*JLre zE0)STmdlyO$wafnvzT4tzy|d?%IQ{((u72NAMAK55aZE;`b^|QU=yDvi9WLxpkDR9 zl>P($E>#XMXWUEosSbXlZ3}5VcL&9O9E=u@crDM;kI5tvXg11)ko#CH#jHzg^ofj> z8Wl`wopZgPE=q=in8=zayo%ie=NpBt{DxObQpeTkFST7RBrYPn=s)f*mZVwr1;*ZE9em z^>1I@(GCn^Do4sptH~Iaf464T}Be3m0Pd3DKIjD)hc8YG#SSe%_bn+_pU&m3&>9EE>BD4j0+e|2Jp^*xe=Cw{f1SOFrc^wsV>@lWD5H0t;OIUChlxCcn z%BNzb*Ugr8qxMG~v)kyLU)Lqfuk9Z-eolA*Gw3Lo#C#%*xy%K8v)iS=E(y~4*Q?yK zf3M_eH>SyRvgB=7g`ZSXOQloWy|Y1#t)g(DG<8}ZrksSwgCyeX`d6R@2MSn2dm#I- zPJj|mQ$&3I$D@#bj7bz++lo}Uxnm!Ki6-_$A#0C5yxFd>AR8dA>a`Lc0vXrrM zruVLL(WC@__H*mGEF|8JOK|en@B<#f1K+8>5B~PdQ$*;@y$r(oHL4n#)q8Ec{X=#O zXy^P4VZ_el@uO(fov~XWX_?ruZF=tcaI53Ubv?JzUVt{T)ieS5K4nr%`21gad3HOP zu>x-4@Zx7As9%uC?>*2jJ2Kn=Q=R)>jM-~gTzvrQC?5IBKs9qJIWcWvvG>i{2t%;I zBTz^jh=)M^ID9J}d2D(BLt>3x3!Eh?+YB)-t+j);RL{X-SZb7`7$WVTYr}@Gtwxtz zDpP08J|^bx--mUrvkvNs_|lJe+4!a=1$ED*I-F{)XL}NY+3V6OxGap(BJg7-vA5V+ zzF>IUu(#ejL9oNzJqlG}?3OBwL^<&iJJhe96%U*I7B)CZ6d9@6QbWNo{y6$?r>BJk zc%ck(OUS9RcfL(3XTMbo(u;z(Z+Q*|QqvA78n2ztNQs243u$60KN-w`!%dz~$w?3F zjDBV1T5`8HMUlc8PJE}N-|@sms`O1|`p0s!j_zXrei3zG_#M8`2e=5C5di}4ZwEhd zGD$mqk3QeI0iJ_`fPj>KHH~0=en&48wuLxIOThk53&$$q>R+b6PNa2$E zn-E2+VmWdFN5-ffZQOaHM`TNWwb=qU`9%13e;LpAo!A`2GVdeA0OIvNv{Qd$89bzAcxdsjJ^hh&QIFsfLi|9lB_$!BP^$5vtmOJ6v?j9D#!)$z z*k6&Wy5&PHf3?Xjo*wED)&mPPZ@27km(VEvpLJ6Mc+-OE)F+0(=T#ZG&fJn`K~F_{u>WmNzds84N*`+c-$b&*@z9e{gRlBR0{kmb z2#?2_G)n4LRo;2sfN96pAP7ZLl3Fyl?2AC@`;=bZplVtu0+ji-yFbONOe9ZLp^#>p=-(|$ulT|YZWsEuuK5|ZPm8Q=Zg zqiw#ariwxmn^%!QV+B*tW#Ur%qL7iFK5l&snR8Rof< zlz_`ByhKi;qQe5(YRvbH7ZrwYTdY6kBCJTdrBv?R`{S)1Q(XTBMI+ef!esX5C#zk# zM3|r`C*IU5U;*f!DK1R-xgbcJeax2p)T&8V`KIcv=<3(#VW6bsL>v$(wB#4#?gx0- z3)hO++tVRPg+%qNacMOZr}a5rSG&UTLQ*+=0r2EQmOVo^6}%jD<2Y?D93x;!j{3-l zksASIAwa&MU;%5OH3vJ%8Q1eisDd~!BO}GIHK(d zeov#rf^UbVMeyto$&*G=0@Bj8{~BNL1S@zX%Abj%HT|!3>-ap<&@eh8XZJii@;pM) zg$X2a8#}M(B>vlC?RplL-w8S0?H635OG;u zWUXwZuE+Z7Fakn$R*I8E23XO)klC5hX90-(key) zNn5b={wc+;Lk3>NAkOXgQXH&-ghR0@t4muZxZ|&a_H?htelq8-mR5Uwenljo%u11) z!Xn07)RW!(=xS7^Ad98#f^z7yoHOZoc(&ykNk3|71<^QkItzY{!)Y!h<>>EUV^p%O zys#o&Mlk*@;feW68;T*p=i{l*_ZrOloO(}7g@&*>of~20&sipRra0#)`yfA8e`*O3!s91Ap2lC8Dvdt?6vGWj zl27L~O@Y$yFz3BlR|yV%qp&3veZ*VuKS$Kky1kM_l?2qoC0hlO{|95*JPQmZQfbt#v9gagwB8ua zlFx}zg6+J>DFa)!VAVERx|G?j-z!KoAsV$nR^MajOtpD4n7P{Jmb;cPc}20FO7>a( z!slk8onNx*c&kSrr}SJKo1R{&zhFM=Hu-}*$rneDoK?v6-9-GYEDLld(;m+stIokNx`oJopqS~4Os z91YoW_Ipt5IdmtJTT`)vl)uQh^LTMKTA3x+sX+f{ASSVHiVJH#x7H}9#L&~h*T8$& z=LJA)1wS3ml^{33MyIi&0nwnLzem15*NW4yH;{kgzL8(e}{_;y~K!vA1izvf=Nk3uf5B}h%A4Mls(F>Gn!us>> z7UmmK&DBa>FS>&E~K|El_`FYmI+bXseL2 z`Mw6-amyn8u+VRpY!|9MT=^$lGt1sA()UwwFen7ElS!By8Zn#uEWphh!My$I@Wpk2guq5On^|W zptn1%qRTXG#gZvoVi=z-V|bADi|5MT(dzEJa!WjF2Z~)UMl*rP5qt(|7TfCFZ8Sv5 zzFFHFm6edM5lsUxQH3?4aI7IQb+I?2u&@1)aGU#FkeyArrXF-MGTNq7%DIMw-(}LI z!A79uSay|+i@iiYRna^5ICQB}M``?gflSb2`m3XL^aVH8`qp{xmg^K>`gsRgbGhAD z{YpIc`elp35bxyU*bCzu6)mmjjsu3*#RA6 zDTM25XT8%^_1}*tf)gz#+QG#{e{tgC+Qj~hhxy!tCKu-L+J`vup1N#Ii?#xiEqgzdV_#r~V$ z$uVST!kNZM&-b%NtJbbk)eIW1c2`3a-FaCX^G;uWqK}(e1deYH-zg3J{v8)Xa6}Dy z{rRt3J7W^WPa89MJA|m_hl{JmnW|uI zOT8>4v`tK(z*(-aSyKP;4OAfeS+HCFDikP|ZK|fG*2X8QqFPUen3dOGi@rHsY1~RE z{QId-k*qd@;6Z1h{Hm$qR0yt0mSkb|1sKAyvZ+;L5#v>pQRHke>rT&kM0NF@qufuE3J!!@{h@1lH#g}aY$1$ViuJRu8H5W7xt@=a zu)T%zaV>7z4fB)OmD_-{3N7HXB0J?eNzPZ_#-vsC+XjN+_~D{mlk`B-C$V<{SBw`q0wS6Ts}HpH zleBlS5-NI=DtQ(X8JDlf*fo*!(_|t_E_ppJWHkajJb#1bk10TEh|U^uLNA%u94gr5 z6cQrk`rCQxatzrjUZYHRlh`zZ(vmEis72>{2(w@pYM7O8QCTuS_(`D3#H>c+>g ze<|s@p@p990VMRu`O;ii#)lpe?w%=DluDFINzpB!FPztOvO4Gw$&^Kr-%Q(7<3*d~^ z5WW89M)F361}}1Kd$VH1t9?@uV+9c@MJ)5f8eTvw2n6l>Igwdz29e-A672;NSJb2Z zZGFKO^VrT_$ohq#_Q+l_1SD)J9z@XF{*ugdj?A&Ap>GsjeSDc-GH~iDcQIBDgM;H} zuDAM}Qa#Li21T-9gK z0sIdlnlJ*A9*uYA20H_eC;$pj3i8pX060k#Zmj!X0jo{|pU5b#qkdJK1pcDv-t^AvP zJh8(R917{W(iT||wAA5dcY%PmT+=I5nj^LEN`f>Gr(*})pScz=`Dnf6u}pizj)I7$ z%L8HttXvwhm!P8jan=^e>rO86W}lgZi`z>e$E$vS9R*GYb{{Dc$ka?hPeu8D=q=od zMoxzln1~8zB0yPH5P~nI`&Me~1En|;2qH18HT=*1(H$)S!p56XnTp4I7_%awh5Bc$ ze!u4mg3k_xcV=HkQ-1El*#D`pBK2b?tU!QgaF2lnuc0Y8d=QkW3~kP&c}lYSV3sk}3#o@tXl{wD>1Hnh;4B5N7+ ze`Bd<0JP50Bf|$$&#;9RP5y`Uvwq0I?Uh+cvA|gAW5(9Kt_P7*dS@=~cSsPd!?y3# zCQOwm*s@NVu;2y&AQOz>>)ZZFVKKi*%w|T&3szJZovg^4*Zc4+A^=#Ja-d!)Mazgb zZA4F56=Wp38BhA~GzcIIG33=kBHrrEDZbzCkD`lgN^IPwGAEfRk$-YP0!Z-&=`^=~ zY$(7E4waxKHJL3=6I(YG;q~ee`o~>FNd%GaUqz%Ae{F{{vDBX`h%PUsZT-1Tt@BA9 zbb5G7zLx`qTaNXaa^buq;*OPr$#rUP; z@|ca!zF~}rNI~n*&k2`;o_{MzEZi;LzSb86DrXK;@A9GQ0WanYNfc!mG560tUC$C2Z; z_Hl}%OKukZr=O90SV8lX%PpkN!`ovd6V24G^3~(77FLdMN}f47C{^w8ht=FOE1DD# z@TL-$UVi|nYkgs-j-~DQA1^B?U)A@3%hzV&F%d+9eePfh9tEGKmrnYyEWdQkzHI?i zwPQq0h}D5Q!C%8P|h`Nm2{e^!+|+GrMHL-w$L1B@4r**5>kILNFD&8hZVjX=ei{;@Mu$|vQPvdGG?6$-fdQtHn1JD|B z5->U4c!heg3u%=>`Sq~itfpybNU*lZo$hrjea<&!gX6NSbSLMK)w6*Rn#Sz2kuSED zyUkB#2<5qLT{4muY+>fK3h9dUmb@E^NT9r2}@e+4rYi z(b)FahqAg!>$aNmHW-X1ripp2ndOuxVfD3f|3)~eNLCD;fi29M`1RCu!7xWoS#04@ zgISHh#}U~y9j&LsE6-bp1@EWK4Fsm-nuE1CcM)>ceLO`enQ^4%C-X>P`NG$oACHAK zVh$UwOZ7Wjy0R5I`W2sqS!+(3V(e%~H}aY~o)9oTVQm~?#oP+*vtK0DUt8OLbxT77 z87`Ri>&bxg`<4!_KS8jsjVyaJQ<06y!L1D-!Mprl>O4`yu0k(P zrtme6G@?eT-PaT%(lX-yX_y<}ntpKHjuGE(8h9DEdw9hOmCwAqI~r@`3>3bnFky> zlxSdyECzN!et6yZ`1rvjP(rL8NP2(8zqdEs=(w)?MGVFz)N~!5k(>0){m+NJYSZ%D z`qG6Hzx9&$wIJ&=f0}dn!o0zQXoj)H(`@&s{zUBbwD_5%4_g+j^j9#G+Gw9S;671FrdD&;1fc4gr`e zZPYp@m(E1IzoyV&H{M6xT5Dbo0oqj9EOiE)0U6b>M_BxZKrVF!DwzkX$29PF@z2YA zximA^c}Rf((572mO$}dPVKTBIwEWd#dU4BvJ{;K@3Gz#liy4UvQAk?q$W^OT3d<6Z zPwl`VcLuf=qcl2P?p`_sGVx7;n}?%bD#^$br0mMdF?0-!T_Dq-7D$Mg3B_mpdkXZw z7%6MNy*ijz-3#8wvh%I*c4av3Y=&hsCD z`DF?_7kGjUNZrmg$sa6IDVPN!HJd1bGfmAapaqg!xnI*8JPtOKzUTvO5fPsVGNE~> z9OZ;fGLgg;&?#YNG)ru^aXq8Dzh8!to*uj}{Y(Bjg}s|_U%YDLm=rE_LNM#;*;@i> zm@!k-yvUF?X=_(Z!M)yN0`$#iPWzcx%vxY&>NNyRO1KY4^1-D@9SS%-C6nd@T}+3+ zGuzg-6N$5|r#0ZbvjYY5SzlsWZTTk@%!tW}iN|$k^$Rff_N(!>-%5mE>i%ugl9k-0qJ>@&5hswiE{^lbQ? z=2=tOzeOw`m_p~uVI+9m_hR{_DCG_uWho}W*sLytK1|_ZZNJfgZE+dQYAozxj#!%y z22-X9HFvJ5Cc?t$b2vVM{0L63tYG@EipCzno0eHCtQryl_CKj(XMF-3wsxigWMg9} zc&PupAv?f{_^kblZlc?ZZRdrXjS^i~yps_wrV%}!(m}gqeY3bS=E}LxJS0M|hRVP2 zz>Hw7BvmYRJC#EVdzJsKOL5yBI*#Wp)_+5@ZJ9p;Tm(?I6aiLOf=O&4+)(1_6{1<^ zy?35|I=VJ@S-&P_a*D2-xWmB4K{F>IR5qQH-F6P&j7pxV*odK=M$xr?3?C z9FBZpUF9b!KV8{l*8Y1P6fGW|h^sLbFbp&_LqFO#U7a7Mq-EYk6LTBn7V&JhC&L~ofnjNL2<^6cAU7Z$k zBqgSD5=+SONh2%_Qph(qy{2uB`Y8$21r1fcOVia~Ze>XS-Rle|30ukl5YS0!8tJMm z6$SMxmpuWiT4zj`Ma7(RoEP>HZA~v?O}9QiU-}W+LPa$vQ(`O=W;3@zp)W;8gLJ?1 z_Zb9&ioS1GEhd(nzM`GkS%>jlO?x=b3N(xmkJhoGZ~qC+*jXlYpIAv*fs-+^ce z({=tKI_jeXs0lBYNB_5##+Jf_Yjwl1`aP}Q!V*B}W}@n>{OnIgpJa849%<+47E zp+Ibw8_4(JAuu$-1CWtWqYb#?(UR+mtVhs_;4?C z&zzn+GtWIkxVoww1}X{avuDpR6y&8fo;`zuK6?fqjf@Cu!S0Mdhh3h#YRE}GD}$2l z!2VFTc&}ioqVkLxc8~lF?m6x=_$LzB@3T zDhL#z`GZ0bcK_7OK|}QiiJPqm&3hGfDk(=73o1T#PIgWjQB*1_Dq$CMOF<23*}uBO z{t}_Fc5`zQ62 zergp|a{*YuBtP*NeJ%V4<^OB@OO7zdlkop2^QWbMw8BgkMHS}w$8Dmh#6~Mf&z^}t zQ;?R>1U}!-c;Q1PH{Puj%N8_*?K%|cJnG!$Omx_B{(>VN%{Y07-RDCSCpWiH`kNo* zjFy%?Ke+~Pc9)8cqNW?i6=xGXa+x33GctAnKyIP4h8uTx*_PB~Vz`ix)F#M8|6Ig> zAe$3-Phyh%)AILoskX4n1?2xFCqpK3j)tdGGW`#aKYBRVc(-A5BA`E)`sWe`|C|=; z{Lx(Dzl~2Mv``PMe^vNXpfi<8mjEW1HT?gn2Yc4_>+nB3|Byh1i4ggw_jxS+>;ET@ z6V^H>@?YzoSa$_{#MycyUP1RirhLS)YDD@U%>v$FbFPvh$tQOGk13q1c2|Gu`7al2 zBskghwP*dY|7(hD`T@oN_XH=xs(4$ND;bq8?!WH&gXBwyg!%<`-&~y@UzwrC1&Jja z*WWfVqXg`yPsgSt7%JrI|0oQEnW0&ai&D^ABtvUHz)v_Z01~ryxJKz4tN4#J?7qIf z_@0BycxdAii-3w3@vEtq0g*n{HnW$^Q~UH2i%G93$!LgYi|+1*wTkSgiT+lIN(=j= zxaY6?=YWaFtU?X?V!0PICSCP#?W)>u_guI7In+Gkhe4#VTEQE({|5g#LIZ}cvfh;l z?e|{3Vt6<{f$yjW8-+_o<~jAK26DE6e}+^1hKdvPQy{j{&frG#r%ft0EL4mLJp;q$ z{Z&}ZwQ$-Ee}`Rt_{oA;VlhMgVLkg{-qrNYtF{ncG>fx5Uce%1am(L?U?XHZs6K~M zUUNQe%icuss`i`92odsqTkx%J0bP&yXlJ`;>_G>#7J@l&7W0i7Vg{E|s@u=jyOiz} zDOpPuKKX!#q6(w;ltVJ`(TTbAGs4^*y-fMjnb{E{Y9a$RPTy_1sDjaaI=s! zx!)Ct)#8>*^%QZ5I7@REl(ymDrqXv8u^BYW!17pkKNtY$lPUE?hm?9Gl2ntR6>~y= zZ^)(y+%5IL%G28lC-lsJXQ|jZ9Tc(r-DV6~m-CQVx6#KGa^HW~@k+8ZeOm9Za>aC) zcdy+1MkD2VuC#$etf{rgj_1fFxl>GE=u>}1h`mRG3aNI(UO(@KHw z!nwLe+;5%P1WOe&3Wxl4UMJS~cCUP~9@P0tbgAN61oiW_k1A?nnJ&kOue2*w-(8^> z>K2DD;a|k@)$Y4jc-iPHr9EuPs7NhPU+B9F4S-y;8Di0QD&|D=LOtNxN2142!u%Y5 zUGW__eYvY%wn`D+H%K`hexa3T)(b}?Ot{_V0G(TYHVYOqP8_})0%Z97Ju zf6AYp)}|K=z+GRbEl7cr_&S%{#ZRJU4^~>%FnZ?1^&Ej|+CvX|G395Cu{XL>B5!_% z%)d}z%NMj#MM52q)2b{;a@c613~v3*(-aL%m?>qBY@IC{DRck=H=2%EDwy%LwY5E@ zLj5hZ4{{PwPIAwP0fSclh0?&UxD(kHi&-%Q0+Fmmy7{exv4z+L7m~p8m640l-*wy_ zJA96Mj0;y@9Z?j+l((8de_>LX^*tLxR+G)+exb!LLoa2@nn!}7{SIey$BT|qxEzNb z?+%Zx;x2C$Gh{O?phs6qbI%EbuNb}Iv0M);PWsvNI?f!+GG1mj$AxAX=j>Z>i#e0W zr@E(xmujgaklesqPD;)#L?%nKtX484OKy2g;adlkz^kI)h$u31J%bkGAE=?q%}?_iHY zZ-(O-KK{(WcI{`(gPSgNQhq>dOyu>l6QK1zq2rik+V?1bK`|0oKfMLL=#TK>vujo= zfa=??4T#Ua-kZ_qy%$a@+iDpZoW+0l8629}{6MYmE+*UK=ajr|Kjgk+W6rN0wVKA| zc@FPzQAqRYr4QiOnKa<5fAwy)mWG&Ex_QsY%;4wxrG_J*+FZf>SBEu(jkMl8vn`6faYrl=u0D z4l}l(de*d)A44S0p~d?7?X{@aCB_G@N5I<6YHx?4r#{R8uS z&VOzJh#z;tsX0E3#2FyjJ^W;R5vZBYyXfUe4{#(@=s@#|@@hVtE_b^fGpHeV`dV}4 zM1OnH!Qmtb#A|)StGqjEUbF8UI00~dNPl}}ZFMr?v`FsJ&~E73_e=wPqi@erOc)be zxMaL}80RFp@Nt>i_S&6;DO;z#jWpQ?eUg35;Fs7b=j5z?Sa$j z?TS&l*rxN=$%etWORJeY4psiy15mnr%+|p;NINKJp)I1?0lqpz$zm)=$55!wBb@7$ zW{K~9#F=Da`F_4`!3a9nq<+MY9vPIA;!8TszAAOfSK^VCdmZELxO0AW;dzon3l)yB zeDG45WR;&V%d$FenOD_jyDODX<-32_@$e2a;d-jcPR&^vRf_<*&-0yo{2O%Dx z7{r*l8fx_v~Pj-+-I?>N$L2KrZ(evKk-CCj-`XQKzAE>yEuj&o*y zu2R`&7ww|PA`;*j`{;+U=6M5}`%KBgQ##9!9hFo+(1^3j>7?1(_W6N)K*C z<%R;?ZgTTSvq z-wAgzB1OmCB{N;NsRk)Un*NbUV+R)_s0!(WOTNeA1^dqTi3`O`qlw#dJ~`>_kIRtD zj4Wv5gH8i8Q+FDwC27L^g_dF2Q5Xbg%jv#WU{%O-fk4GeW=}+u_af_+Kml#)#-M{oc{u^5#PO3C}GA&3a=yaFPwsW zV6RAO|3l}cu{F{8%`nIGq$Jx~^I4(U_J+3&hbLc@vicqgRD6Ejv(sD@-<46RMRLh- zBY$YLf5>g!vB2E32ACdX$3c0&*!3+a-bYn!gCtAV%d$Hv!%;dUq_n4{g+e4;h=q;D zFGF}E<{dM)KGyc^wr^78nH>y^h@D@>w+g87*)q( zLzC*FNw4f4@-7sIj5W8~wAhJR=Es~Jrms2uQ)!!lD~K&@PgHr@H+BDLx(E;UM=$rb>s<3q zJwsTP=sEuA;JSWQc1W7gHEBPuqA(zXd0U@N=>i}q$gEBD>Y!#;b~)|InRtCfN#<}h ziyx=uahwyINWLHvh)Bq>He~#`CPg>MKd@2NZN9hn#t>SpwuK9awZalLWxKcp zn!Xq4E8V6t17B9phD(;U%cJ!i6%|g~t^{v&Ua{PUSB;yM=br;H=*{lUgQ8{c9(oQP zG{e_UNESC$_H=@Ogo=BTpNeb7aDg`M^|CW^lNONsW6(zcPuOo!pK*M?jJtSGvY#$L)!fh|V^Rs_eK&8uvN$DL(le{>KN+KqzjMqL=m zE#}^pTUndOEO}(LHWwRh+Rj&E>{BmBq7PGml7!--@!SjYi6#njXh+Th_xcK?S&Osd ztb6^vn)bk8M1vHA{#O{ZTxdOF*)tc8W!VQ=Ah(;kOkw!X+)iK2dix?$sKGYK=6QOb zN<_8ro;USgXwJ5wJ?9FU=@gq!8op6BCJ<^=2(HRpkq#s8aiUrxF1zeZ+n0;|VbHHH zbvCcY6sw5r1Z?8#NoXK)r+$mdH-at#s5p z>oxL85G_aICJ1y#>Zr2CB-MPF9br-<8;)}2HLA_=Afi0~GscP{=!*%EJOjyptl%36 zz=)ZGTS4Inw6tPs$J7J!;NifHE6C;2-PNng`w&f;%ssB`c;eN@D<@1-3Aw4?8%G@W z0th~}zD3sVoEB;njOEXPY{A_IAuhTJ@4PP?$BArE@!mPQ@>ivJsjPG75povEj;SoF zUvm1gDaAvLJp-v{1>>Q!f-=X#Ief05AgQ44b!%t0i_6y)GS zcmb`gv^Q>}N@mJbUD=0O#SaGS+QM?ARX@iLzHzJSK4b4{rKGR-VQ#EYm+D7G{kX|$?DRhJ4W zcs#9?$32fV`sgYQJ;IK~55NR%=zR~y-YRc*cBN$V-Vm7_ZOTMdZEP$_ z^!$p}XNw%Ua{2rqOo>K&t;;VQl@{Eh&iRuX>EBhEKeU;>EBH}AJS0Y#L32tJgV-7GzfB=kiYDVnVFCf5k$ji@_J|Z)v|)Di;N-6`2i82_{ej-h zMxlOQS}FH11K2zXmMjQFoNiYLar<%$5WYP07Gd{qg1=_{6}BA63UFQQRW;rpX^V@< z^x5@HvJ2n`fCoAKzqv1QlNAOZPZcao_ILSESX>8(X*l>Eyr=Fq$qB&0*u+>44>^}K zBJMsV9|I1qcuEyC$e(F^Cwb9Iy8FF4TAo)MG=HjV{ANVx4W}Lwz{)LfL~AxYdXhqJ zll+>TTrkr%a)~q3Th?KlXcPzV(~_V66dzZ9qGK4^`gUhesAOM;eD1oqI`@8 z!3gqc;P}r?I1P$o_HB;l6BkotGF*i;2nm%+yDbzA*EBS#=1sW5Qa$0Th z=nqPYujDZ(WkgH5CUrdHgX?=ZNBNF(@s3bWyt-A9k^H?95`BigD4h<3F)JX2WdC4Y zm8>CA&87?~-99g>=_bwatC#>G0;X=1&Hf7sBZ+u?0_m@IhZACp3t|S0OCX}_0Ze`H zor%$j-K{MOHS2+|!b3Bb&q5SYBhBkbUst~8FFJ`SF5I_IoMx(sww zvPdr^_m4+0DM$3_cn0(Q>GY4Bs$FG24zdy^{;)Qp_s#YpLs~?>>bncwEGlH^`obrA zxTU0Bidb=34iIIz&_$Gn88}i{EZ0Yo|)lhpr?=)Jzyf*pDjAw)^~pDHUF6 zQ|-%gS`LDyF^NvwpVDWhuXM6{+NECCQsaS@ji{)(CaElEt&ynaChLEMjG>WKJUeg7 z+;>HHqz}pCmkUi!8o8NoZUc}?RnvnKs2sMRk1;*|2C@))7>C^5_&Aaa`p#?&`cH<| zWaqM%Z?Kc@8Esn(N7x30#L44}2Ai1wPyUZj`(_cQ66s$wnefCPN*EUc`SVT=9>9i-IRVL_j-e%`W<3@=tzOZ3qP*9PE$mTwtv-{h&h;c^F_ZW2D&3Wf3N(}lo z(d>88w0xL6*T-_aPNVhvdM8@u;WwK^K}4J_XLzD_{T>)8gCL_GVS{%@S36&PA{uG8 z(uw2BfJ!X~puB3oaKx%pp3A)Rs+1Za;n5jpI7+54;{gO=k3{B9h&qi>@ss4W>hpJe zvyiMv8Aa=Xx}q`&Im1b{&$r4`CL2^Yv^7Gp zSr1^KHTWcpj1ns30)Gnsi$M~xvq;p9&}gf^RcyHlik^!{9L(uUc4cHmgM5sOiRmi0 zNqJ4qfkVA-O*$)c9`1%q6$AW@OsUVHMr&+Ja;Kj0+3wq$QaCa}?1nlAawUzh39Dii_>>zMaW7#trNeHSbzZ@)^ zV-|+kM&P+4A%LOu8LzAA<+YH7`sgIZiaJ4ll2mc?1gbu7C+yvRt{%`2Eu>oD8T5wM zj5;Fq8ZaJf!Xk?`I$?rRg`5;jrIQ5 zQ5r~snttYJflJ2pTo61BVjL2ub{i`XupKx55>jeQ?!XpBk<|gt`paZoPoiy8Ap*53CI>=<1 zH-PhZ7-}JM>Qtc}GIn^tinOqt^1-#IBRR+|-xRa+$cYJSn4=VmA4)Rcl|vKNAL zS4P}DIb?Hif~A6*K;_tUsVH)bpF8Qp2oG|G;Gt)5D%+ z;krnR$hnemv~h#1I1uKTPnXvUWYns4Znv}Aqh+8VqXlEE?w6xUV+Kt=oLq`VzrnM? z>^!TrUS)Z4(}$fX+AOw2Klx}{&F^Ed*Xr_s6}^1p3&{dDow}KB8lPF!BR>n4T3b;~ zZnVt6(mL|z(1B7O?K3W10=ppiM$d?Hyl+NkK2=6)Q~ImDIHAmb-O_k)0`9@~gW@=G znRFz?$hTivgMRq0ZsjY+_+}-Lt7(W-Egk`t!Zp4shjcCQs=$;mmmFviJDP)URCio`o|K z$~{ZI9m6{W?M5=DVkbd*np=MDt)gLu?CNj7q1Njm@@4QKcFBr(kmM3X=JsoGj_A+9 zc5hk&FPRKEBfG<3c!JU((!xF+pU*}*g7F4uJX`BhTQ1*Z*H2uZ`Hyi`5pVNhpMUELrdUExCjP?QgDOPpi*KtT$L3{Y2899ny zKXh?(KaM=s8`+ka9;0&RSZTj}ZqzolA-Ct92R`ZxHn62&)5eSjd(%lVd`|n= z&*@~TO)h8mErD`A)Do9XNY9MpISK{G9$$oz+rrw1>z(lFw@37S@Z{N)552tX=aV>l zi7%M^{5~gaS$>MR8eudS@0Qs^&Qc#j#4{pBDzdIi<`)uv4aK#d_@Wr2<$)mEIMR1Q{7nGIv zqkp3NhVrH`jxa~b_g!`7ypsG*m@d=@V?9*V?JMbzNrg&R*@dld3sp-eHwAGYSiadO zNTw5KnnF;qkTEO@LX(K3zOtg4SR!j$AtblQNC$?IIP_Z{M6JmLo=4tq7sQ_+=k4*D zCVOR;iT8iD9}BCDs4tZYvK9iFOz5_s^?#0+F8gS%O}OXT*Sp)a{npM^S6krK*H?Vb z_(Jl+mkv^tOf_0=vi=}~X3N#))^37yI3(S^aLkOP+;~m;oY!}YG;4K9Zkgn2{s=_& zW`Rup#}bk9f~<($-&Fg`of;|_p5sz&DqtInyd+$pF9$y|YZkS426Zz^-VBby2UA09 z;MtvSreXsxbdYHP+VbwFZ}NZTD#*J-m^pU?FG(wU5i)nBXK~?7BbAR|&6F&Z{8UAT z@W20vAjQ7QsNCIGp?GK+8;wS`48+g&SPq?x%?ihP$Ie!qqxa;GvMG!w8Pm0G#j@%>+YWd+yi ztQE?FMp`<;xTWOG!~``cDa3wP7>1>?H!kd1Du#N_$`)cT%ZT39XXXm_;*$PTx*=|g z{d1)Yg^Bbz&1*L041?o0BV>LNw4-1EI>-_BU33arJ%}aeTMGVL)YwRz@8UdgKtGZQ>F6~+?Yv?7d2j~(l-tZ=A0P7E*8)d=UtgOhEo)_E`Wvua|ACw`iL zSKBdd+e35jPVZb;g7?Fx6TMeaZi6-v#IyHBO^5I5a!EqP2N+=Cz+W@f-!WflDfYOs^7EiVA0tUFW?;Db+vTz`&;ZoS=fB ze1KN1K!|pG(EYq&b=ys6%&(!yEUxrQ!8#XDHNCgVKg=s_$vt5o_93gGuKyaP^t;7B zO8r$SBQ5o@J0xtgM=?V{#e2}>@v5pm7O~ipx_UkOPQ&eegQAmUrJ8jo8~5L; z|5=ey6e`}^UK>IiHB8~0A5t`z{#}+K^4BVfvB0C8&X2qd%vi)yMEa80M9AMICV!O@ zVPnBbivfPEAtbpS3=~#WiA$1=)YIoG5IJXZ?`Asb>N|RafOCBRhWAf-pQXPXv_*6b zgu*ai#rI<<)X=nP4y^LYj@VfYeJs`YFW6}RpMuY&zVIN!fMO|<>V?jXry>hOu;T}S zYD@|rbrHI?8-zp-BGu zW%vK9glWSrutu<%cA&YaCE5ObuLS>o8N^+K~z>4N30vN_2Fl; z8*v>n)AsWsP4=Y!R_^=}BUnic_IjQKRBu`^!TaQ}nkBEUB8BLE{@bLA=}sv3pA}VM z0c|Z}3$Nm|M^Z}#D*2>xO<$Wr^Iau*n&Q@^E)rr z`K7Rku`~vlTTXp0X1{%iFXjm7V)G}``I^`Vb4n2}+`_H}GfJO=68dJDAp`d`tKwjT ze(nTeKzhmSjy|Zko?88*c-~^K?k|i5AK?+*L3q{r@Jg&#hO~`-^B2jDe8$F4Rb+@m zxUdR5@p_!T{()DX6bTs;9+nt@(#o!3^Z;`jPR9kVU*AFRxFWtcVFaMcJd0MOifF

&i(%^Uz~3pBph;jR*i#KgIbZHBHD=k)515sJSs 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�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 DO~F@m diff --git a/docs/UsersGuide/source/_static/SRW_run_process.png b/docs/UsersGuide/source/_static/SRW_run_process.png deleted file mode 100644 index ee0ff7ec76b0fa6a9043cb02a7e9ee7b211b876a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 81455 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 diff --git a/docs/UsersGuide/source/_static/SRW_wflow_flowchart.png b/docs/UsersGuide/source/_static/SRW_wflow_flowchart.png deleted file mode 100644 index 0cee4f5e65df1e0a87cef48ccc241655a357e3f6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 145622 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

    {-d6*21bqKd< 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 z

    =F)Egl&dopW8Pf9>;aHfTb<#OMJR`**%U!2!nE4br;VQ&n@O1l^?% z>spI3eH3B9)0{Ffc_YH93M>ALl_)QWqqOLxv?m?wG`s-*jX4ImGP9hS0bN8__tD> zWS6_~F$IW|MT&@{skTSy3?RsvFVIRS<`o@@_h`t<3XqbB%OXX}dRAqwLiH8<9hXkE zqz}G(pEqBcuf%pJt%zjsp~pX;+jyGzOGK}@q=p3lNoqxVD%Vnh6x&2zl$fg%X#s*c zK4Rm!5Ne8>LBi%VSG8Tc^UAxR45_jhws$QP|+nbwoo-=zd=4>rLB-`1e(Bmb%2Y}ayUa( zs%00&u9NBZy;@+cpfGoyu7Agw4$@V~_uFX<~8OpIB(k>|3&FHyHS#8pD zAAUD64*o(t8=77O-%T?$B?jioqBsI!#_q&((0I`$>qwENW$Ck{?-C;;vj=_;@?fuQ z*$U=~QoW}Oo04<~EG=}`gw9brNcAgc?<#-P$Jhx!VCB-%)e!9u1 zstA-ii>3la5EP-Nv$4HU$nGO$V7@Nt@(Bgk1hXkY)d(;7)?eQf)RN{NZ$<2!UiC9z z6DK%Nghb2GYdcXAqS7GM`WSXnnGg@}k?P57l8h6UuB$>_XfW!BxqJxVnV-U7k<^`cN8xnv-3(qsALW1$5b+5 znfaNi4=T3$Q74DieX9jRM{`LAAz|ZD3vjkz>32V|!}*oOhgp?k-eH%jdm7w+zEu(9 zd(T-^q&_a5sbWTM(X&Roi2Eczxm)g4SInIAwhcXtDo*m?Bg5cU9JFh?ka!z<)Ir%- zOmG+E2vXn~dSDoNLFL_P`qd@}3NkJdF;1TdMoz!t7l{l!t+9OlDf0D9u@vJEcCqYv z`BYz!ae5foJ;NoEeF|+k2&J>d4NOJU#0^jmKW-G;lfqP-5;1GvV{=wDw1^fX7Y!F$zygK@M2&*LSA%fI z>_OaKBuSDR=B;#Rv}<+vyX_?XE%62NPv;qHfTJO4PVUuc3fi5p+mYo2VzhfYt80O zEu|1wA8ihtQC{`%1rb(fe8ZxOak#``QT@PGY9Cq&HXu47k_~U58;B$V5G5?R_&$Ox z@f;dnY%?+sF1zHqmwqgo5{y7Hnx;5sPGq{grgGxV_(J$)fg0UiFSLTKncDX?ZJ@&P*v)Vz9Z=_|R$cbJTV%wJ~Y-gI??BN1%tirpIiBTW!5y23KU)^Ug6~P@q-k7 zPm#+Kl{>l{V({#10j(4(XeIzOuU0aSxiQp?z=DQ-{&60>NKNcEb(2#Y@3M4e>s6c% z$}=$u**QhZaJ0bR{>Zr=MMJ6qo)$Q$`o0a4U%`J7_1uRAr!7efuSzu1rwIW+KMEfI z@Y!~J(ADcfpHwKT)JAOxbkkP-^K-CO^0w%JL0*; z=aHcdk-L;1XjoF7)8TQ}RT@sj3vG?{cJ#G!MMyx^W&@CR(UDO=2s#VrddjMvtQ~$pcy0 z`;%ck_G?64A$NE|V6@<{N)G239iyTivE>IuVfiE`X}p|x(45vokA-=!fBv65M>Bd5 zv!=xcztd=;&{?}|sb0&Ma|e5&h6l1hov=(pM9K7rvv&D>!wrV8kc~bG#jO`_2b)dG z^LxLk+8U8-xQr5>U)M1;k&JD8h~c_r_O$_GVl_y;)eDj(I$l~XSsWIjleJm_s)~(3 zB^Q)Vcpif{m)AU3n1~C|nQ4LOQuj_5=6A(=wkR=Q^jz37>F&|d-PD>GJnm_@}WuNX9huEK+aKWDP^5=aKc@ml^sZ|Z4`H!h=d7zV@tN9yGl%_A|mczJl1&W14S z{ii|PU$QmPt86{?qb~E`KiH(A{n}iryx%zV-$lTAPOr1TJHB9T{cq{qfE;uO~b^s#p@$EZC$+cHLr5Z?Q_d9!5fRu7S44E*MSGRfjRb=)9WW`Vi0Jj!y z$PIXIbiCK4eY{x>SboLdSNtE2bXSMY0p}pl{i8^~yGkE7>&Clr(5BG+9_3uQHY*PR zI2Wbv0>ZjGV9ZCGs$`la%5HF)_Q$%tqN}gvw%hM-j+d9i2<`Xy-43vd?*Qg?3BaIn zPn3Zkq|Vi)Uo#nm`cU~#0KPnxi1G-i-(>2CK_&TvW8kV<50I>BMf6SLIHs`9HA8wED_B+TgUg1SnG*fX0qfD(>6$ z(g5gc2KDyKOJa!3RNjuE7n}C3(`{-LYiZPD;NIE-8MJJM; zNhI~sYvM-(VA_eURs!AOs2)ICqqIOj*XUwd4+!IkZEHxe(ad%4t#uDjrCtT;&j5N% z{i-?c{->6B^oN1fmz1T7A7cbYFRu!h#bH&my>G=H>cTisOr@LX`Gck*^lK4=bU477hV%a4*%+d%w2m7^tIk1Vp18 zJ-eSXOF)GKjaAp~@^@3|`Yr@U8J`KHSG=5D;j?W`Bnd+c^4V?y;A)6CraN}QZ-Snm z9~@p)9C_l}Q2N2XK?HTi*9XYj z1}`=Y=uDD*0LdoR8%x$`m=n;j3(#i(vh$Jx;IaPbOM@ayoegJhUA)s$Enzap&_RNgo z+>Gk{t4_NqAUy$r4Kr(Fw zPs!4L0^P;jUmfClbb3TbITU1PE{&t@ za()JKw3Nrqp677d|Hs{1hE>(I?Z0$LcXvujDjjRlASK-?B`LM&?rso4N-04pX{Adf z1W`H`A`J_W*8f=d{qA=^&p!6o{bhgUfXQ5QjWOmJ=k+_!i%u`>xO4?rgHx=fZuXm0 zKuLu#>-8Vm?V{%!K^ZFXS5IHKanA1p8w#SX)9--x4&2vc1QOLtCB-j0*>r)yyV3w3w$FOZ>88AhZ6+s?$>+BM+jiQmev^9x{L%p%CH;@N1bDiM;jH5j2zi zWG}_(0A#Vth3TEVJsz6IC_zFV;sj|3*}(yE#yzQ%a&GE>9ZdGG}E-GzX~csrqzJBK?rpKH_| z0NVb=*&SQCW?JNuZ^I^wWtM@jdtXQA^ckoW`4lI^IWnFji)7Yaz^EgkeN4YgF?6TX zlK34+;YXMKZCtw^@e;$ML}FzAe3MAMf7A0>aj>MePhnN8x&J3rZ1J%;80!Hc2#ntz zZCoRD)EOi~V1;>ViID5KX=Kyo%xE(gaj7|vzMwy4mo?2=wPNnmsuhrrz$2k0BR%a8tn~Txa^RU(ri5p-R%hbzd}lcV%h3D*sDpS@ z)H@xU0x6Kb#;Z!pwbeZ8B`Bn9RIXhhS?{gWfyd-hsj#xu0kU2%b2zAiHFbiu_lFp7 zI0_49sPNt`TuAEd2XSCFi!!1Skg(MVKpI8{(fumZXpNXK26&Y@@*U_M=5;IKx~`B ze4C;zw=D(UD~~IoF6+8G`koadjhJ95{VfBwN>!v0R!lGjCI$p6HHUgK{9)lhd>8Z6 z=4Edz<%;3Qi!)fTu0Pj%3~tS&A0)_lKo|QTRS_wfhB8CBo+!mar4OmI!hwaz5aNXM z(%N=g1|>80BLBh}6ydxyYamhaB#lB~ZmTo(v$Kl!>2%pX*e;+B0j0`y=c|xG3Zphq z{2hV~n)LDh%BvBpj~NJ3GUuFFAD}XlECtoQn+Uh~6r+jC&@Q%SXkQSHU9S@_(lW#r z>^Ns&l*090lQF>1Y zo@F~-oHK^{q;@uf+GaMO*cDiv&b@y?us|_^n+29`xAJJ?b?wf!4lE=f`UZSjh7h`Y zzj3*Wm@im{I)G<}G)%*!nyn^G6+a|DGu_4Z4XCo3J16ZLpkT*~XHmcVVI4)V5uDIF z{LA%IcmjTOcC%~+1Ob=M%C)!JT)z9#c`d;&E;P!u@*-Gtg<2aYruxL8!{Cj=|tQL!BKg?TC1{uPrhm z+DI^-ldD737cKAwSw&TidHoT<^GYqVcP_2bc&}!k76|l>)@qwtXi4s{(=_WqW*uI3 zVITg`L5x@mi3Z7oL4Z`oiXbRE-Gug8O0O+vQ~S5{z&u!v%Kkx z8P{>F^;%@ZtWF&>rL+}gfz1-ph62qDzHf44Sw{p(){8n!ZRdHTK>TFp2pCrBM)#0g za-rX5%A;KNxO|1yPlD<;<@XZ=R#?O$Fb_+y+~ zP{@6G|1Luo6Eb!~Xvmjn+e@O(i}7M_R>z`OkE%~W(?oRyBLdSVhgy+VZ`*FUa>=|F z4@=jVWe^#tW3Oh?o80;wI7f$SBuf=#Q;lb)R3P_Q+W1sA3IQeX@XHfY%)iXk$A5TX z97~uvG-Z~vzgBfESvskYu-(Y{3hb?CBcyj0KaG6`hlB;fh*;(_AIY{>>U6JzXx?wU z5yia}E$EdftbxFbl>iy4GaD`ZIn3j(>QN{ZZ}UV`NNHi`GC#93-C8$o%7Bu~eTe9I zDyY(-oOkAQxBuR5#TBLkX_Nnw*RTVjwDqvMo7l+X85}ojVj`ndvZzs%C`jbS<11)U zCQQF6jb{u+<3{1V0t<)Vqj8-P9WUdI$93xw*o^r(%^RClY3b}Op2vz{Hjrv3??%_W zAxr9_IIClg6O_lw$#?mq^uapXWhgpw8&zWb$+dH5`Xg29BVw(nqa@tHy_B5{Oup3+21XXO?pn+wJc^J($$l{l%u^>%7VryQ!U` z6xfWK4S6Z8XJy{0E-2>aZFVSaFQOI>| zUwa?1`107U5vj4)B_vSX;Z?{rm%(<#3K{3jxSWd0KMx!f0=M`-D~+N)i@>~zOGg*~ zJ+gba0&MZDwXt85FS(ws@gZ=jJ`jJ5;Z5n)-MpNschpho9_-dvR8t)<|0M(=ywqa# ziYkQ+euC2TM4=^eZJPuW6Bg0it>J90^xc%{HG1OmHJabpT-UAE*(%$xzt*B+wy$)n z-ppqB!0N8IbQt`kv75&I$!t}{PBdDkHV)eR;yGg7`Z$dD^0)?ku6-F@VXpfkHujkq z&V06-*YS_xFp=t4?$q{_$@&}vzF&lv4kyGosfm~0r7?S4)2Q;j@8%1%7cNa?n^aG+ z~lo8i;m#ZGH`h32s~o zPs_8orLN}^2$kL1s6s4P209S#@4O4CRXF*Z&6b9h2cP!X zc>fel*<4ttyX&v@82p87_-Qttk<2=N`f#rBHB}!o(&T!zPvg5GgUZE;bp{|2&-YJ^ z7VaGY7$J_i;+_YlZ$uZ=+WA5D>OU(eWyI~HHn(xZNB-Jir!J3i9#?CWz!ak&UF$}J z;gxm*W0y44M>o%FyXtG>qI8vSWUe;XPG&iLrfO6rEBr#mm-QuWO$@0n7A_X{(!NW2 zmA7JcGoN>9aUGunirq2W?=-n&B~tvu0W|O8bo9T#6nbIjsRI>5!~XMzRSXL{mdr!@ zr$O7gbgbz09RF~C4CPvQ5+Rjv03?(qoO#chu473wt&5*0RlpqQ>w3*saoJQ69LP@^ zW~f7~BZ)w)$5$qRGf&=`u@^EEoz^?Dx2FkwjF!bTUmXuZTT)IUCpdN+6Wepo@twa3Ba0^mI$= zhz^S+N~cNkB{7a+KUr*P(hJr8puw9lR%Yq@166w39Hr7Fg0J&k8L_Zpasjdn`hR2s=oDRfuyd$Zji_GY&AWuBPI9G%i8{PHmF<8;z&=!t3!%xZa`tYGnr~5m_Bo z)wvh^nU7XWKKJ7o`SYh-KDEW0^Ia6YS0Eu36EUt%0E*0#KUCm2?Pku<|Yzito_1yFFc>NF{qp5%wgvJpb z0#m*JODTUpq)6Hc^uQ&M5^(eo=th}79nXho9K}caNmS_90fuTRaSPbIPC!TvhaC4} zBl+FuU>G%-Ipi3eWi~E`{ka;p05J)Afc3hY<8K^cbqD&K@AC;Uqu>K%AQ}iKkR0yj zeDO^91K@u<0k!${F*r_m6)w7WP9Om$ccdNl9~$)|(xM3jqm;crAor>R907iSBV3pl z?Jg279r?o;w7(8iR;~{qzjAncIE9YOAs9TYB|s8y0ZvD@dXv)Z**a&TQ<=EMLK=X4 zmyxw%fyA=rum9k?y!CBmNW7*}6F72xL_P~bvzkkS5eeBZ9D_ly%J>z~9lpK<458No zKw(FaWqtQtlcyPWK;-a_qxX()j(F!bKn1@I$FT63R^qsiWJp<5*StV`zjnZ0k6nRn z<%(O^$&h>dRxYnv$p`d5u66HYk(kXgxSa#Q+fiKrX!*5eBT#rcTIMaycF~HPE|a1 zX=J?R1wgQeE@I=6@;9WTp!pT$Ynol2`OG)8#^I=2a0!w1$jcL1YrCQ3j8jcP9x+Z; zYps=AA+<%I#v<{5=B@c#)nRt+1AvA35=kG2n~Qwa6d7fY8~q9x5UwF20#W($33ZKC(^v0pXeA7N#=sZ+Yk;nx)cM%lf=;TI|bB*4CEh z=||^j$^_=pwq|&zyE<^}g__3Sih>9ia&I#@MW;AXL#VQ4OY#L0q93VMJqbm`ad}QF z)47que0dR3)(9Ust}$HA1wPk5l7%X9q-HA$iVMn?y$N4~VnqH}9L8}ypC*5zNpjWO z%Dw{>e5Q;^P&{IU<*=0rlp+&nGng*f zGQ(b;+Mo^iOF*_q=8Sl*j~wUI@hlFooY{U@}P6#pS2%>knF;xTA$1Yqu(2+ zag2dg%_(IE`HosI&J_i}K*KaaAt}S?+SjPn5;sMtj3Ds53*J>yrC2JV2GcQ?!BAioD6BaC);Y|kovAT%Gin0IZRpAh?5kb&)?Nk)K~BI&@NGH1 z<7A0QYX99OwOrMkl4sfUcEj50Wey0OmUXP`t~`9I0|v=vyrSfSvj$7wN*@c4vX>o}##gU1^4hjNZBJuT zRV2Y{IEkv`Zs9hmG6ouWP{6`tu{nKr08#pa<)@)aIgr#hp}FmY*ZRYG91nTl0k=sR zXg>#2EK2lt4M>wodO_$(_lc&YToSvaCx15jn8}^xIrr0);`I`5OPoW+XdZ#PvD$ z9h2As=Dcf3tS~`+^sQ&nJBH-jlk9M=E!KgdEWL@LR%de^JYFb@g^HuyHib#gT-s*V|9uqRqIBW4D(pl?J4LHp z$8(ajt{Cpu8=9H?CMT{H`pgm3P`_%;pHWvZu=X+?B=yQ(sfb6ndSC@N#Nwe=S6Dk| zag5N~zrj%+u-f49*ilmiBntWctXS3P?XySX!Mmf92mVv96iD&ZjWwN`u@}6Z(iJw8 zyRn&N@lg>jHC-C%A$@ktTHqzwU2)>lun6=pc8u_5@b>?BCPqJu6U6MEGbnq8D=i0k z5O5K1!J%#Yq2RWfXktB#1ytCLm2h@K202)^J7Z_SV_VGXD+Q> zUybvRH_7|ZOrduy$&o!dp&1>-<2@ijRyA25gwdfwOIk$)>@ul85(CbgmdA~orpk1V zS}{XOc7SvS_L}A;Cr|kwp>XyTYN(_i2h?Z33e7o6T5$vH=(4{*#^NBqZ+o0b9fd~u zO%BH3qPzehm?_n=9__f+L8bW&qA!}4zN>o1t|5lY(nX`VvzVL(vDmv~`D=7F=*Uo2 z8St6}XW6iZKx&xux#4U{zS@3YYFEV|`!cCgS@Dn=$Q=76Qg5Q{|De*+0DPMC@f@~P5 z=Pm5+IsOIt*7{niwD;I~nC>yZ?>*yhR=Y+|_QU>Zt-;V3FLSb#{&0lpi2fst(j53D zw^2rw-bSD4J+iHw%a1SZ$&BquNT4OtPgWzkLl04S#8j^Fw?LF>g$-|6H7-!2JE3## z4_kq(8&eDAvv`ed4a_sIwNGUVV=~J=Uq@{_1qsFZnf~cFen5njOY2M>&jph_jhz&R z4c`i}#jWi?GVNu3mbkI6-?+cFmyE}7h`=dRe8pK6nXWmG#u3j`&$o+WQ+E2mQPSxZ zmLrWbH?**Nq5m!`mNq&wAxU%`2_nStj9bl6)X&Rvw-H70$KL2Q?99~~k+rBdxPCFT zIBwe%GOUN9c)7l&L1!JK4a5Jh?=+XstNFEtq3RNEg2SY;c>YmnHT zkP8IkXo}?)@kNjvkO}8Jm6jVDWm3e6G}M>_Ss0<|w#PjVG&YpkNrSL9|12x+HAz(w z*p98p2%Y=x6o13j*Oj?X5xCJcfy56ubxR?SN7Sf$(0=p{*1Z-8UXB}3aKGwj&JTVc z^+4>ML1fL2Z_>v2sXFasBtj^HkiZBgToKV&b)x0ceP+Cpdx1MgG4ol9sCw{)UV_45 zzi>F$9cj`&`IGE<;z@PHhi0%&>3qb|=OXy#5u&G|JbVKVAQi>6XUyoU;i%{XkFD&L z{0;vQ(~i*d!gtzq3$w+aT0r@@c#Ubeb*glT5Xo9a(q3YutA$U~F|kOno?(5P@@#-) z8()=(sxBgfoLmUe9SUQt@KvQIg|cn*iOh4`%nI0Fby?#twFq;fY4R}pY0@%Zo5VIo zB{fnicQt%_#2>cQ>s+!sc8`NuP9LWKV579!k+xdB(+EL5zu~ToS&>4jo$nz1!PF+( zPkY5Nd)1y>!_+ieu}?K%+f(B!Q`Piu&!*>u<;Alx+I0rD#F_?gdD{gZ@E`F-lbmOI zL-}xt)MP;U+N=)-TLO5|bDaamI{mgg91;`nB;smj~_ zZ3eJG@;8uIfzIzj=9-i=#^0nftC`d|WxP;u_slxEQzD;+vvN$JZ;9wb;w{*o;$K)w z*o8-~K}>aGAaSFjhXDe_ z&&~H;1_Fh9S@tn24O3hb?r(Lw-e+sZoFob%x&GCgweYFPzUYAoN$BX_Gd$ z5vP;~IIFiPyka4r&W$A`O{5+1mpLy#4J4A>fJfpOR=;llK%=U=p@Z3E=z4nMX?w0e z4S$hX=dxv%sDzIRYHQhS`i!&s8y|ncy~^LG4qHM(+fjDvw&T$zilXwcN0_ZWg+#p7o6s7sO;oY;Q(R5BJPK$HV#fQM?kN+9VU4C%jS2 z5K)9C#i1u_R-PU%G%vAJs7Un;W_UC;u_Tn9uT+lDJ_=)oF<m8df0JW{}NCw;Y3XUUB>A zW5oRr>_bW7TqBm3!)R1kvWSRh)x2~uSX4CV_Lm>OPr=AKm8nrMQi5snsYSh-5JD$q zi3Ar8#9W5yF$(Yr9^(A01q^T0R)JXE*_6>HbaWLy*=@4+YDfsn2g}7* z!&|NxRlsR1`Mr|cx4*rr7u8mU5fsrWt;Dj=i>=}<7Fys05;{wLqS<+lny_<;nC+xn z&WF?&(pd@iK`eiB3{BOr{3enRo<+S@o9CZ!8gXcJ`jjPi$Iq#6qCIuCMau~y$($j{ zZI*M3&3od?%l)qT(F!0F92$Hdy{2`DvvD#yHX(=BE884O_w6A{_0INY6znf^PypHt zCnsEGh2?5H-&To+C8gO)-w;#{$&Vgfu=Bg|2Y;iti>x}5z0ph`$x*-*N(K=hQ4e1W}7<6@kb`&RTRs6_dyLgGoPD2LD*Q;e0 z+8!&n!0A@fst|SpXp?cNq_`;Dir>CnQq3&-L5NpJ)2$QdOGNl>S}FdFX?VU495Ux+ zla&v?I=*psL#F%=k~s0#8{qoyui2sh{h-cX&iLQ)89g}}HCJ)N_zY`9DQ8|*%R!w2 zAzE&svAIz!Q)@Wyst7Y9(Y`Rd8z!RsEvF(w-5@TgQt&RQ*aRu0Wmx~RdJpt6)szeYCfHi z!1C%FkI2Nq&Iqe~`SuY8&fUA?w7?)9Lq_PU5a#2Lzs`Q^8uC{DmzMb{AR5S% zC%VUFxmpuY2HOGP`cP~Ypq>^p_|$^T zvU2t#>6u+fG3#PR){Kh#WkVYk39eh6?Ee;`4)v)(HJeEA}gSENAETn-=f=sJmg0a7aHkFWw5LA2@&XF!9Y zsWZp0%)iQ26&Hr&w?FuQ_BjL!Viu|`aK%2ak~fLw{~WiPPB#NWWS`dq7{?uC>ZW8N8w(+mIMOaafFSB4 zV1w-hi4A(H+QA!t|BBz8eMP$TxnM{MGn10y2pRUkF*~}Kb%P&lPV^%R#R4ee5T9O$ z2u#ZOtiM1~KLp2Asxs7v+0c|dmSH3zD+SVdql+?fZ;=re7eLKxH?o8c0{+z^FyR?s zK6f+k>KN*`7y*7`U8FdU)r#zq(FqP@F+L}C9~NAAFTf*}ihoXm#GaRtFz&pr_6T)s z=M}(yeUXwk;GRFw+i8TfZ6gCgkS&^6sJsz>|B@+XM1}tWe~oyv{i)E~B5KR33M*5QIl(vJ37lv4nIU4y%l09u&TJ}7Ac-^40ivQlS^H3b6z_Kv~T8e9W44|ZJ42N5!@HbCEAdFe_ zzd>gj0tQKaeJvSm8iheSoln%!&_(ArFQbcMhsW-U0eK7mgMUf)>|I3qTAeF%JCfvy zG8c5J7UC|gQAh=g0JY50K0iA{WU>M`OCJc*cETlziH2%cNvRV>XZ4amN6Vk36UXBz zGeDz0{gUb1R0@0U;W;WiLRLdk!#ThhX`CGoxy`m#C_0x-fA~)M${Zl$8)i^Np&1L< zRu1Hn953~&AM=-xo8J`YNp>#Qwc>(8g`gh8k>;}4@)I=Wb6wd#t;;oaxz8e{iQkAn zgI>@d;I7#LswMBKvEzASx8=Pu(f^cyGLP1*&Io^)Cfe(lex?!xBurv1*~EVD6xCiA zTXgtLkH_R^F_I=N4125?h^@dl%|XAdZbnj4m4d1V70*D1Dx{BPhS)uoE5+OM@%ERO zmE90H z#))iPl%gpb!1Vdw>K--*XH^_zwgaDAmD?J>21wS=lU7nw87c*QY*vuLD?pp}MI!6F z-8w=+XTLH61@_heX3aZBi_RtRRoaeO`92gE_W-P^6dQf*rZnhs4oWQe1bwKZ;nE>s zgmDN(;kQz&JIhdS*$77{XcZstIv|cf?IkJc-gK3+&4PR9L9`Q)@I$;TZ`%Mi9uuqy z6 z#iKff$j(h0KP>_A&rX@2fVmZcVi&;6Tuco8LUIjRNw?#SY7W|c2*NVdR+qwl`RiPt z*jK&R{`L4*`}Ff?JO0eO%{2e+adt70Qb(1Uq_w=Cjw+8Bjdk0B$6V#rTNmZxL_rUKhc#V zwv0mdW8J0RtWZ45i4QfLA?E&-|E#Xc;D>FPUW0l{z_Cc3H_WS_5}iwDxZI%uRrsbSb(I}Eag6@6%I#D74042Bwk~^vMSM$%EHj{+%(z-2^MZ4pd{4#=@vUI%=ssy^adn(}8 z40%q7RBbMN5gB1dug%5t9%iPg(T2?%c@v6JZ>7r}j&9t?auFjJ%jWUbh$I+LP!ryX zr*W9RH*DM-?Goc^NRVT2)N9Cv7TB{y*+(h+vEp7kK)@4tiw0$vjO>hA7^R!wB{hBn zL!?x60&Dk;a*w5V8Qk#7B1=EN1vwR7!Cv{ftFtcyi6JNnQI}9*7YE6Lu_P%DMrvCv z3uZs*Am8C9_4O8=_hh-_HB|){a4V`*gX|IUePcly`BAYCRh9oR9j4eOlF)_+NxKQN z;TE0{x#?{-!M3ZZYTTXpR?tOMSu4_AXGQwp_=D7Crn6vQ@ixuF(Q$$xg`F2D>u5Wlgj_&B=jT}L}D)J7U~RnU8&w9_AxP&gzX zF+(x5;FVE7^Ya3!L>j-V5b#N*5VIvtIAZ^u9`uyv{j;_{uSux>r*LoY5DhwbiV}~@ zYzoD4+Zv4^3q5x%@k9K^1U#m59(wV46Gw(&rkzi8kE-fvxda5e;#O*ZQEt3~3mp`K zi(72q^u~)Dap(~%syfZ+TwU^@!D;m{St6(nUAWDxp>^De$3WWTxMyf6n_dKnJvEc7 zMwI$JQ`%w_^F3PG48I2>f@4DJEL#9Inu6M`Q@Xs4efDb}-Kl(wPyd*?;<^R9TY$!Y zOeTN7r8#Dc*<-8^<9@RsffWkQg_t=@k#)@c>$|6Vk&xo2%?6YZ$U~O4W`hxDC(U=W z`Nzb<@@7Q+RA*go|8NXWct~q=xRw-*TVTiGp z1*R%VM?Z-!L7jQtvQQ@ahF>p&d1FSC7ETxW?whIWC_Gl1@Wh-~teA-ma~F>#rfqHI zi!k|RuDMgLFOy6tC_*PL;G76J64Up5Ls9stfeLJ(i4vvU0~$4p)S3l8zxpb?VMgAJ z7cDDvM+(J-W@xu8Ctm(w5wTV?PO2 zL3(r;GNUmb*;Ex(nFWAyUu}(3I)&{Iok@hPQo>vmO5=6m(aYFckj>^5k)-qVvWG{J z41xBe0-qi_J^K;Z&CJc)XsxIPj)czePli_Mt;aeH`m}rlq5cV6 zif`kxIVpNvPTjuvN~`RCfpqCiJjmm6OHnhfvOG;@Dd%pdPGl}|?SiB4V*e7i>NxLxn{Mwb`P#N?#YRX4p7fxOV{g`qjYSCc zPH(GnV@-K|oD^P)_r6 zJo=kEh~kMVH_4z`@5aLg%GEV{1DJ5MEz)v^nJ3wlo=S{6asl=k3}j0@i3TSeb!}YF zDo29e6ns58zI!s#Jk+o&Ve6Wptt7!Q8+{Sur~Ew`NnKH+okxPRF`9Oyb_ellt|KvY z_G2@}Ct__Z)odCpyQSTAw3@D93G4`m=?qeW$3$xK1z!h==^c-4)^wpZ{dY9=wogAj zMJ4g7ppNqJ&Urti>LP1mW^2&jm5{_1HiCKx$zJrt?EcyRK?T?0Q_MZJaPe1bugn#e ze#~D(_~~qM5%v(S#0~ot6eS;w zV%Z09867?6qx8qcr9(b5oPtXT&4tW)FG7x-K&xpl-b4V`%5dGFli-PX%{t8{_{RLV1q z0f*|pdtXS_Ok?%MC~6vxzkT<{ZJOvb|7emk!?l`mo*( zX4NxmFNI&r307JRp)m5KIy<}g;yY0II~11stV2{1oHd{%V|pn%Ji4V>>V_J5R0v!W zNN-=arIw7x&Q0DpQHvlAdiDG<{Z*Z@-s7*Q6Uz{BUAC)O0W6^{JH!O8hO>LYe&D~% zSj08bcS|RSw-i|yIoWvpk@K_qliE$>S(tt`&o8Z&vot%wBe!Pnk%@BlsA-lCSXG~t z(cfu$IogOwTzEduZz*bML7J&FWxXoZol7^Y_930v4i3V()~^(E*mB zz1gfJlr&`Bs`TTm_;=V-UeX_nT^`|2t>$FE982*2yQRaA_?;9U(o=mWE5+OXpBm8t zEr8Dsu1`$X{}XI;`iNABK2Cm7|4(F2z7rW&*%=ya81V1s{5KqP;Q_$w7LS^mGXE2T zo2myK-9kN63B}5P&~C`vAesJsvtI`XC#wJD?wVbZpJ#8_G3LKAKJSnS-2d0Nyvcxu zEE3;<7EY$!mOzTh19-^Z67UlL*uD7Du@3h22OzpKsqU+{OYw|xc(oDPr|$$44>f;Hzu07!HQE;^|xB3p!ly-TB{J2;0*SI;2j_iS)JwSnpu z9P%Safku&KGKg#igjA;rwij;_!2bFl{Ob_VEAH=W!nxeu(z}Ck($i1MI}EO$cu96HF@eHDI<&W>pjUs-rb#rV#|tqGizUYwu^# zb1nY~v3b#UiV)I+m{93)r;@X<&8GW=bIEqexYou*)G0tGn*cZuqDvcaV}?QYbZ*TV zL4X%GJqSIxQ$C;GYegs5b?NXwLOuh@N8n)632tT?#Fw37o#pI^*j$Rj;(-MdI+`?1YEKsAhAO79?j%Scz?;P&`k0C?XoA+r~^g+R1d z2RfnntLS~**S%5Lk49bkaJhW`abpAVfMFh)494N?-nNeQXp}umJRXfb7SlPGA0W zcQfp380;$rBpHoDyEK_rwL&$nm-0*cb#HM(pmSeOIHR-&8MgVt`E>!t5#ay0hi-vx#a&JJ@(^4P4s7FrGKy^2}H!;no6FMF=G75TpDjm=Gbu75lwu975j&sS`DPUP1dH(qE)EKt2###?> zK^ulRs)7Vgfjy+lRy+;#_FMtIkv&dAHSVZ|?c;%zc2JnJ3_9boY#AVsDYKn`9TnxB zgbxA|=jG;0I?(-i(Kd;H<116hS%w*i0^Ix)R8#%h8$fhv(ECP6pXD-ehwmbt>N|g( z_R^#g@kOuiqK|r!+9a}JZa~?W0oG@e$!y6~Ihv#aAI=%i+&~gfX%~@cPu-s^FDIa! zW!X!Y4^o=(2~c70eB}bPr;42R$M-y7UyaLV2 zGSek-7>9%;WtUQsXwKeG+;MP3*_H)o&r4~Hyi=yo%hE-lx5cRLhCfK~{oGhBvz`Q>kU68egU!}O|X1%Xrd$@&|E+b!aq?8 zy^AoH14DR*1dyG3klk}r{(Yyn}GLgeagX{fc&Z=asPB7SNr zfJ|7UlVIT;*pDXpz!IM#LYr~p$&3+8-@`7~;~WqOAR1~Qz^Pm{esd-0=%D9%m-lKB z4El}MVKIEx*&Sq@E0R=|`k8OHRNz>Af4y6(w;kVKY?R&Mn?MDJG^%tNqPF6;3C2D!*&KOO3u%b=LA#*SxD*+zA;)v-I zsk0V)LT)6lxvmw);^LsA!N#eAatDiFTQ$|sm$9XiJNAS)P0xDacR-XM8kW#rO%!T3 z(1j3wmphLO_jvaI9&2m15R9JY4#41%Nhh{dC*HA@N5>;Xp&3Tj!VR4O1wPhR=^-1} z+?1Mi0)>X;$s4T)h#FJ46siQW7o-XRkRvgGAUtw zI=>|j9T6F623aB6l4U@ZHV!qqCW3td zAbCL^ERqDY!F&4n%af;L^|?#)o0cz=y1c78Prh}Umjk4jbEV-du4GQdk|X}XX`&|_ zyK;m`nuNL*rpI_iXyHHZF4LaWg&@5mloESuRL|Owtz2yWx_H}~mU5+%?uyW~zEtKo z*qO;Cv<#4);;esJl{+g!UjG1CNEvwTb-~Hq28d=jhQ|&rQLV<{TsWDcZZP*Bd7)t82fF_L2(R&ptXvm@HiIc7wge@+=v3fCeCtn& ziV-q=iETAcc)}A!t4+1!wXM0X%)NlTTWf}HAoU|wf-uDqQ9f$4ez8PMjIbE4o(HhZ z3uMs(h9HGS3d~>jK17f$XYTDpNf#ugAxkqP4&|%p4-n@dm-Y^T(?dILsXZgLnHgNB zCtjfeV%qP-0er|R=OrL9oNDx&RjxWUEl7zMfx(BUzaG)<*xW4MS1Dc^ytzFd;Bx=F zrfHQ3(_@)TyeRf20-|&3XQ=p->tmR9q z+*G7({IDJkc}(P2fj&OvWJLc)z@!x{e0j+qZ6vR05gVIU1JPtqop23vnJl;{*bIEUV4y2E#RTAu~c9Z zyPJUL25K^2)Mw!0yKK2sS+DDVb5c=Be>#UWV#%?MX`E&qlUt#u{DIo8T5{XG*H;dLJXxN$8us<8 zit8$OFMa(!ElP7w1>LfCEdK)#oxEllbRedCafhMO2$9$*;$qrRkWZ+T!`UR(oz}S)(s_If-Z^)N7-X4=- zpA@rqQz)G}CHX{~oE!=Z*ql)`-yf1oCT7|g1_-N?b9q&drG945P!jJ3rUekKYiP-~ zuzsiASZOd$Moft_)~IbOztIy_*0E^w`C_76*mXL($819^EjbBnme25ezvK)g#9r7C zTNB$);S*4ip?egso3bzrFkDD@$+-;3km#W}TMNY);o7fFpTf)<{3Icmo=i_3F6|C% zwZu-hlP=c$G_XimpSx54APqe(WqTunXu4BxBDS4vu=@CUFCRsrCjJqxOLX*Ft1Rdn zs`sGRLb;C4xMI+?(h^RT>7iPKqr@`w$hi&9@*tfMpNfVBQ_XHl4_#x#$h4puParHg z!U$Uvf)2K;*a^Nd`GFKlShx(Ds%dyR>1bF=wyoSi1c2dR@CwNEDGNeqsI#>|r(SV^ z{L{AI`N1Tu2+;maoZ}U|R@tH(vC*Z@7l+eOnzGqv06{B2XIh#}muk>Vz@wEGGA~RQ zTM-e9XAJA|pQEjJ!r_iO1RI_QWXy;%cRt}rV<@wb;6^uR5&DJraKGb&gg<}fir#$Y z`||162f+~rL$|+!otQt<{m0(^G_dIja-g4nuHpBwY0reUtR_vj_Lo$~idugKrZR&SM)B?ewJ zPJe7N&>Ig@VqDX@L;vw{sRWA2a4&%{m})xHC;;-mQ}(D+D!FSdl_xaF3uJ4 zbFvypHWZtvo5+PJ>OK#?gN|7C>B=2Dy6`~6cipFvK2<)lO34uk5vf{{d5oFk!pj6CYmuHs!i1GD`5lMDn}bBB;u*5$nt!tM1f&0wKwU;W}rDoL={urRL^ZwGCq^% z%i3E-(v2ZmdypK!y3;SK-bLEAot^ZMkS4}c2qzAmHwybCqN3lJ9*W;Q^vN3^lMt#< z2rOIbSajE9Vps|srSx{kj#C>2zoZ7%DuvSVEe9G(Q+Y^~GT^YX?AnvmQrpsp5kVTX zE==e`>gBQ^^?>+eysrP@#B==ddIuCaRe~fMAywY@$$SB*cm}>=A zapk*`%>eQ0X&>n)l>O@wQ~rt1&&0A5M#(}%kA&_qC;GI9#_y@6siL-@my&riM4Kc$$d^13ENOE!Vi|L08|=Ood>w9AQTH!R-c5RT z?<%8gb)Kec(7v=%rKPFx5@AmvjG=l=6&k(017di3X%XR(7}c8JxVkuRC+bM@xJ2B| zEzh*_){sQb>gaLn=_?mdcfH9o5I$zjB1Li?$EN}ZlWi;<;-0y~Ip#ipr@8h>KP zY+o}1!I&|>!?#Ws1SK>5N~|ARnPwAFgoT)d_&=K$J#A1X#ShH#HDmR?tWm5TJPP{~ z%SOf)D-_0b*M1urC`dDZBETUSwHLIQ@J3&32 zyqI&!8$v(=)h%pWVCCiH{!R&y*NT|lC=Y*{CoFzNuwlfP3Tr?}>-~|+E`Y+gwET0)cn>3HrBX~A0|+ldTuU6N5hV_K<|IbrLQo0qX#JXo?_NR7>9 zHAnbxZSXXtLAj=IE~OCV6u}4bKKq^Kp6(IUVBOjs217Zb`+ZL;PuOTgN3X3c3ZV%@ z!camlLKCwXy+-Yw-phD_;1(Dc!JDQL)73)$!lT2)KmCF~iI)m4vhDMSKvx*gb`so| zPaf9UfeK@OiqA1C8|CE6nn+;74?Gu7$KAHe`)Fm27B)wy0XV%k z&00*V0{MNYt+JVBZ*=785AGjeA>fp`e6Y%gtOSbpf7uT*Y7O5feaR+e{&_J-kU8*z z=o`Ukx8))Hg;G#ZK?UOn1E-70gi{a}mEYmece3dN0uhf>g#*ElZ4%TkpMM(qiM~_} z$fwvzFej=7d}jP96V#CrgV};{h)ji%&ECqdt5R3K<6|BF6%8&S@pS`Qumk5a#WDpo9;k>X`y@GHHg+7l_ZUSGw7z9D;d-zu8d50vb z^ugL;8ssygw_WjoP{A<<)9~q|ALeB?k&?4ayFgj*KzB{ zaL>;{!IpU&0`rqw5m0xZY!|P{c`C9v=XYN?b7wNhJ7M-G*r~|M%bI~We3KmtU|z0n zHYGc9J2?Mw;2L#s2f3;5P=HeJaAzKVB_RhH8K0(&WH=eXu_fGuM{CaqBE|<|!4LN% z8etzI$bAu&ICZrbI@K}gFjPk``6oX5=ALp*2~s zT$f*)spg%&mOuL|zOce_|Lfhlzt`57lMz+LiazD5I=+aexJFom?z+* z`Iblb7-~^OQnc*Ve+2pV!w0rgBsvDc80Nd+B7`xqiIf^%BEp4cP$GYGDTH;DY(i`U zI-|EwJFSBZlZ<1v%-`hI&~b*3dAfNAJkHoTGaK6dV18ftC0e-m?4X292(JIY`1@5F zaC?f2B*6Y2g7EBv&NFlv#ka9sCN5_x$BcZC?|CrX`Vo>bS8}vgQwgb_kOT;hz&OEG0xXGV^=sibevixT?D=~&NQj;6=Y76Xxg2x> z`%n1OhS!5wD`B4LM?XJ`RA}}`3Rf}~hVO}H65B$yQMppwmi8^Hx=$%g$$LenH5;yd zZ6ixB=2#%R8e1-j&6Aa$-!BNKH%8XjvHaTTnS*c!eFitit_u@J4sOz@C+KWu_^3?Mco7?fq|IiWoWl#I4HK=j6) z;apB|_>`opC6Pp{eNpN;5yLH&nyzQq(NIV|pYo04ba(&DyCHIYVQ}Go+w}?M>|cKJ4QA@`eY9BY<`Y(6=0Vm@_~tv**ab6=l$!^C=j2zQS;7T!H_)Jqw0 z_;VR$ISa{dsr$D@E*N%>2+}CE)wP!`$yG?GAbvYnas*erQ$!rR)6+}0)(#Rk$bmJX z)wPqk9`Y`>j-|B~8M@W=BB~zH{`__wj31FhS!RxS^rqi*fK@TrKy)gFakB3!*5or z2?tkMW$nzxtj zd2a>np(2&i0#{*~{med!Q-yTZ`svL{ABAJm1%q5K#tz7PJn!IJciaPHi7DR*%c6c< zn2(Z7r=0gUto0VZ%_xOoQNQzhM# zE2sK{|L0G%EPUAGv_&K?YHoT^%yM}Up#hS-S-Q1c6lD&2l6;LQIrjlRAX*H)C@SSk zU99iCq%RZ;vm+BBX?=aff6S9+KKmkIFXAu5=0!DgO3pUca9Krd{E~K76 zva#AK%el&ENJfoDhr(@^sYX8m2Meu?2d1#yCuKB{w?#KD)judLmNjBW8@fgxKK+vT zWS@QMASo<-VD*BPa*zVUrt21-zIdgAWY+`2>v+q3K3%Ajc9PL9py{e_fMpUd71d3n z@}O+PR-(lY{EF|Hv5)he8wxGVH0TkL8o0re0CtVl({!Vt+S)iDqW+snW*M4Ns)EV2 zTqxnBJ7FO67zJ%*5D`TxJGGdq%v0@AeQmM+k1qK<`%Kg&^4@r_ujke;<`W->0`5#T zI+rC>DqT*tdQdVqlPHo7^Z6Hzt2GqGLW>mTRuX$FvFg<(V<7zgU#3S$FI`CQGz3EY zgp{e&XikaL!3*7*xod6=Q3hjTGIT1;{OU@lVBlnn5j}nVjC_66|0SO}Dli@S(uIW461J=#IrUj5GAWLRU*i}FGz9+9 zbpP|+ks8QK%=1bsjRGm?!y3$#{VccO%+A)HD589de37FjXZFemU0+&Ii$K{%T}zl$8B$&GP?*SBy{Q zgtf*ek{S>5DmDp>l-HbBNRof35B=|VLqWK_l(#yCh{elUrx(ui0z*`cJUcKJre|CY970jd?= zt0?}t;SqH()*5XRYTXWXR%tjN)>fk$AEbEt8R+bI;YRto1jW-rh&2aUE!N89WLv$8 zp7!g)!6*~Wqq@ugTQdBjgtZ2T`WmmZ;gW(79S+IIE}coIo)V(TjM`~YB>AYdcEK5n zud54%;uC*mF@ZJcu5o*Bzm?(wz2R^Dzj}3TByp|%yqU(uP*MF>k>d?|(${v(%jYQ5 zgTR_mGouI-hXWi;o+na`n@#I_pPkft^Pi}2?Oloyvu0F-S~vDbF<+}z$P#UTj=jT! z{yWCKvcROQLe(2=(bwy~vC3j2w~5A&-4u>1v`GGbJRyE!awaYar}(j1Oz(NDQ!lX4 zrFnI-U2i`G3D=oTVR`?wiAkwkUx`YkqYzOVpjj$yoXV^8v)KXQqW!;FtnGqCtZp@) z`@Ym^m1CvbrQBSpgOrTcBd_5QJ5y+MhjIYBIeDAL=GEOZSBI(H@%v&&%(?w zbhdYl6beTplNY0PzF>cy;eQG-a773VO()Lwqn953 zZ-CxcdwMjGcQ9U!Pn``c{vF0oj$f;iFPK$}RiLLGbN)>T3gLGEvJl9Ihhu7OsvpQ)n=u2?_4lJhMY@*Si{M_T_grg3z@ zB+Q76Pyh3f`2l&KdwHD;9`T+=Xw$ASmP$ud zm1%=)sfDQ_^3W_#1E*T%bmOJvL)}Uk2mjuv0BHIz7nrK8Iwd}=ucYYYtIE8!cH-HX z?UzX_Fe(-^vO8Zs!Uh=gB2X$Mzi_O%Z+v6<5{q8S2DCL~VT51XUnP;T>0K@`g1kE) z#~9emhk{Br9ZYXKjc?&KvzaZF%VDTR!o zuCPD7VPDqL=(Py5+N>isT)X*npitKU_jYUndA`0ic(WO1x)Xb_act3Id)EO247d|| z`LWJ{Dx38>MSM%5SNdQ94wy%24$ojZ99-MDUXFVBzJix}vEgtZhKj_iGd@5Gr(?DJarh;#BMu zhdP-4QKL+wVr{Co{EyE7wB*yGM+dBT&nH6#n7(;%$^9n>BXi zEX}pBB34X;qoR+l$Jg9X%A^UklGf&XoTNHix4tfU8%uN=Q-xJ zjYA=E9tYBIU6~lWJ?0sYol3o+B2Zt7N?TC}@9A1Q8a4z^XaBPosjGOYYmQN=AqAmoAXX;{CQd-a&J&(H_km0Otft*=AEa z8rWT&v66_|DT8&`YHKpmAmnvqgoym(HFaVGUG5)VIY@2pozc zl9O2&g%Me>E;)^c5KbG@%N-IB3cprpHaBZ8+;PBVveQI_wFh!MLzo|z3a1>Msdj`? z_tz-##d^*M0cc!kt!ks9)^f8c(a^&ih&C_bx!=BhR4MSQXO1ayFXVKl0NNH{(Fqag zA^k3k6a~$S7#cq;i>!3+GsCJ;%i<9uN`YOLv+Eq59dSNiT)jDnP-vIdIw|hLq8~q_ zF%u1ztME!4mMZS9HRJG$1okG;=}xxMgihj6V6#@mX7!7jlk!m5?@Fo8n;J$%<#16P zw!R6v^^&Q8LM9$Z&m8Csl3Jn5x2o1^HB}nXP8U~=XTZ?uhrp=6Ygwv{I7FPbw)u+2 z*yDVuEo)B$7OYmZhBcXWGGx_Kt7b?!7t5_FJq#KZNypqF;SDv*jC?ShEZk1|ZO9YG z!W~1`)ZaNSiGHdoZFf_e^gj%}(K=n)I&6V%hg*zHKDvIC>@1bbqUK73WjcBBk+eWa zHksIj_bfz36Q=t7dvIjiWo+6@Wc6`!mBphI*X2WMg7o1hru*URnu2k92Gi*nt#Z#|{Q zmTG1c(Wt{EzHJ87NYR{G*HRbxq&iyJ-ENi5N9pm6`m)$qT&{LT_#_x;PL)&(8p&D* zdQz@Y&D}mToNyeYHU;sC%{IT*37;rRj~cUOv>60fyj`%j+%r48Je0AG8PwaH;5HvF z{(`uSH^ns?Evh$8cz@O#Pte)?lJBz8G1oFhSZEe4S2LWiAEkqHSEW^2DT1ol9%y8( zT3>JCS=P5%-ZRv73Cvm@pSh$`hdigN(Wv%s{^>$DOWL!lGlZhBn!X|DrscEHTC!`2 zzK5<|l@-FzztuPsRQP~dGsuD$x7ZRZ#)~f^d~ghJ=3ah8qp(6?iGJ#yI|Lz{5?o=@ zA&WPCchmYN8ds&!?XNv^r{R1;x3D;cTrYREy?e!2Gs2eljn^KXl)Tl|dk^y9sby$) z(K_T-E)-ierG2;Wv=0(A^~zrADo&{>6ic2Nn5gDqp@w-j)X=iJ?g(b zBbmNDh#W6FlWG#9-;IHqhuFD~!VF=Dnmsi*g$B@UzAgbuen+ZSThnJV$Lv+HGE5qy z#@yTK>>a}=)iUG1e)CGjT=o0>C+eL9&E29d0%oQ+&F5{&o| z%~T2^EiDned=*HtH%c|SySY?l!pRa#Fp@5;uC49!J0FMF=vXt|HVantN*^W?DG7-> zTZ+Zf$-7xw;E1eDfVbm^KtAvu?`t0I62Wa{+0mJAm@>i&wr=iM4tJ`mf%}+6DfB9X z&NeGWh*bX4jzn@#e#SBT%O$?301m%iGtPFbc5R?uCI>*IT z=T!&mT>bG=gbUxwZt6(jK7=NU{!M80dvRR7sKz~77G4ihE>;wRD*&=hb~tT+w)plm zqTllLTas#+8F{oR9D-(_`z!B>6i30+L^-GHtR;9klMy4kSWOSEAfp?q#es+BM)7 zXXcsnqZlEbgCE}3GX|0EIGo~ct=fj37Bm?Su_1GmUW>piM1c3{=o$jSEp}3mW2P(D z4gFkqRcRv;b`kM2(;QO*P zC0T5j{lxt+_jQ&5l3H|?(8g0-$}NQDkZw$+pu8%ZY3J&xrd(gw|Fb75buPNO9Xg8V zKAPff{K95Ob`?pHH7e4J({*G_Py%>BgS3!+%7o6qLRg;7=2$R4c_tY6l6IqoY*0|b z#{qwDnewI;IwFr3A9~@jpF_TH9t`<@`QrJ1n^i8u6+@e5euZ3=GkH|5$-W@;Y04!l zju_ST4X%0rxFqes_pN^0;jDz=aypWPgt_TX8{CjknHCmC?E`l=`PxMusxw!lBYfob zt8qW>lW(>%FJWNo1k`W-HZrgeY~JyGB1u17oEHKxwj$n)W+TgtFeUnbz^EXLOef02 z`*6L|E_Ez1a{gKDM^YgBGR;f)(7I)=MFY;~c%W`xw1Yw<2?>$+v63@>d>!|(l{l|3 zPuA@#ytQMoqxYru)6EYx(q$J6yBrpY%$c*F}MwbB2C&- z%7M7H1S&4o>g*mWWwi(WjRPlzNm$TOAw*@fMO22pL~V96_SZHLNv1$j{eaYZ;HO4Z zA^^!S&jz>h3HSFfR-!vb)RxKCD^;l&7 zYb1NtM@mJBBw3`~P!X_y%Q}!cyw1e3x5S5G%`r=Z*sS_*+y~$=S!b6PZ|M4mTb9;2 zDIsr8Qp<8}9NFd zlu?$_`@kicf~a%syYeE?>mn$YDN%wMgUTaUI8)3V zaY(t5nkz{o5*BGKebrJ+7l30ZLy2`u-hi~mx3RKZ097?QK#nTzW05-d0Ykb`{*Ijl zUW603|0EiXHi2g(BCF;Ev;bl4c%8-PWb9`{C;UUB3BDTE?X%q*TlM_>3nEw^SE4gz zgHvTKRR@Os5JuuIMiAn3uTf=llP9$0&yfD_+JZowW#ls$B23JzJaXr!8ieizxL-MQ zt@j`gKBCI}1c?*{Vbr@}&t-#iCNU@xLI&gviHX6n1gcMQeiAStTuo$Nli(_LW*c>N zy2jt&ndZI53F!uyJ+EC8trAdvFXDV+>N87|5H?sTd9a_HyWieHDAG*ltam!;D@FXo zsb1nh^)XE4d;ddWy-eE2ax}@s+nqTbvD*Q4-YZZvQlG%{W^?mk{M)(Dtb_@>oG!!k zCLV8dLvuP$ERlp2MZ^*YoP_w`TDQC75A_mBBhLA?mH4VqpVrx6-Jr9*B)WyxU(ny3 z`XyWCK11cU+chesE65Ut^3MM*S;~=HofA8Dsg9fwY0D`*st`mb+;)SM7fo-=t$v7u zKjgtV6r`~+&Q3$qh5Oz(Wagq40LN&Q{6$&g`<@w$b}p1l5V_lBMk!5EWO5{D(A|ft z2%ekky^Rg2siDyJr)ai6kz>8x7@yqzK2*46EnL~SYi`$F_;jAHR5`fkinX|_{T294 zluCoMH0B3qGK>Ne4Grd67dHb}jzA-X{+JTVp@)BX9+sf7MDE(nnE<~_ULgsxRu)J8 z^)R8u+usH{Xtk5OO3WNU3xR8KPpbsVg!|*I%-^of-S3envYJ};LtbXjTnhYvd z*D3(*-eWEf$b6@mE;JSKuN9zjnV%9vCYEabe52Xp;HWa{1F5%c;OaH(D>h*w55HcHHW=D0P7e4c@k+2ka>{Urza{eV<_1Kam?7%jE63l4jsZK>&E>@EGZ9loL4cKHo$!5}}O zK54R>uwJ-CY)^a`{DS|%o%CnT=0FGdll*o>DHWPj5c?2GiAy=g9NosRqMs*_;aVjF zoALgs95?#~@lywm>T<7ZPX-I=w#)UutFpuT+(CQfWgwPr&x~iolM4G9OIQnH4%b+& zH6|g7AR0zxap;cVH8m;?38NnA2W9pA{blc5XU2de$E<45SbK%RHt(JCrR$2on~L_r zA;79~KvB#Bb=(}BF6PfUt~vj_I>@z^cW5BU5~;Qp>eMj!@Ez(SH1?@sN?N-EzABhT zarOF53~Iwm#8C7jX)`;-9GpmCPi@!r(+OR7YB_P9PxWo~`o-R2=d=zx26VCP(UuCER@N+k!`UL0h?tnYHHq?o_4)BN{T zrRm5rDC5L!vPk;|BN&(Tp{fT`HV5wC$nT-LAA$Nyd8@3bxL-H_8r;&!p$egL%_1vz zAKm%>rc}vE8>0Sv5j_s3TN4D!Mu-w{pIub`;jUYAPCo@9B70D_-6+Ik1gp3^CZWif zNI9|mM4N_WfF{Qu>E_E<>IJ&w3(mZunx=ypq5ZL>Fx}=z!`69@p}yBjH^ixDE>!OH zUcXBjD_eGHzoS5{#WfjSin&U?BM7aFOS#6_=1;1XJy7!)&LFD?W2{dB4j8OClw`y* zvo}`WI$QH4YYKEduqjia#wC&moQ<#aC&!~Uq0+yyH9jaEml5c@z-xl zApOxfkE=e5(y3nvJQWj4$f^AdF|!$iSr8^WgH9z%-bbUvETk`n2swqb5%2YVYLFJa z1JB593*HD~`s%cH*ibI|adK<>**!2S7z!Rb?roPKm+Tp8DT*Zw4VO7&c~L%9-Q%dn zEIHJ$5;W=<;(^AhtRp@e@vFTHXHWB@dYCaRq=#&yYY-W`CwFP~d61d&!OcBBB@S14 zs5bcGJKq308g-7qVt*lzZbsIv`+}?N0eg%TCpr2z4AQ<)Jz}KrT{k!Vt(j211E)@b z`7Hx%F8T8V!@8R%rH3f%l`NsPN6hOw_jBpswKW{mA1F1QJN=wF9GH@>mCF;ojJlZI zAEQ&r>&kd}S=Q~rb7&kz*#~dqZr$9;mRlOu&BLorpJ4Dl*-;B7V`N=ad~ZEw{>c;) zHo5ZX80xgey=oHD8$;md5d3LN1%x|Fo$Y8@UM~c}X-`cky|=n59jQ6wkwEMuk)ys% zIsogkbuaI$T8gEnh(?{#nJ2WCBeHH-6R+3JHXl6yaN%dvEJ$wSUA~FhQGNju-gMh_ zV@KqTH}gZH_ZC>%>-rKje=NOSqUT-$NH$ynA66qcV6Q)dnD$etm_x$0On!z9GBSg? zpngo^@oDjzozHb&{r#-S^VVXn2kGl>J+AwgKAz|4D4Nr~G_zewYd<4G#VNZD)20t1 zLIM6aXLvnL>r)f$$yiDRL+_QUyw&CyNBhpqUU`s7XctL4+t(x0QRWofRSnTa_zUkZ zP}|wT$-9}%p9Y2vH}xvVA1bpmi44O^dt|nX0H63({yzhXrOtSRekc-1qSDqbeT2N^toChzF<8O;&gN zh_&b)EMWgts0kVn85X=u=0cPIf1b)Z;D8F!A+53!{eRj!pyX-1OHY-LwbTD6{sPJ$ z2&fNsN-eYKQ21}F@A5Yj4A4Zn3cf1V|97hu<<R?frc^DA%er1x=cqGu=4fCeF@y~AG@ zU!J4GPBsb3aoinFH102^RqQrGDpRO#b*j+Ql|59}kwlZSmUg^CpV=v)1m$1e=q=CF z5y#>z4S0K-{gHk!nk91IN-LhO7d6iv@aARbkB!#dX|_zJr;9F6O1io$rFEuCvU_5+ zMdJ9Aj^wc7uQA;v@KEYVPNPnY-ovIaf5a1XGRnRHg>U*aUsDY7laMlW?KrElOi3Az zwV{fA`zFPU-JmXeq}XqOmzh@Y|0Ya3ye-BSKcpgMzJkp0I>%VAzY9)TeWTLy9qM4E zGXZCzyB(Ddb;oX3EU`$UNzp+!cDYW2>}Ap$?`;f2qn#{6yxUIDF?6Lr;z}%ndC0jf z*3qSgHdzXy1{`t&fV9!?WxM7mmn%~qG&yYlNupHRIc}Ir0o-QAEf&^qbRAw%lk968aZLxuGdN+M*kdqjKxV`mV$F$E$GN zIZtoX`%i7fay$o1r2!kX+t*njzAT#D?5<4I>E>@P>lO>IeJ4HA7eto_OV+C#V%_YT zbjKQ6x7H~-3)J)02_-)1v>S5TR9C8%smqV!H@~+{U2AsNKgUN7E~!_Xk*t$FjyUJaCP!Pz1u0LB9lsv#EapjPa4x!5!Olp5QJ}o7NJf|eO*AMb&*KqS0@6v`(}0cjh_#`5*Z;P zaJC0(eHlpl7RLe0^i<^%;h0*pfZh(I?8U~MXI@CHg3{ofF8f#Lt1U?)hXABjEjJR|IFJ_`DM>Yx=Mp zeK}s^7!>2S>a0`bbkQft+T8kW?^IW+P++#KdR*`5K@N9CdDPJljj}w6@@qE3WXqaG za`^F!*^Zz_HSTp;c3{1!IeD-*qf6cM#hrtgddy|xEO1SpV&@$+JOz|j{v!atVhY*@7lM*f6 zD}H>2IUZMYXct7Q?tHXcv8xe-2gQDc|>hI!_jR4jt> zCr{-S3&k!gCr^yRpu~^AzP_+|-AalHm-TevN#W2GyJ24+@kG>3;S193oOYlc;LeC*r z^XXckZ#s#dZe~7hr;8z|^NryhZj{i3w+)nd9G`x*-Ph8CDErwZWYcwVjF0R=AJ=`R zM7;X6qm2v3cpezleX-z$$?TfU@I%5xioR^tWW6AT0Z*+aLI+b&Hy4z?px_&n8P9ng@PfaaN!0n8nUygsE zPj*$h&w!o9G}2xx@iAh%ixC*#Sa4lP_FQm$m~NJJ_s+uBXO7eDaH)#IWEKT@;W;C1 zn{czQ;BZ(YKz$(zU|9r%UvDj>pDL`MN|@jJ)pRn8^5$?Zkw~N-N}Q_c6)5KhVcT{R z0#3Bns0W2gQ4^N)l^XR1{otcxW0Gk%&ktAG70fwXiRXpC`~jHiFP#GGmFB#zE#0U( zTr=f>U#YUrpwWY6f1B9s^&%7DvJUq*@cISA{@tC0;W7MF=W#|Zug;p(tN3%ud6lW*wLIAEA()tac)P}ig8f}avQ-3L{|2`OT zO7B3>Sm*WNuqW~3a}3Lym1;#w6~$oj#m0vF9&Q_8?)9Q}Cy^-#7c`EaDI85xc9`5V zRSMhebMU)1fLM(lE`xgESc#qr>Lx^O^92cp=!wvWG%ZdyZs}%)cf1GLzN-1(~q3^!W zekaOq>m_5YdWrLq%0P* zc7YA7*2^QSZH~m|b}vG*ZK740O*;UBH5wbZf&SjC=lgHCeN0{1&qiP(V;D- z04nmKE{)Zd>sC1V*n4&Vfm1l+JJYAg$2+=TyJ4u!26#M?0Ka~7j|u^xAig_54j~$R z1m4}a0z8lV1;kI!q8%Y6^KLN{Pxma5z3(dLgw1^>AQfLcn5MqzBq=1pwp7cvLWZpG`%-vhYcwrw}~ zcO&k*RelT1@plYrINjbY;ObZ;YYk1lTnXmq_J;$s0EI!$w1wvFx#w8gu54JPw}8c@ zlbd@cX!C*&J`uk*`(?dM*JYJ#4|gLkV@p}pqk{ScI(qZVwz73QZ$;doO`iI%MMrZk z+~%SDA-sN4g!JtEi_P`k&4{ie&Y~+96~)A*4XK6=G{h4((PP@rGF!cj--*4kw@?;b zZLkh0KS$IaLbVz4yV{Hs5Ue|!x3nG_9#QHpE8ik*p>%JMVxeRJp0NTP)fM)KFON5l zf#q)Ip0~%8VF(!Zlib8X-O`z?GHwg+9yQf(KM*z_41Wbz0Oqa~BalW`pQOxP-qy+>3RLF9D9?K$0NqMqw0hr5y zEa}h*Ky^YF{rU2A=SoliUAFD3eTj6$GQg9;m4MTuUUJ!k2o;7$31qn*lZ`*C!*Ed{7y-iBL2qqftL0ON|Q| z)oj&y5dJMSm=^WNa3{?zz>|*+?wO0)K2OQ}xRea*tbH{8$AX-B{5g{?oW>96q#>sA zc37l7QmIN?n?-Y5u+NN_`Tcs1dh~aruHRSF!bD1>D)H#d&K!2!h_=)HFgyx`XjLoI z_$9p;A*Vi{IsvA^?{H?~5-TBjpxl=B-9^vSCalW`czGKE{Ix%JnnS`(AQiaI?aZE{ z-1h42rN?Nk{AF%yGM95fUf8c;Tx8>hiO7V_w#O^_nKTMy5N26_U--rm$-Ei!_Fnt3 zL0_<@(i3U*u;W@U3DKR7IU3W2^H{a9BXRjJY1Uo%h1&kCK?$y!6Ir_7{TU%7V|#J3 ze;RS^@n4QO#16s@gYiD7Vys(Fi@O_>2w!QCOP$`t@o+kWYE+RY?ZgcNQ}o?=cPzMn;Oh40k0c9_BxqzujYBlo1z9wGvs~c zaZrrF4kL9#h2#<-1&*$TS0qNp#!&fSQz_|$^78*YRG3%n54-^~do?llAHUDjvlDzqpiWMrb)|%9V}xbWXX+^w2An zf@rSX(ssL;%5KJ`J8DnxM1el>30&8B&wdVbVH+NMKp+tz+z7>kzEYkt zlIy5Z9{TQ_OtyIN)gd*t+5lGKecCsX@huIgK7Q4;73yIO1wkFN#PM2F{sA6qcQbld z4wD6;W5<;Y^R7(;sMU+zT?x{=fdMkCxIAcPKf&luQA10Ox*wH83x7jY=AQKI#9{$L z#d^Qx&)!}0?B`bEb(lxQoX_H=Y@MdSSu6Tb=$Y~98yGb5rw%ZrqQ2_3zgTxIJjn}n zhGGu@1qnGvvs}3>tb;TwOkEjY2y6YUMFSiw=zOhUGL=ic-!iC(Wfmqu-X zNx?HHC0gQU)vjFwG;a>Oi+oUC&7U%Tq1qv6@Bbqtyp(TJs`_$3+wo~-IY@Zx}t#jtsi4(#ZEyOLcX!I7R zt{yYO3st@{44A5dFyi=iaw9 z-Gc#BY;UuAv>pbP&0rAl6hSqxLz0qzF+>CU_!*p?6cza}aQWpz`q@YWTbXYjRXBMO zNrrf$f{6(#ydAJBHK|rTNjBpIjcE8}Eg=JGW-M z$dQINVhN9&y}?8N<@NQ{(N||7;a7lXcP3I3Up9SE3Iod9)*ZPuid-aeTLbL0mUOa% zviT_?8n>&ehKp!-P|XjoX+F0C1j1&It$}c#)OUjc*&hUjpnqOp$4n9XG0H^t)_|FA zwl+ZM6BJu2QzFOYa42*X%ZI+m=f@;k1CZl1G*kZdqZ~e6Le;S=@k@h2;0)#wZt_W* zwqW(!IS&A%N*lv}qlcL{{lj^YY}m!T(01MF>|mkyu*(g(Qa)$hf~?JE;uxKjantf8SJPN}pax9=)K^K#s0Cr~yoGG8x;)cG82bpnz4Sz2@#wv1l* z$1TNLyf}357K~jx^VHqBcG}_$!9Fbu~t3l;rf%>(Fg*omF+s01D-G{JvJZePtE*B-^bW@E9M(g=|5VXZgrXDy@wRV zVW*JGE;c^=Kf+{_4st7hG>CCiV$ajWZ535WWj8NLHIQ(bdd9%z-Xu(0HcCSAN;S5X_eeZ0oNT#fY5mO73=7-811`FwOQZUDt6FoLCb@pY> z8+vO}V$(06Dk= znum2Uc~^nojPp4w&TqD@m2R6KK}vN!j{`m?Cyx?JPOHhY6Ciq`hutCy{DVi<8k${Y zmYa>cnX}Csl>P-{iQJeB+u0Yh?48CTih;_?4pq_?R%1YJ2bD^tV_vQlaMqEa(7DeG z2l2n|@x37_PXaX1HJMgolMDuwSv=dqZH|l2-@t7L6j37j#!#N+KOe=v$1v!4Cv#Kx zQE)m~DbUM2r+9!Fd<*v*Wd|BtG(j*H^$zrJ)gNOyNjcZW36A&qo{bT^U`!Xn)u-5^~G z(%m4rbT9D?cRauE{qMf^HP^uIUNiGK=Y7r(9fur-)U=EGpWJTAqC(2Q`mT-jmXUCR z$Yw_zimn9-x=}srlIyngWvBS2JjL&z?5rZ_2i4dN?;CKOgikwDg-`Nm<|kS;x>w^t=IZ|3|ByR)$cmr%Nc+_S0$zEw}ImExbwezPkuxP{!Q9EMn@ z*yVKeVH2weaYw2%RhKIF7IR7?QL3^O%d;Z~ zi`o21jbcT+1J}{gm40fb8Xfr6vU;z;sf4EV>@{#isX5#xO80O-HtA-gqnOrH{*2<&lIT)|0-zvXZ5_iRxVHe)hSlKT_rZM{j{P{q?2K2X%mN*{?03XS_JzK}KZPU?SY$*% z9YT?pS#tP4Eea6A)&YSjYyH!&(bu}L|7uhKoC-t-LzT(5qy1Czx*&cPm;gw?=by?I z0|lU^u~OjKHvbE?`j5;d9v}rABA|lvU!c+dKQtUHpryeTQi0$7^X!I!e>>K1Ctj=F ze^Gk>VNSmXy~gzhX%((U{8Q$-e}&oZs|G7O{(HKwOX6a_LPd!&4a@&S^>)9~W8Jg5 zbYH!|`boI~*o$?vI7-%*T(DD8rhV{95#Ft({F|4|19Qx6sbmOd? zhtqDE1YwPx80NZLy#6YgSm~QJgPrmUY@FZeCU1cz=;QX62fHNd1WbW*>7;NJnPKzU z^5gB1rnl^G@8`Rv|4yi8A8tm1*`cEY_sX$Lgf1QP$N z$&1&#!Q)jQ6Ch#urf~k7sDE2FkSDhYm%%N!lVL8+*1_RxBC(?1s!^y)J{c*%Ir(@R zD3c(>=Hkm9)l&Fb706R{-3X?_H^R;4^ld`y7r_8$*;OYEkp~K6D4C|e_PLY3eyqs* z4j(KFfkvyTHjks@nZ!KHG3jwZ<^_Zin+50P?lMi8fG6!jPlu%3z;V%B*5UEmA$W*v z0~-aQi_8Uba33nt=8%+uX7I zE3C*tMe1nw=8Bmof~n4D3e5k+0?Q`QA^BKkxqsCEcHcI}SI zP&8pqNdu)@P{q*+LnkIb#9^V6%O_jAt~6Y!9@c!9&Aw3tE=>TVA$HATWraklTQ9dx zAW@mwanL}kRTM}$E&@hJi$l5IlCWHdN46V3_dPe4mohl1q$1(L_sdT86V@o$zQdF~ zqQibEbc;UjCoC5~VW5h$PcLI{qlp9@vw`{3;(>l6GCV`WhuzJI)=!h9om1av|vkopu?t}Xl}!qhlUH-T=9;xcv) zM$83jD>b^i5Sch&1?*GkV;^t6AS*{&>~xa&)`rP`aynCDIHmdyqGG8gKe;v7rVOX)z=zT!M@LJ>SuVbcs!Co%PdU&1!rHram8Uj_6$%ErW%CeD1z7XuPC^bU%t5h79)= zQDB@OdQ}>ixU3the8+Q$?wKPz%ADhPFjZR?db$!hk*g}`vT}r}?lcfHpo3@5BMimo^iZ#sU`co1NIwJXq z53yOi>+dHF0?bnT#7~0i^4!QKjh`e4gDN5#M0zckN@y}9`>bS9T;-W*5sx5EV7w|n3RG_!Ej2kXE2Xog1($09gJdnA@7O&6 zFjOyF@&4$&gBU!zLfnm^-m?6Gvv1TqXe9Iob3%=fk~UFwr6F;uAOYDKwd8b7grGkW z0~~r2$8~tAjlGGw%k>wu5-=|3(T5l=u`32SHg(p@ll&oe6PW6gE0#MW1SX_9WL5W# z&~3D#oGQ~yOtwzk3k}A-!{$To+Vp~A<#;n)a2F8SoGW3!CP^yu%*W;s;B8Q>@Wz=$&ebYO*;i}=ES;#tO2 zp0SMEgH6lwga+y9^^i|UFV+`_t(2=Le)d^0DVx5m2zIyP^!B401HJ4&!q-tD_%kg+t$bs$%I z$=ap_>)lqqpEb@}t_|^&d}KURgIV}KhcPU^8&^SnNEkS3)z9s_{$0!O?2C}^lazlZ z!{Wzt%xmGXI(L#y*-t)^tB7aQTL2C6FkWP&D>+{92l7&Jw6#{48is9{@7E8)Yl7=! zhY~74Dulf7*c)l>&P(3QnE0u@THJyn!@Qwy1o;I`aF1%uW%SI%srth1R@_2W@Uh?1 zqbdZi4AmPrV)^V~C556R3py-Cu1(9*`eE1+$ax`ZL$?ER(=Ko?JWb`H=JGihIXZ>+ z@k(fyO%ZnnT`OB;5LyED+=t_bSnn04Bpb0p2pkw@Z{iG|XEf_4 zwDYMGDGtfElnjD(H{s4KQvcu~3V2{3_1jD|F!o}q?L=qN?YzmRv}NdR@P(H^^?bNS z(fT;P`)soZIVJC)r!aoG$B;`Vo}dp^0YchD;MEenW~@$vFY*Wqgf&$_d{G=QI*5Gz zDZ0*wSouTs1(alLDdy9k2ecW;1KwfX=gQdAJtF@Vb#(1IkYc3bGlaIq7 zIJA!w=x%90JVS!AQ=Y5aL)?CT3l<_PZeBx%C-;ZMBn(QA3(zw(i?ToAHZMr%xh5XJ zT6HXlpk=tL#4~k45w)<<ZEA?>g)|&yxqi`|&EcTrgO@9yz~^&P z`b7nix;jw>E#0nilWO28h6;w0-aR;)ri`c`YBsa&tlB4)(#+WR7Tqt)LTNMWr5Sj$b*uT{@>J}7pc`SjEE`bY>tdmHJG?)boThb0 zZ8phPO}W~eZ{8^Thj&Z;RO2T!wY?{eSho1#fl$ul`1$aoTwE|r^|J+-P*T?SZ0$c@X7vV)Gfd(&ynN1ajCG&`=KAbv?RPI&bO z+Rf|r;P0{J-ghwV#CSn}6qpcY&JTsdPwu-{fX5?AAb^pOCk9eL#Jzc0`UxlK zz!^{+p{%1}F$>*+9Nt%%XDi9@$-ke}=|HN(oQiax=)oeObLI0#V8101IqmpK+;a&k zKR1R$S;G*vMx~IMhcb_grRxch^^BGPDlCt}T#7z*YTybuTHM*3puAh{>Lc zBslg%0x=U#Rqhap^bo7sRVzme%`8X*R_~JZEgS#LS8v%!*z>S3Gxr40Pk7&{mt6E} zuhR`-Tq=0XQpsBG>jT{$bRlp<(60^sc#lb`1a-s%o+puDa%mB`P;axbG-vh?A%Eo0 z#R<`fndoV7mrc^RwBAq6Xj~(uKf;w?eby0TnxrnRFCz%Wh-zzt7(ESwa2zLUuTk}a z`6rvO8?E6P3;VQD6(rEs)yK+2rkiXgQ2(mU*|^nyWFcbPq(hdRqc9)<6XLgGz#-ni zk9J}pNxa_?_48x&!0>FKe&*;JniHA-z8Z||v_U&ZlA&SjJJ=}&Ln*m>}6Oj!4TOBqa8=+8hrlE&KcBm{JlUQbnzjdib zMb7bkRY5ke)^v|A2m_#^p1;gkvi`YwVTGFfO{x4~?*z*nxiNRLMwZ-?s3d&p zR6jtOVoLa;;|S8x)+UEwG`>+XoMKq6eQRKKwjR@2;YIg2Fz0X2Aj^*dsyOpfeI&p% zYnf8Va!H#;zXK^UAh(2>#fJX63S3$2cN}cOilRD={4wx#Y~7mweZB*obX}Z5yJs+d zL>d7in&QyUx$PdG6`VoHJNy2Fi!S7JKEIVF;L(s`9e8l#SuNihh>U&9M|~pL4Kh}_ z7vI^B^AV`Gz;WDvev*MfESLz38e}S)WSoKwdU&_uSbt4%adPhu!*C{p9U!jXinhIk zMY@LD9hn%sJ#c-HUfjXh`W6!mN5gJ!$Y+GY+}pC@;?L#N50KL0SnN()>pyh!2SiU0 zpwkaUT*f~vmwuY%RGeeevUgfuTC5Y9HkqJTzR=U=%)$@FQsODHZ&7nO!ba{zMk^zj z4=vmZptBEt2a`EaMe;7nhHHvI<=g1HYHOBABs~eLr`#5cnR?)Puk~(g*m3XBaw>&B zt|gl=&f6?2hwJ{W#}~ymQjc5?bNG^$d_tDZuXJzUrR_#XeZ1~x%@!!p?i#pKJ5YF4}E3pCHZY+!f@J-cgxO`EJBax!-h3P7r=Ab)A?quXH}( zNr5i*JJA49ii_~U?1*&r^HvhmNwje9k>?hAyd1Jwb&vfm?NY*$y>`cka>aC;r-=+r zYLj***_Y|y$Laz0`b;3}Ds>cxo~i}bg% zvDqxycHEHAeQdCvc|Jou^S&QADL6qY$b0V0vmZlwEmd*(-+E|0t$qR>pJFLT}D6J13<7)AQ&faY>L$5?JxWj*>N4-V*PDf zeM+7Vze5QQ05vEijsCTLl;VZrd!I$Up~RbcMn|u$q29qAazSiddc;&OT2AhCeo;C$ zPTP-izuO%%(Z*v5WYBa-m@0E;L5I9R6N~a^3bD8Z7#W!DfDG8p`8d>@;u|q!8bzW} zq~(@PH8tR#WR&O|3KQ`mGYwfX>fo;?)gg*G_s{(md4;uTWq%(q#p&cZkm&4NwlZ6S zr;w70Qe@7fty3cjZ(6n}$4gazDGpkqxhR_L&KUV+c`of8-k&mzkmXBP8{6w8XHQTD z$VAiT>NCmiYCoAxO|Q9c2$^+>3^ZBeDlFmm$0G@Ky%)EM;ti*%6YNRInwXE|3lj6_ zjXOHyQZ6%$y!rJ#uBapGbg&oLmqjKRCv4hem#MTOIfxEHt_8-}a-_!3EVF);Mv2Rn zmEyJ~zsd$}Z;tT8#xQjhQH2~5&&aj3g*p5Eu)7r>xnSUjZQFF|+A&rx!X)pY1XDm1 zJ&CF(k$dP9sK{InQ4YQDk_jiEPZdDyZ^!rac3KPlA&oZ8powy9%*pzz06mf3U$2)- z1nBUY@Diu4{(rG6|A-RY3KR0)Nt5sz{h=qO01@omxpGt#u6tra1M7<_?d6PUSnpM|aZ}FeQmQqH@=Uuxe$fmV_`F@tYOt;pOTPC)dCZkBF=}pd%lA7ph7gtl%Z~FIBY9OSh5RTZUe$hMckElb{Jyx7_`kiWQf&#)Gz z|G^OECIDOg3^KhSn80_4yG3nL_Y#&mH`}%~Ky~)+c2(VkxDrxJvi}+KF7H}uh|dDD zo5T%apBbyu(7kx5h?>ha7Do0#=^Q83XR!j|n!p38ph7?}f@OHZS9H|ms4Og@U<#Af z47_*9P%{Q|_Whk?&qxcU(r_Cn(rA|7Zj=of95Q>*ZUHMb+y?yR{#%M8pzPXoEgrSl zN9+P5F7u_CN0$t5mdy_Fcofls3Tw7Ge9@CKNC{;Y2H#TR-PSMXqwCXLaPiP?#vx5r zPBhvmGLvS$*h;Zg8SpMr%UE7kl)Ai`I$=!CYGd934-B7C3-h1fN^|OS!}l+z&WzP$ zx7PIZV0SZj*AUUTu(Q&6&FA02a*+k+6PolYvr^!YKBBHEvzj}m#_BSs7W^1syCW67 zQFYw58Y%(}o23sbrjFkr^aq;^Gwu(nDhv+3gM?3U->*TgmAW*7fd1bxUy6=UF~f_; za4FV{Izvwf;3jF<=9N8gzt-JMrV7GNO-tj6CIuvPSm^$dzv)dXkIaGp4&y2edQGEx zGm`xO$GQKS!0w0wV_`RP&9TXU$BF%Cd`t04Y81aorse#1fZ%^~1pR@R|B4oWE%@h9 zH$oiwb?^#Bqx8>+Nnkz=d7TXVE3?Y|a}bRhjQcvahL-=@|G!J#zQ(RWGV~MvIT|K_ zW_-OLflFkG{@*1}UQ^0$IU7m-InL&Q)ewK32vO)^|L>A3a=^N3m943&W!@@)?L5`ng|#bihQh2XkYHO zzZALcjla4OMSY)k=P-oKE*8F=z}(LCtB@C}z+#SvjtU+*nkJe4M;th7JeJmvc4k|%3TOt&nKu_ZV_;uAX`5x5!*YZ zJ!(=Ix-TQh2+nDKum9#O%9!Dx34>Vvm> z2JsEr@{i3~HOG2;5RWsjy>l4ZI~D5#BeE<^)MMEhG;9DS#bh00AKDwW>VRAUx8h@< zsReKV&wZZqif*u_)+ms@@%Z~|GSXT9YF)5OE{X`k=lDxy?Cnso>ckpC(&b)FeCvGo z%ed&@>AQ(pgXQ}WxJ6q(fqFNLCI+Rutm7PRdPv8@k!yzpOp?`aX{%ow%S|`e^Hj|% zR2upHO+y;1^~SklFV8wx0~v>e%jqi1F+BDRu4_Kapl*w38w5%&ual;sM-UQ@bOZ*z zUj5)HlIY&=u|bX|kV37!-px6scMSF8qf0d^m7~=iHNWHoy9~@TKzoK}jxE z`T|g3xC<~M>E+rLvNumS#II&AKp1#Qd9A!6`@EkwOiQV<*CnDpIDsLUmLHBXa$saP zJU#Rdr-{#giApCxSP%5%p%TVmq0PoPLAtJde6-ajmw!!+1pMfH`N|kn$(FVBwb;R) zr1x7kwk9Q&!k$_<0F86BXM~12lF1hPFm>k zo6Gf=Qo(L}v{I2(>lT;wyt^`knjrz2P0=cA4Eb_lMpuCS02j)l&`njB^Rk{P&Hu>IZ!${MN(2(p-Bh z%zN8cZ!+xK<;RGi-Yt`$f?H0e8M!{4FcEsI`!?VHWiK8vT7PD>_N-x?AYT_wcHPO= zp1KhW9DQ8&m2a#Ypn{}0i0@4J`-b@Of6Al&RtPq%$?kCZq-0xs8`CM|7yJkb9pSRm z6Aw^&%gUm2T}Iz*>mQ%luCKo?v{1AywzP%SuAN5z#g>Rss=^l@1qRj0=rBFy6*4lq z=Ef5O$GcRcZZ_Z_s~dp+*!l6h=KZPeNMrh-``}Tq(`dubWl=S!$+R#mCoNJIEBr}cS^XU!689mg zzTZ#EbuezYZJ^wom}G~yzr?!72H@ZKE&G82+H8iBI@`Ot=1)5`cTzP&{Mox0T#u@# zP!oFxc|n23(hzZVENP%t-o`1O2(FAGA{DAvR_I|OP+EvSNij|OEjv0qMc@-HU?k?0* zb=iTcFmH7zIS^j<34$HAmz61XdPx9ui1 zG2h!0uwXf(X7PS~t;}7eP7NrIh?j|vEyThW-eF}+o?@@MrKDt~ zoMvlqqGXgf5RRQLRm48{Z}(=f$Zo9L@+iJJz7X^l`p(%p-2fWb!)9jBwVd&)-iPvD z@4L$aDp>kRmX*zKw@wt@Dn@MU%#&B1dwkPHPM3-RSm)#8{8O2b(>LwW-_0v?vAdl* zzARAys7LzNmGM`8E_>NCy~yj@-D2E?evr)bf#8W<2EH@DWCuA=gmu$2%lx=0vM7222_*$pcC*RR! zfTNqg5(ug^ujzUyM^15Qc$r4$NO%H@8(jfI`k+AaL-niv*Y$XzBtTx&M@%XzjWHFR zr~46;lxg&ZG_XT{AV#9(e!qY!g%0k(`*z<~T&_T(Bs>|GQQT-}B~J>5_GrHVMq}f0 zJH_shLeLcr5qod?qm;b@%*PNO$y8yz%~2ARzz0_;Eq-`)@oN<32ty1Rp07KJ7>8?e z@nfy1jg>a{2yQ^b;I_h`W8UBIZR|{l zq9DGtz$}XA!DNva`I{zo@f{r=74bswh{bE+NsdUKa&HPAQ@ll|=FqYvu3JVV7-6r# zc&eHKdCOA1MZJk?8wEx`n)!_~&+gVr}C5`KjP?w7@B}@%`@) zW}gA4?w&f5=d-03A=SfgzV%@=z7-0w$1|y=($`wgI(;LZQ#&b#C?(l=)nN+QSz^*T zFjL9xJp3bYz5HY_KiDy=ro}I+WO8!5=3ApQ#DHK>?1*|Z&;~KlOf$tiiRS;HFL$R? zuBeW9Edh?0C>Gp37SQf4FHMg2(3m|;sb7-!(C(tptw9IvX%&a+ANG}gDE7vZ;BA8> zZh%(Ct6tJru}JJp+AIA;t<>)lmt|)UryKIA$7;XpT0tY|00P(if zgsK;}kjxVX$Nfuj*3zI2c?QWRN)K0GH9F>-F8oMgkA zzm7#~6Jamr!l2suFoJ8SgrFMJNN&rF_lZq9$H2=^_<=8VdHUw18JOO<_QzRv&{I*+ zdd12=oK8DorpW!qo^!q0BAkcA@naHnj^YicHRcYQD+b|^ z4e=<#%7!$=Cw-22c~r?zsGl11bn(yh>CETBOTBqte8Xb6qi&wHko(&~Krz!H%_gG& zih9%C;-6&tb@LGn~isWFu6lGEcFH@gr)DxpJq?}6xg=ip=-G=cP~?V|SMbF; zmoYO;i?o2$S+GfB`(E+DCmMC2Qmd9K8hx*YoEC+-jBUytbt;|7I z&(rFYA9nFsRNG|ZovmKUXG^%|3qq&(FAO8LmWdM4jh|L1LK9=Y%v5!W$hP;O<;rK~ zRKg%`*{B|AP*)w#S19U9x~vH%Ed4c1FrOJ1=a{cXekpP8PM$s3NHzM(C*$ z)q2Au^8{S#dqmKN4-DzwQ5*hEMAaJ8iubDYQh>NI$aRc=RUz0qG^)kK5_FuB(r8sh zO&5aYwcmi6><6|XS4?QcEFEG>IDIb_pYSm3zi%i_F~tRtnAI@mJ&8ZjJKoJzZCgwD zM5PIX8}5d1z(pqnB(y}8&LqogZQ&e}7tkkAx_!7xs7 zaY2Z@B-`zxAT|xiUe!O(xU^u2j7P9>@_~z}v|Q58|D!sn=>fV!b-Q!T@ACcLgRhj_ zfsTEA?t{4bH>PqSM=`Sw*B^RB2F=ELaw+A}LcDaJcuKW2V#=seV>lOg;XIBKrZRdV z7wnM{34NWRPyfciv0Ns zY+*HenkVPHaxnw&3Rz>g?(mpsHjU~Nmx1>DLqZ{BdqlKnzfn_vI8#xYcvWHoz z3Nr|4Rp~#vIw$UR{lJDoWGFA=(?agR>SkX2ND-Y=?Wh7Wf$yx9eYBnNppaho$8S+I z$2o1Uv7xa2k-i`VgyH#ufv*Hn|JGzQufyRNdk7NL=M5;V)MloGd4C!yM9RWsbnZ+E z+0k?idHh0-uPs|yC4Gb1$Orw-2j~P8OiJxFqjR$ZoK#Vk(od_#Qkl|V=^`5RKSMtx zp@+%04z|^MA{S)k!8Zi_e74DV$_eHpQ?QJ6FC}q+)aiO$y9ntuXqkiD;`7-u^-wTn z`+aj*dF&UTV(0pE79r$UF+XwY3M;k}P%5-Vi?kPXoa?5-p|%MN&$5&&kS=zfU3%AV zimjg?G?D)t19>7^TWaS?9|*0+cm~?!(=0(RO60X zqjq=)(1@?Mw0b?E{rB$$Cz|w}Z?D&)1U{&BonT8}ZG>WY;`n|zlrIWt3(BxaO^`6| zL=j%|Sw9@Zo7z`kumyO|qD_W0INmv&$yE<&Sfqjd6^5a`ex$O=Xp!@NoP^5czpP-t zgn0ro+;7>aQ&D(RfzfeyzqI0XrzO+T+!b8TajcsIQT!RCK7a>JR{7*vX|57N>m=pe z)`YjhCzGU=lRqCwgLfq7iUNEDv}ad;tUeCRoar>9DVT>~pT~&syqhB~=QxkpJ2qCL zH+`S3=|MF%znwl@L0>Xgn@4mzr=W#_mT{mp>lMM8n9F8+N+)`6cO0kMOWLbDgO+qj z+Dhhl_0|i`Go|vg1zfpH`Tbf+_ICU9@;S%~8Vbj${XE_Sg%1e~SxY*c{GYCk{mx04?C=vQ$KARVd z_B;8andMwjPHvZF<^F(Oq>kYJN@C)kgcwNRfVj(F@)=13;f1^O9ENy_U=wAt2Q{UQ zqUFWN%5VbIrX@tv~qWk06XE%Wnr`%tjm^lu%d|76NtP1mpt|7k{_~-J*vPNR6uI`W>!^Mm8c3ob%*hrW zE%2KFi?XoGu?vzXzIg<6=$H>z!tr6G{LbIo2#j)>?1Hx)i00fyV9WZO>l9j6_c&Kd=N2LR zfFbAB)1&TGXD?6w(2s_X$U#m#FQtZk)U6KgUwYjE{#)A7%YOe z%5*>p{7-Y@omY+O;<5^?*l3wpDW6!!;|N{6{L6Cg_0*# z!X22OBFW3Lfc98o+MJMSRZidNJ;j#HiT_?p_RcaO?^?^BaMj(Gd3b-C2vH}MgAjVm zf+n@YW<$V)1Y3WmQ9yO^ksTfB8cOk5Q1~(>-$GWEL(kH6k*STXbOQ5*b|K8hGs>d4 z_b#-CFbh9~pMoX>yR+syJ3^INi3+WhBqL5d{^ZFF9}Z;*$wlxx7N$FIY~6uQYFKUw z+O6^gK9qNWjvinBTK5PP;rw^MZVnH%h5{Yzls2Sn~FWVjrhWdxpEgGhS z?~C#xQoqAd|14q13urLn!d5i?vFYa`&u~xqV@Fk1Qov*ix~HU*^WK`dfp2HL+smig zIW#)OYZymXM{?33^^kt*oyYjp!0+?$xo72JA!cNTatnV}7?@K= zceTtTk2)rhr95{ieEWNSSI4ODE05D*fT~dq&ul-#H^EA9gYZzxUYy2y&Aqfm#o2Lp zDV@}ZUU9n8uh@Z3bSY(X)E-C$ffR5fQMdugiH0xh2HF&P8CQRVscg`qBjlE~l0)F* z?COPaX%aoC&*gp(>R@zBMA2LNe4IQht)W~}^E)gc;yqQ8Ba=t42*VfZC90@=^D|jq zH(6JTH%EcA7m08-4P#~N9Mf~qfTtc-!Y3GYugY`_!}8kq@tkt8mnQxQ>K2JH9QgF5 z`{WF;v}BfDM5cmNCqQ`<_8;(nZT4TuJmZvxeZ>X~JM`}qGUPd&GhT;*Jp0&}_o}p+ zvm5pyllMfLWKSl!0&-W|UxV|j@x>-A#>Ctn|B4))TR7&5M#+SDN@wu9Otj2$K(*hl z9s4QwX)uA;57TbO>swsjCR;9+)VrJZOyHE2uw%*ZBpmLK$Hu_@Rh{g)H3kPIeprE8 zo86y#NXle2(WY$s8orP9D5+|RwIgg>m4ymT8Z{+GM4ruJA;){rRdwWM{GHAQ@lA*o zlGq6P`%kS;IuI`}y8zJ5;a&ejoOH%|(@WclaAC+xS-%}w1y>8c)UeE)dsk)IVd9B* z$GgfgpB--V@S1B18^C7gLv8y#Ydb%THbzCqZ#-bzE4`t%+S=zEo8Jjc5yN(Yrtc^c zdqPUWJi4dtnSijKOP9|&rX2cblBXJ_(m-MN^KCRc9XGp5+0eA%KIkW#_SocdebWY` zpEPZ%&(lq|M-6}Ppsb1F6K;|{#8ju@z_*_*QpMvamwopO|C*s~N$Qf2Vf*hQq^yLz zkVx4DY$hD>lRS1ln2ZmFw|%zX+T&WJ7bBp-8GY}oH8v3s=mc&g!mT3b1+YfA}-mTkUKPed6Z*Dl5OzmIQdu|5~#3! z+PIPV>t^`0CWQsTl3pnH(7Wy;Dr+xikOnFbjlw$f&U-6BLY(9Tr9osjMb(@hJH!Br ze+!~)BC(HA`9b34T5`=omsSY3`%s@M90CF zXCl)0`c^5zq=W37=iEPV75TwHMgiwEF_r7MHQr*fl2fBb4`cB$W0G;Y>L9u#a^?FG zUO*K}`EA;EQ-|66SmwsZjJ?SiQ;pmHUnZyw^c4cp>?Qq1Z^q{`&k7Y%NCae#^pwc6 zEKDpyj?r~eX1(}@@HOwUsluQ%ZMZ(R(u;0pj_R=Mfi65zbKi>|MG?Nu{b?Uw^Z26y z*J@7-iaTTPzQKa|=`)VWe%XF6J-3U~cax$EZYx??4(qDP7&_r)Sc-RNlXIU#{jBg& zkVNy=sqtk_HVWvX4`~}?yy&=+!GBo5EllnUYm!J5ZbC8@v z^YW^}_T$4o{uu?Q&Ggytu{mWlg{VNi5uN0L`^n_I-D@29!10&52%77O{_ws%MyGDm zggGMnZ9rRHMG5H0xR`w2yEnog4T*&(l8-WJFhZea$%9eO%8=g31&0qjDD@&Nr|Zae zTMjhVZ6-Y6W?6*3VW)bg$BD8nQOQZpVRB|s(RfmLRLq?>rTrSAhqGD#^#C?MsK!tM zIgI6mkC3%HFDv339g=cPG2@8Cu=yhyCyuJZMU_k7DueBH>?Xu*B!Kd}CFNZq9ZKTG ze8PH(nDGpIK#j3oHVbR+n`@LAH?k_$muUre!fN+}I)S0vP0jb|(LdSa?dU2@W^$Kv zBU5Fg%fvvF>{fa_rG9nOc28WRy68B0dKwiPlFOqyITXbs@(j)R=Q-@|&FY!~c_|9$ zG}QH&J$Jfb1&d^=70N+>9zVp2obO0|k(^A*8dNxG`(^!}P5pdHoWJ3-`n7u4Y#z_l zS(Owb1WdkNIMR(AZYePDaN|K;-&1^lWJl>K3PCbA9Hm5xUze;tCdOhd_)5{zQ)8KR zn0%Lutu;{he)qj7VfwRXuAKc6*8zU^=!NJcu#3G!rKTU3ueT2!gY0@;b+~6wxiT3r zQgUCG>8YDTy`P0Vc%kNk-vjCL6%yr*qMEym2ityR?&%1!F(zpg#-i2O)a)lXVuqqO zoZDufcHoRA!!u#+!XK_Pkp2$y##21Ux#$Gj0Fk(Rc5-+Al9HW)raZrw76v=tc%d6Y zCnH&q2d+1=-l3IT9t?DQI>3_@^&(V>Kn2~|d`m@!w#s71)2&kbr?~Hm5^TuxTjw`x zROP$>bq=J#0m^+^Q4v`5pB{l>&Q}kEZm6!uKPk3S7Qm}e#lq@vYx_@@F5wkH8zSm2 z|7QxMxaBK~Woc{M{+}8%sDGW0D=M&@z#PQ~(tn;F6AECkUX`4DF2nij13zd`#XbE>O-Y&(gHg; zUcl|Ig@5$@<=)uVKy3ZE&Ivb*5mTMTh<;~0Krj1N8H)v+i$h*XW@0gW2yOJ6ZJ2Fo z5Q|Bdq1AZyfftxB63evm5y+=>Yl)!MY_y#&9ywmDS1SIY_#p;s5|!BRaHj0y7x%=l z6ov>5;5&DVXysCU=XdA4=-3XHqX-n~e+7;Nf`W7wxV6%n31Wca2)_knZ zx?6~WsHZQ6ZoheLO>|S}RlfqkQloe0+uU8KFh|AT9GMa@InVZa-RZXVL5e4)zZe%9xjcYXHuk1`St(SY0tPSuKt}aoD7`yx5}4)*UK#r8t> zG#JH<^5SZMguw(7=bum?xz=n$;qd}w31BidE>w)Zb z_Id#qHC>}(_<`sz56sGPp#4_8`io1*E8uASSs^T%54(oX^3LrevcUC>=IR2E_t{1V z^-T&VwBR>YW~p2-mY+{L?BmyBVcxrkjgEOQjJw~wK0vk(j6We9U_J2paa7$7?{PST z^a{7dmA8JHEf+@!e$63eoIW}h-CwM?KKluS5oUYR&W=dLgBT(ctMQld9H-t2t|tge zf+H{>8sEqwI7bk!2S_)v08BD6yhQsyO)Q%7vHgH}BZ=QxyrJX)cRjS)@%3w4Z^C)W zbw~?WuLl!I4YXXMF9C{K(YYT>E)3EaiSRjz;_k4b|DJ2H<>`ikfVW(kO?!iCh>RFk zj#PU?EjXvD89gKdEi~xe^~-51J>r@lH)6RKQi#|yL*fe9Fu(`X9ZW6+heF6Xa?cUP0bpp~+MJxd%Ziu|G?K)8|W_wF7SLxIk-zx+{SpABZn^^DSI7BOTv0zu*5qi2He@m>7{z!#>_c|44 z#(^FC8h&rkgnG$6$Kyl>OCCS~tCSAk^Z95uy<%JXPo>_os5$VHhP%|n7|Z~ev|RN- zOaJQCbC>O2>JD=Gy`$Aqb<74EELcG@8B3EY2%e51mPo4G^1rXJG4`KFiho?u7Ks^r z*eI-#xu_TUe1+)Vl)_&|mnY6^6aC~)Ja*L+tm_Y?tTCp%MrX3cXGLiiGhXAE4~AhZ zg&`FMlu6=8VNM>^bc-%nrW?(9zhQAl6FHk!6%)vwRZiv4Va1|lmyQ}4(Z_>dF99(@ zm~dsJo0pgn$AxN~JG~Wn97$mL)(!6r)7ds@qPTPY-@?8;f6M**Jv8LI$5H?>K5eXq%nYax7}Dpf=)wsbe^kiHtX(->EdsKH zP7rgIj5k_oELUHsq*Gn$6jJDVfZ!+{tEg0KpcnDrHP>w0)LoKHwcss6x~x&*R!QAb zw>EtegA+D%ZRj6~tK^ZA+=xA~XMSOn$xyY2CgVC9;Zr<3%;``J^bv+-_29xOr~DA? zkfZKPm1lK2H{~$CHGZ15>}VYImjDt@s$U3s;AK9wuQ?_OjydjA3O$+DAiWLUYH%vv z{Ah&G2cqdmaPvAFfQ6*2xJ`%<+Qs_!>Xo-S%~fWudn~KhV~WP(oA}ipw`?c44pT-B z10vGFlu8DNL{&x};bqgZW6JgyF=N>Tl1zpnC#^CK8Gs$8E7wE9KqICDoKw&4Hu;b< zsib)m{6#zVBp3|b=<*lNNMo1qs5XpY#*(NH(iT61Lg->q*f4vtH{jeN=j6b1n=TjB zpUF>JvKmp4iV-hN13Dfr&ID(;KV7_1YF_JjK49J?ksC~b8{MS!0F?JBd%5I))$8@S znqg+igi?;oKSjW#w4jm-YB`%#t4jJ4og&p;vB&X(x-+?RzSRS?xBqkN@Tynr<6Xhc9O8+16~{$x4d)Yp zoi=x$hCRs)$V9Am`oqrFwojEFvG?xqsDd5s8qr%k)$r3LDI2wHocxYzlX`c6|LrlI zkj_5Ao%yFP4>abEeh}~@WZi}uaPVB#yS^OI;6uo(W$1HgknID0x2g`(ofXzp5NZ;0 zADakMw|u0CBaL&pk~1Vq9}o>Lf~GJ?Lg_m-LYw7Jw0`0@-s4h zM_c^_UD98kP6K-vQkC87z=uOVhWhfcri#UDlg|?_D{9^*RP-S4d`Jy4UbCtmS^ASl z$9L8#B!?t>7S&9-QyFx@C<*RIv)-Y-h{U+z)5|A6su37Duo}izb8w3vK~|ySux)ySoQ> z4;I{=;O-isE{s2){=)8k97Z(&w<8(Jb32T zy|R|R1etFRAj0Y*x>*Z4Z9WQb)*zvCh(++N1NnZg(%FiarjyKwu#J@;Rja}Bt%Rnh zU@#;QarZbZ=viq2KT%1;KuyuNLj$%>0B@x?(3N{P)m}-^%QHaMtACJ`UTRVP8NKe3 zh-+Q)YBw*F>Iq(&{{C*1T{s}nFTXu;MWAgj>mlLY;%+o|ck@({RN3_?S+{wtOKsUis%a(w5 zT(dsS{Wbq~F60;BUV_oTvnKs$>%6%&{hNoLXYub|2E&6au3v(B*}E>}ErR+?jXAa+3qlRvfvzO1D&0PNa!ut z=YA4t$Z#bb^L#zpvI^%tX=U9CtqB1`$)|ohQk+SszokozlLx~JbtO;g zR(TS*>kxor4_VQJh*-x(H=N)EsB{euVkANP8#1`l-ud>JV4}IiheIZC0bf*LM*gCH zNl2en1{#`=Rh|dg_GJ8uE==oVL}%V{ffM@Gvj>?qL-bbG>2TWrWw1*Ds4 zXODBQ8=>@)HSJ!OvxEZhib;Yj#4K#%G$4oHq-CRBeq@*wgjhAU{$WNIsN z&bi0~w?r5FWnH}a1$;z)J8f&Q3x#@C4TG1Olh4<+?ywPT$hZnBpo50N;$orM8m8|N zp22srQDKnhztwn&laa|!O=r-q9J{*eh7{Gcw1&(!@s4X-E4p>s%LcOChDSEpA|^BA zXoDR-e1D-@F9*hU#>2_M-diuPW4%QuvDeedQR;ig;Bzjfm?p zVKg&*ksV;*#qIQVHhycBR7z)s&(B#YzsK`NAj~c&97cT)P(7K;?C;2QDwBb67TVcF z%R3cJT}p!dIJn$G5$Ic8Fp;FHGu}>xk+5K#y z{-q=OAQChW@hseqrM$~bTS&JGE;)_YS%_KJ_Uy|m>F@3fF<)H);7tNsGH zkl(sRcy0XyI~I)T{;!(EejO8dM`(va z(v?{Y6C1zPsrtrQ>}}o{n1$^kZ14ok^}t~#n8by@c&F=wKA+_mDnH27(O8rxWekNJ zHVbg)oRG=Z*Qjo1O?WaT(AVcU3`_^LFikM@4==ecJ#9`x8ySULRa}i%Enqa}(+YTN ziyQ@D_=5?rtJ!Q|8_*Y>^x)E@?oRWl5}sbm{9Oas6l8N@t}x9!Snw^z@&k4w2Q+jP zCkSp%b-#32fCt!yvkkjjHR~uWq8Lg&YxCrj%PKXoKCpk4Db&-zeea~L7Er|H`8u-( zr)602N#v7PEf3jaNlxw`_z$#1*e>3uaL+N1{qX*ey%iCU?-yT7MEW7Y z1X`5UyvC6N;hb_4(NeHF_yRbgImp)muDHXYDPx{KuOs=4J3Q%1^cJt-@fICW4v^j`kgK64ysD4t!}MVWV=2bMMIq&)Y_PxHcM$$o+b&GIBeE#=1J#; z*f5oyzL=|cId$7>Fdw}~IOY8_py%vj+Zh~cG-mbpSFZPY7gTq|yEQr;;yDqi{Ku%PA#{YhYnk-cIbE)9P|cO zz~^=5hd!KK{%`JN2l{%wse+7!oA`fAm5U+h!6s>WHt=DhD0EDNOeT(zDavJ!#deo9 zJt100d&`V7e!sr2xA*vsd3oELc4g>(y|788vP)9h_e-7adY^4@CXd@OZsD`(QXnVM z+>TvDagCWbC*N-{vJ%@O7KM#2h02eV`E3Gm4umK&d^I1A!Xd#(N1_;}kE#?1_r40B zo;n(dd+7Ys@P0td7?Z`GF4sORSzBpIWkiL+D8ybKw~PeaDn~{I^VkLxdYVBliK0!( zBmSt_(g89B9}~o)lTComqVtk< z@o?=MnS+$wr8bCj-LRZ8fD@qyCzyLqw2$Tn@ZImS3$R6|?sXMdMgb6`x+Py|HlkhlZ|GYuOtN6u`BR&F%NgzO;U%v*#I)$FV|#YYfQ(gTJ6857kEBgBJ{ zif6m^n4`FN@#6*(JR;|m#h4BkEa)7!M^p6J?(Oy` zD{}|MArbeex_)z-gk#v(yFv9+In?tQT)#@w>G?Yc<~1Y}nDq@;$r|Ae4I&$?-HWbY zHX%^Lwnz7cQi~_gFQ&qv4(t&{6apja<09JoW-{e|Cc7!>g@WjdJRqo`^Kvqo(X&*+ zh-N-yDTjf_Iu4s!IWoi2X$X}JT?UPKzi`oIqSSTKtpeQ-YV#lxP>4d1WmZ}tiK#_{ z$ZMXoF`i=vIq5Jgs)^{2Xspv+9Q&4l3PKZN43dbHb0fK08rmlhB7*2nwHwq~QHE1j z#pAT?Q5N{g{Z?)0BBRX$-=EPmS9)CmAq;wgR-sC38g=%KNra7P2H-;9Se{eWXMxP! zNm7bU#2q4;U5{eY$M8(~zz2NC;5vT-Mxw(>`?9q*wj*si4Yc@dnGYkZUs4j1&a&+K z*k0G0%6%mx=M5bw(huFD!5k(Pn?q@QB^1L@H z?`z>aJUB1ohxf07EUxqP;k!T|FG69lfmXAAQOwKr&5(X3j*-h&q%a9QnLwJ~L6%6h z#dl%3G*Mq%5s3rek)T!Lq{I6Na&M$C&7fr=jp*qm^b3wuC@Nc5YHjr3j-uWf8t?vO zzb6}#t@RIsof2#z82Ouq^ovPw6AsTaOB+_f@nPl}3L)jKz_0xf?J= z(2eiV#UCPS;eDb%Tk7-KwxmJPjIYB-{Wu`f;Y-*@qrFw97dr^(8E~gVQ=|L>VTj0_ zaT1EeGo_-~oaIkg;;*TZ9M6;*kWku4K6)sV?)-t$JH(6P+aVQroWeu`=d#z;$ftp8 zB%$X=ye3Jb|F9E~>fq#|%Yh;Px&a&YnroMTAVV%im$63ulFd`B z=pR~J^KP8Mw--eFlH?noC$e;dx;ECd{K{asxh93PX|x_}9_))b8#`6q${ON)P2Jb& z>@%B!`N%8ZFQCTT$pvB96O-|K!4C^2Z=Q2b%;I_?l$hr=mImY}Qg3WD*O>#smp>^j z)V(jPi1}{d*SroGWO0DifCNfAJ7liLUztD@yKyv0`}@(GH@~~(hvyXzI@z?viKcJ( zOPRGg7yg3M~r979TWVZwSNBI^T10<^CYAwg@bq|7UY2|@AwuNtY( zdk!&DC;8(aV-tlf^o6#(GYejo-|91CrEv`+$&rVBF7#wr%kSfMI7a zt0i}#b9lG@L}{+@cc$&tCz^)6dyi^S3Zro_Urkf}ZJr6TdmJU%^tESXgrp2822|Kk zkwD0NCalu6EMN~&I1(Wu6@%xJe5S01a`_FuSZh!mnxG!iS}Oih8#uA8cj z4Ek3e8=d8Si<)y+FvR>v8Va%n!kk;g1jm?nMM@)0Mew7~MZMdhoK#k;W6xUJ@YJvn zrVFn?E6hueM|%|dN1>LO5#-K>q#UJWzKZ>TBV7Hm?%8eYI-o=S>HQ zzDWM$Sp(0WTJY3l|E?f}@+wQk3V~zWn0wxl7hx$BvDOU$Y<#ZC{|i687dC)@Gcx_K-WjB8CJ=6WUXA zs8vbI`C9wNoc42N@IBv<_HWufJh9wZ{uQp@Z!CAVm|~r00D=D(jf_QwmPuol`yuzD z@<|>%khV1$BqYS!Fcc;wMirMJf;Mq`?3)3y1XZ=ZTs_y=FX%kn#@sEx0uhiL2A>q> zR&i_9YE=$Y{w@0703;#4mpQ*m8HqoDE2c6}PkHw)dm_*)lM>i@vR{YmqB2PG@JPNN z&6UM?Grpjk-r^5G71rW*D#rR~J^m9I&8a|6Wvy(e(9+aDWXqtr!I7mp8eY2jH*JaV zchW4#xbg-{RS!XZ)EUzvi9-+si;6Gu8LVQjF{(mb(#aJXUpg?C*x%MkjtsK9pAKRg zU#-9M+B&`qZn{d*e0>BUOz@o$Ni;_;3fzq6#e7g<9pq{|N9;*e+~AZIDmMAy?taQvfr3(g?IkF8eY(O>LWHnbotIIKOjeslwS0Gs{JH}EA51==`i2!-4Qsq5ECO>R zi^<01Z#8^R#a>O}Q1*ObvXwDa-^~qW>Zk`UbXt z3O)G;l*fMdKVh>atF!tcOlESuLtor%^5&x>zV?%ZT0NLAw+LSLM;7kCG(x}$VBQH^ zM&kd*Pw`z~MQhgNC*CMZe{wbShot06jUHk<=;k>$cD$3E@Ks*6|xhQniK!`odFa8@YjSe z8wBo~b4k=0FT-uS$V2%KqaYCtgWKXQy9j6j_bCeQm-{y-1tkAWFLL&A?N}wjjBn#_ z*~DMwO$-4>D*2!Br9Tg3GpL$AQ)`~~d&oyh^zS{c|GCo_;7(Y=rZE3z2n~2&6rtA< zkRD!CxX!;FV0t?l>uV(%u#`$npw9>8 zS@Lg53#I1HU0dEh&x2N>pPZ^-5GD{uzIVH=`C6H#TFygk4}Lis%6On2x}w!saYB2q zW>k`&oy5urNyYWn5a9`@zWJ!#Xj1re7QD6{qQ5sVG%H9d)@{22jByADV)l9q#vJcg z)p3i>(WRP8c{O1yI&fZXz%WV*CL}>F`7)2rE}agcnBcH3k&oZCG76TJ zDmhnIMn-z-95-wd8t~yVR=ECf8n-W`nryKVSwD)9awARw}EF_|3sN^7*d8&9=&w)jZ9vr zCT*s|R#>{|-CUXGEbWIROK^=;|CGv1B@y)VZ_B{+Kkex4S+ix9w558qXHHsw=t|wO zeqW}3fj~$14`&=wnVI|jSY{9X738Cx#%66jI)(0Su*Sw@ z-gW6{ETvOyiu(|=Ia^_PAt}Yh!^GKeHdnb5O#Qe$qr{8Ee(2m;Z^P6ST$kL}pdTT2 zuypn-b8%2w-HuL`6{U>>Xna^k_c5u3$HpXY*#UBlKg(MXK163SK}wfux_ir*=}6n9$@25$Kc2sl&ikMksNoyF^gxhOjnb&vV0M{)TCV1pMtCI z>KbMLM$}KGx5CY;5vU|ZW_>}SG^oR^2aDZ#Nzj(`Wy*JjtMII08R1T4d5Oxl{qlS6 z>?D%L67=6oS?iXM$Ka$-{<@wGi5|@vXh-SE$&pXS?HO)s6lokbigPLJ!R?N-R!#T0 zjGB9-J!5U!9J2d4$jlK*el{kae&_s`OEbYtu9pFI4jwJL*hJ?WKpO2{i>P>>LlPgh zg|3hVwr`c}^~qw=r}r4es}9qXn9(lPFHw*ZARD!%2gbf5WE+9d+dE^k;k?3+AO28OyCf{u zeEVZ14t}!wv@G1lHLJt>&DGh2bJ)JJz8)i9$f$e5*g@i8f4RV>xFE#Ljgkc^+PiPuGI^~v5}D``ci|tosi2K z`cK)<47`fxFkUW+#I9EK%zN}HVqne={uezO^EKY?%#g2HPUoIN_NYq(+0!Wlg)xy1 z+k4l~+}uj%cO!*0XKWir^W;x&it9fRaO-PS9vePWlRC7KWiE0(nwRWy31 z^4<)ZdSIh6Vn#&WiDBG5#D}>2sz*UHiZIT{92Zmm8}uMF0bj8vzVX=}(xJx>$UXXJ z8*XG|2*RJ}IKKI~$zBSPnT=`F{d-71*J{-7&xz1+dwys-nuQ54Ls_Vkmwq@y)>SFz zR`N{)2`H_QYaBP3QoH#E$DfuRnn1>xJ^#IHha1joO}INC2|1onGo$pd%DaCwNXYj6 zdBoD;1JbSH&i$F;+dm#n5D#^E>-Ty8`3vv#^APy zL;05w`<1_*iQdI1G1V=fY#rJU#^G={!V6Zbx140|OU zzae*VBRS9T5^KKQTBYMIDxaD6GD-?3yRjZ>S(8n8Tzw*DGz?Ek_?GP}yZ}NpK@B+G zf%toq8xbXXRk-Nb*Ntc^@X237WAAb$aEjJPrE!r5%;a)sVdiT z@@D6}?ZaPb+$M*@{Mz2mbMa#0arWqEvUP(!SSMu_vrrjmtqyCO4|#JV=r>r*KVttd zQM2kJC(miM=YnDht3oo2yLfXHSGyfs9s;{~wKRTA*^s%aj6tVMxwpct^fDC&TktuO zUx}H`B$dsi#x*_O&R*yz3?r}R?^g|SdcFL^^6oZ0$C*#jL3%Iy^wB{~rJH(|XG?l7 zvdOgiv`dEoj%AH6v?YyWMg`hJshr2s!ao%MwKCaKkq>E?7#VgQxYA&;1HD7p@SI4H z_JZBcoBAX`wzuEAC3E5icax9ts+fYBRh+k-_{=pJ3UjsHT-@Ju8*<*4;?He1@AB1f zFKy@P`xbj*zN;nuUHgT&;-BithcmHpz5J)-1*CWWd;E{nvaP>!w&SgKQ)ev5j}ovKMT-Jc6t^a&D1-jvQrm*y?H( zhk^r%`q~iN7n(zBTm=97noKqMdBLe%?Gmi+M?P=|LHd!N+Okz@P)a;AGatQ88)kzT z(}t>;!ctVN6nr{)N7iKXO1|KOH=(YMuW%QD$&U!IL(^LE3i_MKPaCxR!3gRS6c9i7 zsT_!Ms89LUQTDSdSqI8(t`;5Btg;Amp|z@^Rx>Cpk}0{RYO-D|q=cq9WPJQ4G2E1= ze`8iB-9Gx2oY56+Mq`82P#_FDE}9(VB0^p-V)b_$xw0Jg#$o2e8=Q^g2^Kw14u>U3 zwRrFwIx^N$G-#fk{#f9gOV8wKRD!%JOOAA7rS7&UFF|ox zdAp{sV%^k3HVS8eMoYcG=054#F3YFNB-5$8_197QS`c)w+D4?Q>7#-gNj-$?>DP|W zU!dj4A~eI9c`n1{D{*C;o&DYSO2wbj)z;<~tK;nhE#GQ(#R_%l3=FqRggRokpg zG{hX$^iLA_Gq1ZZy=947qfXp%X&6!Whf}BrS{3df%c+O*9at^37)SqikmM<$`?p}D zD#gk&VkdbXG*o`5PiAYhOg%?GX28}xTlbM+` zIWf7^vnRYs-`tPg*M~6a;~`|2%oJMuz>C_POFA1%O6p>pJ4AFg)k%x)zJaWX&@x1&$!K7&ckWy#&+mljWkS5ykFgsq^Qa#8Dsd;9DVvLGh3A z*ysavyIUm;$XzO9;V>3e7c18V)ag|mOUsxyH{CZEic#RZG0iXOQAfRVkfPHg&vUcj z2VVtQa&$#OxG)Snb;PsePLBbe1Pp%vbB|8GD#e>UrRSPuOjJ~QJ#A+77;)29lzV5A zM36z``ZNwY*h}$pv9n_bZ5GxE(GDSsaTgWX(U0E=j-Gt%|Ff6(UL)+jA!V6tj262&Kod*0|L zW4-r|0t!>4h%pW?nUA*9Vz){sgzZt+=wk8zM+?9LnvtH!ffYOUr0mSkK><62gv9ygbmz!23HETLq0K?9Djp1qmsDKdzb{zR?P|_to?5L z`Nbn%^07*Rf0X0p^|LOO^2|q49IOIVI+;Cq6=7!mz`=7}(H0s0K{f9V>M?Rg{aN2A zw$$eJF@bX&ErS6ws`oZt@`XbE(R(Nmja0ZbfmOxjYLtnv74h-ZTDKX5dBV<}!l>N> zF=R7%r#gq-YAKsU-^K7pm6t2zJS-?KLi$k7@o%V23~%Ut(>J`o5`M2_nQAQ{k>i-0 zVy(~?eindhH)*Rjxo%F?)1OYc#=$-g=-aoyY3cnO!Nnk4u}K+ z*h)7Yn7+y#gEJywp3JvMe?`~hQtC%lewOx6uA31TTPiHfU`g-j+{|B76XlHBpfGcr zEAOTktrW_`nU|3>jEN`a&#rRP$I@!??Y`h-J*cjrcs6&|;$-3O$pxa)VbOcDv2H{o zkER^3E&lakAwazHuz}ALF!oIWi~0dJVZAWUWTs=&vlvLAbj4AwQ`|J@Dx9aY-0@@D z;u|Dy`~3IrX^DoGpZ#@2*E>&^8V9*{!G;}UF4RriLb^_U7nj96v|^aJ1*2cH;dFZr z70@7{zRmYN%sx1`iolqKrencu3UV`BY|CViJfrwTo55}bKjwczA#`Dhg|zv4bOW)GGpkqDk;w=AMh1T+|~}s4ZLWCDCp4#``mx-5*mJ!N(wrjPzhfN6aDb; zD5B+EyZ=4LW(SAK@mJkwauTXZo=KZe=8*U^C10D3wZ)^iUVcxq4Avi@#+u0sl`4b$ zNQRXc`@LB_oKb|zoO6&_qhfF2BPTQYPo6r+BIhq+tQ#S#Dfl?hB-212E zd3AjUlUBOB6zX_pY{d>eoHcefMo358_g~vI`$!LC7F(>132SgiquF&)X=B2^_>GhZ ztVjRVB+e2ai7%9T=P|hD$0j6uKd^-z=F^{s12atZ%;6ht6>i0)uM}VrPE7MtgymwK zYojNlQT48fNhNGyVqg>8+8cAU*p+5ePAT0c`V8SVPa1!#6g4}K&4?%{X5FX6p_lN( zHA=!bnLT`%xB7L1s2sn&Bt<(MzEVY;HEOHa*~ zzjVz3e0r@HYO8>dlC@mL%@3+xKMqp*09kfKKX0wS>y1A zcy%q6<^Hf2bR?X)_eP0z9LGULp~euoDp(?W2k-WYsArE}k5EQNL)zH}_PuQCP8Ij> zpVpYC@Y&nW0c>AKUnn14UAxRJQkojB5H!bS?HP<~Q6Pgb_+KrMG@Bg>47Tk`KE#=O_)jz9sdl$_wW4e#28}po}^z6(=pWMVz-|@nl=OlpA|lxNpxbbTOe^1HDs(>B^Eu`R3dE0=&u}2) zKEn76%&P{evNKhoKDexAVVSIH1L9B#9g4ucbaeXAKC$6o#MOjmUrHND%ie6H4mo;@ zo{5s*IlS-HN>3B&g!!@9gag&pnuBkDQpLTiWoH=(A}vMAxUg2MCVRHSJC%UHfvgT} zu-mJ846ILy?!^7a)fW-VsF=(XJ za^IL(%}@?%^6!LqXM;THmS9v<(WRc0w8Ms~IYcF1&A|3ndw7O0aqs!Lc5qugIW;Cy zg=iagnQMJrJz=_p1lvguioSFm;smY6l546J-+|Wv1F!h&C$D8D=py6G-gv`Ug{LRY z`Rn}L=?Lda`;UkC-mYOo9s1Q^_ulb|i9@cS^#aKvSy_NkXa-gEyCLwyBnVk->x#f{?6bqBA| z^SNz=>jwM5w`5#v)<(}4@h_$@toZxtQ>NM;NpSD8v>P#w!jsAVHPb8Zxn}+T|K(!B zbjT4R_o>WKdWfYe?UWXnJa79svUMn9texW2|aiC z6n?$AjuAHgXGTAp(VBK&OZ}KfVe6w6E2&4%h2$8vh!}_*(_Lc-3l6vA*=`@r0ubx& z!rW}J`9WUeS~>ro-z1B8iqd7j(*fo@`ZE6%OqZwLmV1&|=@x#tYZ_@Pg1R&WzJkQ= zWn9%rxF_9di>~6?^l7;xP#gw1)_VoFTgznnuv_jD*#Wk2w49P1ctJ3(HgF^~?IUuM zGY3MtbCgy^G+|8AHJ>r~$sMyq5ARlCnNMJ!P0ocp)=&6hD}%M-=XDcm>L;5|bFJNq zP?I5sU5JLbYWfeQkPd=kFf*Ko?J0y`RMYW8;6b!=u85+;#++3? z@ZEcEZ!VN<~0oO@~sYw^?o{3ZF{bA`|cA~+ja>Z zK#V(eCJpJe1&sM1hhQMQEz4|8Mpqn_Y|4uWV_Dzo*FQ#>62&2piD7nr&sL26E8hbb z!hO#?s(y`8|MepXwzLY2b z?@{2w#Chm#!6z^O1vUPICMW_`&0UKgjk^CmTCxw6bSu|sp8y})p+H2w)N8tw{XO~^ zKZgvN89R02WBGJkTk_Fg$%uN-lO!IF`}~yF7hBnI+d1TY1w8ot7l2Ls;0r*M@b|T1 zpo_qujc>bMlqQo+N8?v5dPL-Z`nBx76%}TU=Q5*s3Gi8(pV6t+27uPlWDa#~9Ccln zq&I3G;zKtak=t6PKIWp=VEogw&La5PZBmXBAif=HWx6B}w44?3WuK%SOpD5K z2%7Zcit71lnv_N(`aQ+z579P+F8let_(p%j^}XM?9HOq?mawV720|T+07TR(HI3l86r43New%XSIq2zW@qtj*FJXgL2#_iJ*)>!|H>| zQpYcvzm_vQ9Q>V?K)v52)Ezi%o8cRvGG^`?E1SQpBs&GNW_P+EH9E};2JhDt8y{P^a3{OwoQ zCnnqF#@>hc<$FM6dZ)BFE1tIgZyrg+Xax-!RBX3uIg_;hvdWqddEVWDNH(XYpHJLR zJ33p-g`L3d(d=xGEWewjqeVdK;l7n@wB%WnTVzW450`t_M}3}^ zx!h#vz`t+K;|DI)5KS>F0(h3<1_WXA|2Mm-$&h#^Y}D z3~-Rr@z_bi+NRS(3AF=A*N~$+4m+C>^vO02D{9TIC+UjFDIeuWw#aEhp`=!)dkd3z2Z#Tmz- zE6TPW{|@oJfBF&!coteNyVI)E-0bi_Un`da3ao0{M>cP`4rh$OO-8jLjOuxUJfGrD zkGFYvWfvSd949asTx3!1?T@lEnyFnXFRHR1U%8JWu5?)=1fM(sMb|OIMbRU*ay8lo zV734ypX`*wZ=(6lhn`87mDpwxpTT$L|8I)5%;eha5IE=^8 zOKPqFpS8Hqh1|%mUD;;*wB<~1eLsNpdl|q8c_r*Fl zQi0awcUASzgcLJwTyDMTrJM*#!6zG?FKdxXYIjj)iGCR z`-p#661VO2_J~bwv;caKquzPP>Y(ywi9%BID!D2Vv42dhTSxWwbXCR5azzPd$GgCC zk5(5bQO-xb{L*2SPSJJMEUO6H>Y%{FX8V?EJzrVBIE0JO?OO48GFPchw4yVM67`jH zs!ny&z+`Kj|1}X1QkAlruR2*Q6b$@ydYr-Ov<(pGVuRr@x#0KawC!*QlROjJ-`p!j z9$$0Gl$Sp*)>)G`;#TOjEjD4!RA;Y^4bN0W6eU=@9{-(0mjl!3HlsC809@fM@RvPU z=*9Z3K+$wI^fnm9WGW`Rtbyu|@Ne~L1KM_BAi$EYT0d2Gcv6l|3u_XAZgKJ|Lc1v* zfv&6>HVl4;l8s5bZc*oh;1-*8@<6h7I3M)J?~NW&u_zRuR3XPic*WgxDHW4lnK)fn znBj;Qn^~!A!%_b3wl`*3z(=B^O7fZ&*N45o-Bw+^3TL~cJx)B29yZzx4kn0qutU46 zPzY$5E~lF1W7@UxeQg`KzsNhZij%;n$xw(9*sXhoeSSCH-p^>c z*%~+#_$YM6>0+fJzWA;p-zK%<^Qq)x6T{ePbGbyV*+c2XyQA8@WjOFH`oRR@tB$jD zHgPU(BcKi&+~IYGyD78eAioW~#OtbomKI~)(ik8N{a9c+oIHtQvjjYc9MRwVI20!3 zj^9GJw@O3!N-J0SfaeWT;M!sCX)T+;hvlz@7eKGvo#F#Xzy9&x*F%Y;p%a5X0VG~HmHfjo*-S203qU}IwX}#C5rhF zq;+9VcF`HgGp*<4Id>=gpLA`%pnUT?llRYHXSlcBRW!~^Eq<`gYdkC*;067FPbuEGpf+&JdZcT=O$^b$=a>e>{t14D=BrLdB`&=OY8NKL3N1ur$-(xsuJHW^{(f&rz8rqyAZKY z+{=%(<;H7XzOY(PYYkmw4NpiT`pr{?8!v}XZVE)tL21$uL&aI*yjRi__ce9_)_m#P zWAdpCgbFoD5;$wAfJ}bRYYt%C2Qb<3OUyVGHZgS^{-D#9g5{dG$~a|A+5l#jjy5TR z2%Db!Mz8=mv46bGyt-DM6*`3j{3nF3Us$YWDE>P1;|2-?GQbM)*gC-1!ZON|KF`Fk z{+7@70326W_&g5gBQQg3@=%KmVt8-uU2@vNM6Nz2T>&5I+TzCz02-pRkDSjw#H{lt zE)UqMrrmUrhe`Mwcz6}!Y`^_JoDXeb1p7tJ z+=tW3nWN@D4(U>%mO{9%MJ}Ra8E!HK+kECLpQr229Qbze7{6< zYHJd}FA<=|f&_o%0{nIb@G}TFZvP7Sf4;KNHYL$fc9?`>gsxxXdn%0FPwl+H^W&ib zl3_rO!5JMB}e$6i+H8QT(M*Du2dOC=kJwZ*x`dw;$O zLHnywK>_{4Mb=()87|k)0XK7S0j;-yn9DLNC>!#q8XwXJ{2%J}jPir}!2&b1Z5ylK z>*a8d7sqbuFIye!p~R=F()!LsYm00*_c*)dMgsSTonK>o_>CFvd24XL%K`Q{$d6O! zC(B^J@gj)8Vu=mfb%At3knx!LffLS_5d+W9`|ry&`{LJ;PN9C*ke+${y}ex9@YlnQ zp1`w?ar~Z3)W2`9XWs=Z9V;oi0g_6XnM{4Atl{9Lxn~7S*MbHVgS?1pd8)gExl#kb z>Kfh&ZY)3vrPu+ad<(-!4%e_sc3BlhwKuetnF0hAupz4qx8JkuwDqjQ>S zCAHFSHHcz)+WvT&BOHPdo#==Z@IKcA@M%B+0#>0_d3O7L4XU_}X_eIQwPM~+T3Q53 zJ{_}S&Kde(){mtT+!JQ|TB*n!K$b$Ss98iWpOo@L-fes8#N>Q$cx|`QnqCJZUZN)Q z*-eqb{32ZBG-5Ri>AI2gwGaW>#`RA_m%OsD(al~)pJCT&v1DgVEMEhO&$FhabzOT=B-`lS_3n=B;7A^7(fRp}Op@Ot;lEj-r?1=cZ($T7b9bDFFbhGD#COY1F_#%t zLvGz{Er4D_0H86=qgV{WxgIW44P0MwyGm$#@oa?u6#I)f=5s)j#|aGQk8|E@1z)gr zHGCpz$m5J5AhO^jlS=U#h}dl$9zpH2J@CY$gJX0QhBkjVOASq+oi-4N_(?F6OHg0| z+EmzH30d)vJPx_g zPl_`!Ai0l`^x(Ufe;dCfU6Cm~KoMypDK47zhMp7H$St_7pr78I;zA~#1P>-=e|a#z zee(nlMxv0dLT}SxTmD@ZpAAdz!?>{x0}#+x(qMO;3MlwFXH^CP4enS9j4N_7jpcVL zPCGBgzW4#-Nw8)Mc)Xs_f|62V%Y6OjhCgHoQ?=O_Oi;0^iX?}g1V@waE5!mel}wT@ zm@$S`;CDF$5dzgrm2oSUs`2$okZu^p&E$IM1AJjKJt2PN!qqp8m3t2v!ylVwjy@f zgU0%^4>IA&{E%%T-$i#X{5y9*yk%)wQLCZkRDTV*tLpH<(gr(Xsk|4OC<<>dD@LECP${~?sP`zrNv>+w<(+L*5*5$K#}{OVQMS<6eyXU zM$-EuL%ngFD~6xk%&)TSVSGrUEzn=xG6wo^LezE5aTP<{;?6+&gwKx=`{4v(owP*T z2|QkOmCtW&J{e*;O822dw;T|2r@-xya*Su<4eut{RW=P zELWa4%f$%>aIn9=PYX&U;L5k}7<>`HHan8$(IRUvUd3nC#Pj<$wwYwheEQ*Vocz(} zrT@V3q6M`;Z`A7WgO;?ItTxGtR`AVot+q1f!Hz?omg+)*jZf3wQOEYVtTqS#q=~7i zqs-`wW4H8{$?`Snlx{V%@doUkJo0FHbrVFu_+f{K;_D=;Q%VII(Um?9qcY#CER1lL zfDSjSs$aVibT52|48NuVe1lGo;-9;tOIDFzTm0!X_7ZjFW8#g308O*2;q5P%ddfi8 z&~G+p-yRalc|;@8f)!JuplXVmHQ&du=F&z2Zf|}~jKePh@=VB2mjrnSA|FIhHq~(& zPwE4Fz3(ZkvS)G7Dnp^S(c|9_24)nXLZkDg{Wg~ZIAtl+uNmM!WD*uHlQY`O%n4A* z)kNztC7!+f`QgQY138@~WEWZU)1(M``${;biskXeQ8ddarwLH10?puPsRSwb1}HpzSoemP z>^ds9_B4tMm6%)l$k51uQhp-Lfj1zKk{`mncq=G2y-S~fP_`g4MM+;w4Rie3U47Xb zr~8qXq-M=He}&#}6^mE8et%-(BRNnzYR_o5(dP6hmmrWLGTp^_(_aM58I%f|-^5#$ z)%ckG?T`w3rBL{eT>*ED>Rl(d`Ya-!Q&|{E?Rr8Ga!VB;Aj;fVpC1&v^GnU@S44Kk zSHL32ag1}Xv6Enq#)LZ!DW|VD@LjIOFKo-%J(Vppv*vfKWXzDozhyKmp%b#&lF*O} zM9+oG%GH5XO7t)%7jnE@pJBbWAu+(tr{D&z~B9F{kBAFB=gTe*s z)xQ$uGGS9NMuneaP5%00CYT5O84_y5^9fw98YpP(EJWnf2zsrM`_7i$*{agZVF!^k zFis*8D3WPU3%b%E;rKB-Y~75C_3f?qcjyCz>aZ~BycsTIZni@oRVJ&C~SELq=TngVs zDaBQeffT=o8KhrSbi}NuOe+Vgs4v?!a#|PSH>$nMlE?RO9Xy=5&?>yOSW_!DZ49B` zN;E3HVm|UHIvg&O)kbp`N@X|mxg$D#i7+;Gl3#V&QzuK!5!{BNZ_>L4w}Yem3HIch zPH690gRim2w{wqXl{FLbf!BnotbpTus$kLboncgKJ z5vWWR5!XB}m@Dt)MkBTISO-U}-j;^7i^GLIe3ivVzAycC?y=dyvy~;`7=0wT?oIL# z!~dgy^T8P%(L8?F6Ok7U#RC-J@SZ+zxJjNK^i!@xN_3w%wtrtFjmxt&ENI-xWr|d! z8`}MB_q*lu?|xXdqcC#Vs;o{aSc{pq>ofW>-9SdRV9l2gndc>TZR3U=Z$+v=XqE9U zt{t5uTcvC=2~s{^nw=mlTvQJ#_%H0=n{Y2ZYv>?-=5^gTZHmQyx73}SHf|ws$~|Wj zuwhFSo*ng#Rm5bMVtNZ|DnXrmneU;GJKC@dg~1%9NT*H42*^17)q}uiJ*7Xe;saGp zFV4%Y_DME%?};j;QWJgE%v%LWc@Sa>8!S*^RTe#B#+;Bn+M&f;XR|Gwksa zis_tpZ>tWOu`wm~+RM^xO35DhuOk#5?Pg@6|EdfMp?I9f($&lp=NC-71O`8L&F~Au zTql+{NVRM$gD9TdSp`NcE7Q<;a_PmPOE4D|{~yZUI;f6j3-=BhToXLFh2RhfZX0)Z z2yQ`wySux)1q<%(?i$?P-QgQ@&bjA3RbSnz``3nDGd(?fx@UUUv!36|`J>2IC9NyB zK6bAy@qk0QMa~QqYRPu5HwsGe<<;1iHvY_TC;+$5nn%{?>{HAmu3Q1aqJ;+jZZ2!} z6*PT3pOHWQjpxzae_R)!F9iFWQdXJ@W#Csj++5~X2xp?=JtK-ZZkFgYo!UM-N4C^h zmPz`6!Y`?N!K`zB`Ck2q=HQg6+$?iFY@$K0YCa3XrlfkTwRi!xJO6CK&E(jO;Kahi zQ1xs$8cIl7HJ%##J!;T&3F-D+cQnlEG+DQR8;>n}knUVQHm&!lU?34SLXO?iom#HD*@ zL^GM}-xpr8iHEQt@BT9~3c5&X?&JQSFlMskZW$5Ut=zt4yALCWlx)SDA_Qi3m4RID zajqLv?;$3b{H2oU68G!0%c7{&YSoxo{-91m;1lF@@PCb4vKRf}F>Iq}Q2UVWZWY|R z$Ar>(}+51C%HB_{<&qxEKk4smi<20 zDl4A#X0@l%Dd0)(E(j^3vE7Xejz{@P)oiZ?gUp!5Lm})#DfXsai;(8m4oRF1_fBJR zhM621={(fyIq$1;KFG-_k26+5LO+d=R7iEl9B{CnbeS(7`7kMp;r z(HF3#ArFO<+70+Ic%`t|fVL@*$7Z#q)5Abwv$2^cln>R9e^a!#BV!A(C= z+>tN0D4Lhiu8??M5MGqV;;K2(nPiX`eaXp*Ekqd)OKe1+Am0;17hWAY_!~{V3dRJ% zrXd4NjWcmSkn^k9Nsj!lC#XdtwrPSYI{j4hWAqa<{v|pb$r)n~9ZhLhQMcr)udrj4 z_*9Sx)IU8u^{vM^T}xEO?w2xn0{mkt-th;KC$g_;A3`xoxMe4zltAnBv0~17WzT|L z8=S-AFLBHX8%v+W1ij-|A9vRZ8De1WF}C^X;(4}vttr*e>cc~keAdi;5-y$m;bHB; zp0^8uyyQ~c6YZIX5xSA{Y2IP=tW`yyCumKoi%E=t_06{uRk@)CycCmU&oYJhwT~i) zMncyV4KWE@QUV~{m{lX%p9_6HtQJJ9$5Ra|2Jw9oDD~pZ0OVq=N;OQ!eCZ3$jph|p zgiv~8w!yB?d&su)k7O~_C|KX1yPW4sl)TyFDL%DQZZ7kSuVIB-|CH>|alSyYH@f_nZ6WcOo@lk)2+GU|GbeAVtBM zQg~(4j`n7WE3ni6uP0wneQLhP;8Yt@xL$Ky8N?=2O)D89ZsgJYMAuAzNG#3_G35Di zd*!SXK5K{dfK@F!uDlaaY%-})=);UvGk?te+gbGY<2wz>cbtiurFZsD|Lf9Q;%k?< zY?#7OLjULYRBvvIFN!vcBmaY?K~3uqXq zsafs!A5YC+fyztl%}60Ovt(cOZ*lAI#}*QBIGbNICFKA7R)Go-qLhkuYE%CDRQ^+Y z)ZtBZ;4s$#%p(6e7;x5dfIFyK?rYt0$v+jY1|Q&XOD6EeLI3HpL#C8jqT#Z#^Qp_w}q- zrQnZWp0c`6t4*ff!f-)ugBvOu7&L06Q@^Am2&5W$Y<7l0n%UR7E`S~s#M!zsO_wyB z{8bzX`B4I8v3yE28W^MW&o_D)0T^R9H!fZZqk)*0-oE|I^R4#%ZidGsSriZ%moE@t zT*te`PEagXYH-<|3*p&0-zAFJ?A#(%&uZ4`@@EU(a0{$#U(nt?ZF{9v;DnImB*1#$ zoMuXLJ@3JstpBNZ4~P`eX;RKdfM$^Zfy_CcmP7OW^~tiCX7U>GE-n3l(rCg6o6V;YvK zBZ+mzv8%?dNZsJ*55Nc2Sp5cIGWELyQBSyfZIl-}@5U}ax+TQjd>yj6Z+p53DFJwm zo!?RiG6f921un`Chc_j#g)YFpME$f6}lE?Q+s!0ioFulN>$$7!d3r zivmUMox>vHpyslp=dJq0@=)E@{V*X%#Hsio0(MZ3W#>vY1z}aPaxt|Wv!<4&3uL>} z1ekgmdX`Nz!r6AP*zUJt3_5*b{Vp)<-qEN&-W&@Cm49#`FGdb7hQDS5>OL6&0Z-{8 zmt!QH9zZS|h*!7RH>{j+&dO`riWUdKMo#_70&CjOPsuf%+0yizXT{+$JW7JGK%EXV z1Bz5~`Bi3iC=eeQ-malyG6R*O?34AXePpwi3OIq{JJ}HRncK6l-W-B1Z-^RLiT+DK z*%zwHTUMGRFbXVBo)-BtoP=1b2vtJk>%h7t^|6=tjwuUa4 zc`SsUUSdg#Mm8@~NeHlBvw+H%V(pML#dDp}sfR+3#J3{skjIG03J;pH7eJ+<#ur(I z#=ZMx`^AxK17@Llm}hU7!H?L0)Ob`mL@PB_5HqV$7(YYu9wpOq57PSg6=M3A>T6D; zkDB93Kz+ucJm(b7#oy|6@j%?XSfMON+>gQtvq7N?tq9%_VuqbetN&aVDA|lGE1AGC zJcNJo5wjnhd;+)`cS|?8rS*K13vS>L6N@I7`gs;BFBL^59uK@4tfmw9Bop{E^D+}M z6S!T;f-$i|z+JC8AO2qUD^e~yfiZs*u{5zNAAmasTt3qbI|h5k$-8`o{&LfFc+yAU zyzpS9S#&bBB*;g3US0PW>nuCDvU$OrIO?@iopzEg{^&)Josg+E{s^DQM;Q+wa90WE zelP~Zg_QrCAFGgWAVLp{3qp$VlHkvH`jfKGUQNq6P!K{+8 z-2s@=32*Z)ahf-q2~~vbc0NxWGXXE#by`-~AX?F)`CQ10o+9N=5Z>`>Lim$OPc;B0 zo9j0NqS0K(H(7$c3QCJ#Ck?ixxsY_9{t;l)&P(MveVDwHry0ZfWawCK@Kl_4-j}Y zGdKZMWwaD05Op)Z#gmD!HB_4!9Reo(Cz^#BE_R~q)d$!d>4F6=*+YO`bhCgpxtY8;X{)+NnR~W1*UD47cnjs8ZzMfa|g&%p|J`+Uk3^zO5<%dRwwoO zYLhEW`&4e8!ku-w?E?aoJuOzXo`!NL z#(l^v#2n6G*bUgiEg(+>Dfe(GSN~%DI+c*&w1d5_DYTkRBM++&&x+p5elY5>ikZ|b zM>_`7w_m1}SYSi9)YiwyjUO3*qvIU{PNe0q5Om9}2XP8VK30F2b(BdkF_wcad-lC# ztwqo+vD`%`#oeI;3KQm;gQ~fXGUg_~bpIi3tS=Wlp=gje&OZ=|fP2X#?M*kyHOIYn z)3-8O3*z?G_jVjVp8(HC)B0eHJhPNUCAzSQh{J4!Oy(oI`Dz9;XJVgXRp)G~boOEHeKtj+!z~tHk_|EY3LE{wFjAXsEov+F3K&Fp_uaso- zM3+TMKpLMLkWphp`ksdR7y}bp<16}*Ag1OPjNX&$&s*%hX}d0+1as^)zg32X{vW;_ zsbEP7CCNeCzzPQA>j*_~CLO=$<}2_B2cX5#0vW>!uB$Tgbp`PLyb_F2pX~p1v{)5L zSF(sILqA7gy32NodnQ!gvThq}L0JdSCSbxQdyvb$`1O`Gwv&=;TrF~()OTI0Kft+t zODZ@N*}&VM=IS+Rn=#-g>=|%PEW}0kbGw-r2I^}Q{c7-sEP52)K&wXNj=0(eo&oik z-0>gin!BB{3L9qf)(r-#`u_;v_ma~K#SDKFa5@m$e1O?Zq4+R8KPR}1t>Ih>*0J4F zR{H)VT7vuG`fxY>qtR^i5@jy8i#}Zn7e`x;yTyUS(m1@tJ%a-K3erj z^PR~TNbinZEbBc#maNl4+z5{Dt<(Xg7_fzyMq%x{rC*I6fsIGs2uyoftgbqpdJ#)# zC=n86JS`c$WPZ{d`1!#>LB}w`xM>i^MdGc_iFD;ofB7mh2Ksb}JZGR=2Rt?4W^t;u z?#3s}$`>5Hw!U+D`SQ_k&iR%5(7Ad3WK>-}Gq~3#XS#|5sI3yyHN!e{RYub5ErCxw zE=FJ!!couXm<|pO$fAL~TGFNS9* zrBu!?`>OQtF98ViPgDaW8w|0~638RRh~O~FKd@vR_AkEJ20t0vo-wX^kk{)lV~q)9 z-J)c`d@DESav>B%C}JY*_ac#OM;&B1baJtdn`x!VAfjwu2p5E7PamwmWhg%F#`@Oh z&Yz=RJ6#s$-$y13`26B$FaMSyMAmT9jFu?jZY6e?%7gaeE{4LtwgE*T`}BH-8@Byr zZ>r~UTC{&X>&r}JDN@>Lf)pcd1JYor#T}a$k$WZ|nBGifgFJgXo3>~gh(z>kdHudn zT~I`OD-y{t%It;rt346f!e|6)sGS_*{<|$Yil^zI*?Z{+P&MECv3`P99xdBWq{7+R zYxuM+0rq|Uv#j77)SiHt#zW7;szBEbhmsiiEtfN1<^8A&AG<7z3g4H!kTitbwcF4= z(zUbOvBgJH=*tdE#uXc7>s?on9X*mP-KT1jx=Bo@*Y>5?b;~$SYzAGB$omI`x^)t< zq$^y|fGNzY=Baiu>5R@$Q(!>~NTf#P%qZh<~&v{ViE zNopfaz0IBX7t~;l+t!i0JQDVMzqb|f*j$kX$MD-mf)zc^H+K-mP8YxgCMu7DBIv4T!M|h=mI@!mQbXY}ezmq#0H{+h{d3 zlD#0_`^TmVPhO^CC&V5#*c55nZvOUoX_T=(mI=#m8vP^TE(RiTx`W{9J5MLNb73+v zAPa5jaD*GwN8q!aAdo8#?poQ+(WkTR#Wt!hTN#UH>kgsa(MY*NvTqg;6MEi8x#Sv4 zeF>(QKHFv3NR9AY!_s-#x_6p@5);Av`eGK?I_!#dgxgHfo$N_A7Lo{~`9t_*ecsEU zq+*3a?zl=kCwD1huxjjSN3At`em%TLh$NUC%v{eM#!%!FXt@X}471g$0ad91$Rhlu z{#7`o)Fy`RHv634W=nGaA-W+BGZ~uBnENjLGx!wj!qE2*)kp_YIbOZsk_u9Ol@qp^ zPW<%hjs*34oT7cE(Ta50KB0SSI8&SvwSLYfgi5w7CmgLIiH7$AOdV7#s^_h#xyTPA zmEcIpKkLH_lV`Z|KUepzC8P6^;7of%U$*;>Qt><>BTCu(wR#y2o0&UtC)P%Xx%Q^| z^+JwdEx=vCC1;I8IxXD~i+8IwA(!(I%ees&$9gFijU;Mp<(Ws zFkDsH_fbQ3-5o#58sS^)rAYqBEcoQbaH=rQjOZWw`P|oCgex{sC|U;kx(kFGo4GTY z(TB7C7A9ODp?GzDzRb*UmMEknH!ZWY<|Y7@e4OY`a(`6w}`eT7G!%pQ9M_2OF1G2F+^`vEAQetkQo?6jkT)tvbo;bC#p zu!oCN`lJgSedufFDzZB#CQwrSeHagp#>IqRqIj_3jQAPboy|l>dNFAy-9vikQ;V%m zsjL0LsQ595oBfG6IgKGNIg12ZA~LzFIv&841AR4(YGyFvrFNW1sy^%MpqPd??`G~@8wH6y9Kk`nGej8n zYEGpq`V6IuC5{z|Rd9x?=P5uh%JA-NQjhT#9IW%I*Ozy>Wi`7k+$4&5{v))`6Zx~v zrs`z?nYoZx_gD#pJO`uD9g@~6l!C?#^;srQEAXy@q9%5|KbI_uY1n6omlfHk7 z)rtr9261wn_3TlPA%BJPi(~4MG?YBqGo$Y&_RK8K=Jnw!cTMt(5dou ziEt!2PB7jP{?b3`i-0}01y+;mKK2a)ZSp=EVpNS|lP%U(&$+;MXzAxf}p z>1|@|j2FVGPeHdr0nT!lvwB8dMV!4g2I;>_;TGa9oe{cggq8Y~sE_TCT_wCVvEP z190#x4pw-}7LwCf4sk zBu3vMNueyP#nT#}8>hTNL>TiO!t96NN)T=*N)S0ulQemY;&LY0j^CZ{QnZ1b&O-}v zJN3I&qW8ET81?;GE<;sf(Nw_5jR$>XhnkHdGu9vz3TRuARK7S`wnOM-1vy0;B_?!2 z4hlVl!oM_}A>F^jtu`?ZGe$r5Q-K;;t2o&BYV~~+Qxyeu_$V?TVFV1oZD$u=cW|SKA7C7PL6I#{2PFuAP={}0A)*jXkI>^n zQqZ2?Wl8rrOB;XD!}-HM{PQ}K$0=IqRR`?-`OPVmdY6;DL-s{OZ>qOaf*?sQ(mMK( z8s~b$<$DI9@hc{y_kMmzcD#C`>?K($e+ZZOhP)h1zE8As0l8+MPr|gCCoQaQ5@qon zzYB(ZC4fGZR|pS5L^bFc8R`z%@k{XHX)D^wnnJC*JQKy07$fWkg<}lBCrc`oBS32i zcl8hT@M2GM3-0zjCw3P)NGUyZJSBeHKdY#wzcc%)Y>o(l2kB3f=GZ_u4OI67caDK| zgjyUjC1CpYMHogzY2)-dBR3#7i;Q1jn@q(48X1}i`qtQM{L;E=`%|K^{SI@ztG% zia!^(I?mULm!kT{)$~pR56!CI9@rs~z1vCs^Pz%HVp8F2r|J@%Hr$)@w3ol$uW$L)R44Ep~Vc_V``BKH@o?h=Oe3ltagIntdwiFv zu{5@WErRTNBTY}^CTeD4EabG~W_{9k7M1b-)0FamSOB68)39N-k%5f<=Nhu{yqPE; zP^j;W32uAPwCP?4IC^Z>G_zLA&q6Q`dR6*3I{qMwZgS~Mct%$28Oi!##2;>raP)yg z1X&R5dSjiZIfO$&VvsyQ>dDHWqNJrWC+?_D=j`ie^>IkE(@_fiiSwzB)IaF>CX4`e zyv;clK$DJQwYJQg1mf7cY_97t>go(*h+yc2AB(#!s273#q@l|pmq$c@J~LYBbj@6- zP#kl`&eeP|ifm=!;gs*nVG?(>ucmInS*7XzVO=TB_Cmidci>R$%==P~iC6g1e%ns9 zVI(5%GdlM|q$7lk#SrDuZ56m-wvMOXcLvltEH4pWN^4?jIIKG#^;6KUk5bGn41c10 zmL(HLd8CLE7M1E5FJ6+ZE^IP?X-3`X{1LV{VIdkwt_2nbx({}>Q3B@+nSKm zcY@T+hKSv8>?*5ZOnWASqU5+aJwHuOF=O;nj$f{d(9G%|O z9H*8_r!G<}6)M*w#jd*BpWJ9sEkZfwJ1E#soA2-?k*s5k?Cq!eE!b3gZ=jW+z8Yrz zSf@)Lk03NR7AI0iv7rtKtun6iK@0f*aE0j5eMgb!|6k&o9tUTPv;02|pv%(OVUcr&QsC z#BC7q!kBCf{mT#X`+#>l_QP89WP$g}IY+yp@vv1pD=K@2ZMF6RMCA@B?Sk(xv4>CV zvCmr9Fodk~=ORzil8>L|CP)PaFZr{oZ`ETo5QF1PxY9P$R24lf`{&xdDw4 z-i_)Cx!C8w=kviDa!mn1z+z~?kH%3&GXgUDy&R*ijC{b5FSgmXztOK0LuN(ipnvjh z;mE*^`PYHHAWNZk#Xf#cqxzVI--TpBco}aIKh|4j<(c+#Zfvslr-6w~adRw93}Y%= z9AQ=Cf4d2!vcYaI4_X$+tX$D>|{0{nbUoU zU!}<*ZBm1A%;RDRmg>a+TsSpI`o0Xd@Uy)EaegYm`-^A)HQ*mv#- zRX&S?3JE^^gZ!fcl0@Ur`zwIyS z{GaY2zKyG}UE|+CmVuWm|2rcO*O@Ak++FT}=UaGn1EWSVG(r=|aq!X&f7fKsdA^<@ z8Y3%0x!>>~!Z9HOFu>6_^_2g1A`*gqHu5k%Ii3vL&o?^!>OV;ns(|$uAXiiS0oV3} z4J6V``@qPeJsD|E`u}CC0|jKuiSCu&IqoD?rUOyRx%t7M|KAp|z^xs}8j+xw(<3Ls z#Mn`}8TthHQ8Px}DqjCRP|*M{I5QEa{lwdJ^P&fT?@&m#J?I}G(ZBa$c^p59(Luo1 z*E-GiKm8qe1G=)M{+;DOfA6BgAUN`3hBcc6kfJo3Zb6aj&P6ZIqPfxb-+?4Fe_pt^ z?fvlm6?=dK$l-c{aiPB_GO**SQ8%jj>x|A^dozHaC8`Gjmq11Yb#K15ak@l~#qgMI z%Tct|Q$=_$-YyLO7x911X1rOF zAL*;;aF2n`B2P}Q%l|1FTPXyjxy)jz!u`D=5yMoQXs9O7m0{hFf~~Sy{yT#t^6l-+<;}lu6_IZQ*P!!?;=f}@pWid%?20zqbwS$M(7Rvi@2rXZ z0E~ec?*X*G@ZZRA&({Iz(Ld78`2gAWUwdH!ZOjV}PXf?ZPohkiyNrvg4Cvs0O?2KH zRLZnx^&=#K%st|A!~Oj1#cyV+>BQrOQci_xS=DDI&*aisG?Ph+zcu;95@-~27mdT1 zAS>VUXO1!rOhQP(Q)Vq!Sw$Mjcg%nk5*gW9N zmw@(*F)X7oOL0i#TUAv^7mdOg|8aCY@Y7XRKKmcbWE{1pRMzHI&~GqXQ{r-$U3}DK z^Yxqn52+D2wciL{;2_|7fO(q>=3#(KKu`73MjwlT{srx&l!3eoXc!MYS+Y3cg$i!^ z7;pV{i5rAXkY{0g6jo#g*8#vv8pO$H8bo$bjSsF7g4lD^XfV9CO9y*=@sNvfege1&wzpAm~6Rw3~i(axZg z6xej``694&=W#un@KiMzd!rMcdi$uYN+ua}ICG#Bd$>wK?k2TgK6fB5@O4XAtGbNY zLffothKLT%uqj(S9ha24_6B!BEZJ5f>;}*3hdNoW%jx|NRBe0!k&FteNZ7Wqj^NmV zIm{LVc$`^m!p(b@*ofClar|ApeyJqmee1kjg`}f00gh{PVofA-D$6BK+DM&?0E6l! z3y9=_dIv)>W9fCPQ5wa@+*pZ6@z%U}Mhx(lfEs)Fl1J$WO6hcuF(R6{;o11x(+rg2 zZyZK%PNjEVM`IwrOj#vCfy{E^^3!$OG(dnD;^ud7qh>4^qUZvRaz8s zlH@xe)mp7p@9$%r*haG3PdAlgPBYqc<(6UWt<~_clr3tN;D>)@@j(64_*3`=BhqKd1%F1)@TFRT zrE~?Sp=l9yB=6WA(KpjSiHCMZ+f(gBgHpCW?EYk1VfBHk_RSHJ_N(3!nnR1lr78G1 z?&SqD+uhcUT$$k4`o!Cy%nggf zVGA+>Q$D%%UNwy9pvlu|O0E>ITT8mUv`#9yMlf}LOkLm`D~lX?=z@KZx2i;_TXl8+ za?|6Q5%##{syy>y&Qeh`Lr-K!LW8y~Vla`s3sKbF#N#_jp-f)rO`*Ypzm&KA?InfB z+^(YBgXyyS{g3n#wQ7cF^`;fXk7Gp_%PH&HAw@F$XKB(QZ z-dM8iMV8Z8>1j^3mo7F7-65UFBNlNPEk|?1Q~p+=-1UX^tee~RsNPC~q*-l)?bCZyPb{~)weEg4cbmsf z3Z#UG-)59fnxrUROs6L#ZSLp4n%y^V!`rXf8*452AB;7jLz`Cp9&C zW#Sl^NVtvVY1KaJcLV-wB1{Sxdt&Clk-lqN5wln4xRB=?*yeubsJBiS*7%~Qol;t# z5Koj~pPu@m=E5T@%O`%x`>iN#(P+JSWlV-^HKhcwUE3(J znL)OMP=eJIn#fl^OnaL#S`pAb#oA#Ir5d22Z22}gMYb#kj3PGQD@msk-2yPLj0 zlwh`)(nL@cw|p(XNuBXJ)+8+I@@e9%^`zu`_Lyfz%^wI4F0Av~48$H7#LBHdV@ni& zUwIc6=la}a_^bVztG2A>$;?7qgtN%Le*W1=>-p6AS%u(XWybOo4Q>t3OJVE4ZrcABc9f9Qiu$XR`=L0!zwD?J@ijVrlitZ%v90jJV+`MNm$_bUcB4M+j+0pX}K9M zc^9 zL^L4moS&dZWYcw#uHx6*w5JP`Khuawf;roM9RZZrP5vzeHr_Y;cRwbx;-f1XF1n$# z**o8VZhhMBu>Ldu*xz&;ny^dz+8dQXGI~rLk#;M%rQ|9(Ve9_XPseyOvwz~+5S&MX zLz96*?Bhs-)rYb{u782CiPXJPpheIiqd(6 z?sj}MUiP@84DzVJ<0>)&|A9?cDc}jk(e|$4vESuZ$_lg#+))QO9A5SYNy>7r@tLip zwI39rkICnnQ|%W!PE@&Edqw6eiAwnV>dR$#7dcOkleh~n3*Gh`D^7Ot;_3#WA_!>R zq)#cexw%Ad3Q{2TpM%;wK3}?vBd_56wA3bZIkuJr6+(hO(LDJ4a^Fb*vfED1!H@5N z{Mvp^BywvPyzWI&ZHGl3gA5tNZ39Gc3ZU(MIA6ymPHKb2Uc#q#MKe714;Zo+O&dj= z11T$|J?yq+!gfiFJTN9C_;>CZg8OPR(jB|NCM%>j5uPWOv97f#W)KuhRrywZkck(p zE?~uI%;yS>D4P86u00E?B0cY*YtB1dE;g_>EO929c_%O4c^#|U4{Ec=UyL%;qFAV5J|Iikny_iJT7V|k_`&oc7 zZ3dC-PW%gSvx;Uhjek8E;Yl?c3^(6z0~Z`eS;)|yX+H21)Ud67#;pq-iuSeU@jVDj z>1DI-zV(|@Vnf6-d<3D%$uqV|&AfODG4j!10re>tCittLLJ8va$D>b*^_}BQZMa~! z(?yFExt_y)K6&{ES|e{=!;nEGN~nhR!bv$X6{XcPQ(D}-MlX~P_`0qJoY~&A!Tm5jd?lda1Xu8QVd~b*H!vu zQj@A5w~o)e#VL(J|J`T2Z~qhqo(a6i3id4I_pvi=6F)bn5r#nGY1E!;Vm(8Q%Q_n$ z=#aTMxeW9njENQ-SPyCuw{xELOvNlewbN3oOwu~qdWL5eR>%vM|Nblpnm}sKU-$%V zz|7;}QqYE5?(?x$Pau<$cwEel?%XS-0B0bx`RCLvBfoOxQPTkEX(U9RgxjqKNAYLA zB9GVmQ+WI`&G;p{x+7Tvg_VxX5?LNOiOe8hmzDZ^7qW%+<`MQJkf6QOo5gD)*mOoDiLtf%d%gaWP`H(NU|on!(4I}gXjpoF=#34k?tN7 z#?(*ykJ-@$v&h}G&w$y|6P5)RoCq0p&nE7sYGUd&Y6PvU5|;z_54U?>OI=58AlP4+r=5YgK$iU zqw8H-iPjId?_&Y^fX z{{^3uP#X5?+R0}4l+o&`P&>N4$Ez{r8B8^r(L&+|?a3WkajeC2KY_q2{!0KW{oy?%eVe`PhF33Bygj-u z|5-o8FV~II+i4MV{p;wk(K$MbN3Y(_IOp=3XiO3QuG+7RLc%%pGw_g2Ab1XqP$z@N zOF`=51&LF1xOp$$*HVl3D{V8YP1YUGn4+T?q7xn~q=@SznStN)kzcuFC08Z&3GBrC z#RALyn>VDf(&|>dd|Y818_vh;QnlGz_v;Ydm3N*Si7jr5Z6Apse|UqtqZkfp=-rrNMI&qtfQTo>`(?*iwW7d9hhi7u??IVk4X zn?7J;H}L6Z+ZA)mDptt0s?qNZHOg(;VA*G$)J@_HnvYLnG*ZSpmL9#TCjzsdd@gyv zT_`ECdqJ|O-Y-X6XLC$a)0Hd8n0##SCTbV7EL|;F*GMb2kicg}OzL$*4Dq@$b1&cO zu?l(5_xyO4!FiMXtO?oJMlrj4sy*yLYI|4n$i{y##ccfB0^Fo+&nJRh|C-v)gYY1O z0KMHd1e!Lz{QAR7)w9&;hx59P27C`UOH7^D=f(Bk5gW?{Zup&=Qip4zgpQT!eC~sd z%&Q9Cm7UK;u?TI>JOM85@wjQMP1wAh=fBA+KdsL{X+kujR8Oyb^ggA=A)H7Tv79eo zHs=6tq>8&r>&u@W(k5hIvdBd;C|+v$c!rDYsOnpzg4OFMq=4l}87eQ6nCBNpwOf#( zS2_@n%)eLN>>?LcYNWaOokDe|!Ua%piFh-S7ngaNYmb)JnZrR93Djw&vfb1O4a6ek zlqgMlW%JVhnlnRC@AxEwR<@OcP-<;Wr;5Gc_w*LYh7-wbO+?#er68k&$WIKfg?rwk z=su(fsfT-b*pqT#wr4FKYTR^2g(EcE>`JTMDtdoGRHxE$50F9CXFlJgujrK+OV6vQ z4qa{KUN%9MZoTIf&LqMD)t*lBU3kUt*n_Y-`&JT+zoKUE1?>=&@Hk|vbFh4k6P2G|>LovD$cN4yRXHzTQS=d$-O{f88`n9yAyRj%FmEeA_tjH^6qiX2v z{-CWj#^%+gK%;Q+xxD71>{w!xwsOYGktygWlP9I->k9pDikiH~Xw0*S4#_$ev^=2l>;=J>cVh_=zDE9*o>jN@r%>DXu zQ=c&N;ZfgUrx&F=xstv8cLFVzMqzjbK}hzi4UC63}%57Iu94wMZE5@ zaI@A^Ez673_$AwqJ!gBV!tU4bIN}Y_yJ}SL5sG}X(?i5_pYP+f-$B;4>1$gxB`DS+ zsD`fn4#)Y5colxeE<_hGS@4qy1!=j$i=o;kPKfUos_mPoQyUpCHnEPT79>duPbayg zTjIl9MxE|tZktZ(kevHWJk=>Hh%(9d>IV72I=fbi7FmvManFU(acj92%1u*9v>lO21g)C>HchIqWbN{ch#^qiX7Q5bZpw- zrlGnfGnbiZZnR>>L0q0u8vO&j*L1oJZ$BV+mn&;^JYvU;nx8%~yd8-e88qs0KIX7r z@)g@&_-yX-;Bw*hQw*Pait@c0w?8j6Ec<1o`Ab3Ab|}UgPuucM3uXM z^$j24+KA)5YCMH=2c!2El02+0RehZyJp^A1ggi?^yg5pMY9K2P7blaq8R>6KV4{_?gZN}#vYN^uGQl$b*<6FJa z3#OBPoX{f*_0X9!nsvm@i|@qkq+xuVc#Y3?B}n1(^~o;3qFM2_-`u@_Y7&JglK!<%{R6KKcwVycai#D*Ch4nbsPcvnEo|WQ8 zR5N|?Mmyyql8n52aEW$mu(&nf5)3mO}?v$vVA6KWTRUs;tB)bqibS7tygqIhQCqk6jz69|PJUEbwbl^?7 zn!sQ%%>Vo~Je0fWMa_a+o`#*Nk;XXX6zd_~*Tae8M_AI!vTjno$Asa{p3Cj*EfC%n zelpmc0lN+BmQp@H8GdnMj)rt4i*C7gCo7uLYRk9Scq#|mj07H%si-2H&L52QOOAWM z!K&GwlpIAc13I*6s4&8inXU65oG+B|poq62+TjEqCulv+r*mTq5B3te7Ekgd{NVTm z#fo-XQXi-E%UkdQwNR(%m);3gTXl4 z&5<^4yc7FC%1qtgSb)BU3OHT|xp9hB_=w(Nb6uu$mwsy#l;Mjr-+t2#&iOr$8zg{; zF5w&RbYJC96cHhds0zjZF{{EM0f1FZyji8_|EgkdJH7)p2cth4f73JmPua-KwKrMO zN=04tZ`A#7Z2nE300Tn&(Cy^{{}d*H+!g^K4&0$*PWCry|5wNG1P%fTw1M-k3+bQ! zQ+i0CA0*jO0X1=Nru+Z4j=~GH@eYB5`5(OiAr%F_Q!r;`y&=1Npav|Z2r0OuP; zrQ`X=kEMp&Xf1#?XT6)|fME>P7%@*eM*Am9A*rowl_rl{jqcFiKUyqfHOO7HPCePZ zK~~JQUaK^*QF6y(h2(Z@p0?>m_Zov*g)mPnE*c;_avEOV9?g^dO0^D-rB;kEy~&w>0Qs0XNccJ9^-1^*#No7`mjLM< z=pPKr%1X*m{MT{T0MPyP0gt3AS(wZ7>&xluo26K;#reA4@!S1-JT%ATxC@lQhqP#R08MSAl?LJ!7G@H#%z2GGG;}OY73ai7yR3a?= z+SZ>6z3tMblfk*@@w*F);dCwz?V*9gVV=7+2&au8iVJr2p?{ScuHUC9F5h=&aOf}ea>-T1_Nz(`iP4Qv{JNN0SiTs{{!}R# z*VAGa8*Nj~J&2puT=(ObYpJ=w)Iy<{XanydL?NhPchcOY`e^dvPsXA_6U*L~kik|t zd*1RnS5@7Rb}-m}Y{cNad@EE6x49WDo2XYXqHzqw`g@#P zmUgbLa+b_lD4tknpxN4H*dWGCYcy`M+`Re0=pmS|%I zwQ?cp3lEyva%pav$#UsyGCT1)L**L&Bq;F)XScK$$v`iW`88^hs` zN00yLJtC`g3bW1S2G2+O=KI^cJNxwKdli$?l%Zo&ogExQ{;$ylRYRP{7K!Z|y&4*kmjfzr zCd+x|b4LsKGVxEmU9Pz?JEHMbuD88$B@tbjEG5OTSnI)F)N>^Y7mp+tj(r2(*aXCP z#p{P#`rUtQOLp)yA`2Vd`Fq>ymRYg&OKB5AinJxb0iFbn;+UV+OLSXXNFvXw79gP+ zH!XfwPua0DG1seJtC!+p+c#$$Ie-S=5*4Oh2nhbD(%%BhvNk47&~BN>{Z;&n0zKe8 zVqxV7holVGnUJW#o?;-rD@aP(qp2b47GTY4^Y-S&IQc&ij_DAZN38+;f>jewVC8Zb zeR^MfYf1AFf8j}jk60mTPk&%1sy?J7{T*&;t2-sZjxH(>*cjh2Pl z5TM~##qJ3VMyKGwdUdLY3NLTSaQARA3Ktsr$q#Rq@Tw_~=3_r@a3Iph7uDo3yQ1!c zi9YJ77}39L7~};B;{v3da}+_4PPBC<-mUJUUVplitM5UhO$nCE4ehZ@U>O6VX)aQ2 z|2zBodrUg5kJtFq9|9!eKBL|N>^Tw>B|nTznzS*J9m|&6Z4`&IOdLh8j|$R})S|&< zoOv2J*V@%w(aeP<2n97P=i1d`zkuh|k2rIY5i*Wl79;)L-!`cNoQ{Et+_ik_V{iuo zRS%j6%yI?pZ^uH1RW$l&|)vNSsBlX6@^3hAX!_0N&vje_yK z>IAN!5mu+;OJPm{7G7Noa7P77Q;vYA>S${se-Cd9@ zPP?A`lx`FxV+N0^`X6+cgw`CskG}|t}H@Ak$!O+|2P<^ zXU$?2+8?=&Ogyr8u?|zht>=OKsjzS2@Mva$bb%L_tJO8&78nH?PS1V6Ywc8CKAG(% zfms7_+*^36wB~aYQ=jH=_6zIszz6}ZAWo|!e9!kh+D)?4IzKdk%ln6M)gc;9VK$=A zMZ3vA?v+T3T?S(1m^T#668qiPlVG|+ViP4MYz4+o3dB1jz%z9;M;?)nRQhzSycZv_ z;Mx9EX%|pjBNhk~W~a3Fx$I}As9dMDjNWhD^H7+?nj(?x`N1`O8Bz)a^waDBA1W;h zZADChY@LWK;+XR?$D(Oe2cV(jC=6SQ(UKjr4#BNeEyF}s`_cuDR8U;?Cq zQ2+apuL9|X<&LXE@oMw^*k-C7z(6(-WJ(7nmjkpkQAWR{a$V}}eH{>FU=b%KYDRsF*x+4ob zGFbd{aa|&CSO!dTo9I7p*E{Y`USiSr|~sO z;bJ&)qopKwu1eCZwUplX$gu#?Ff_Wgmq6Kh$h`;NdHPfrdeqjchiNry>}Nr^xpw}t zCk<^*WMk*RgSY-V>V%*Fpuf3J;S_&^IBM6!2x2LXjMH{w@dL?$(mu69$E^p@dhOGqL&`f#mTj(Mv=hSe;dD(6=9&7_hXV~r#`+EZ4P zU`uaoNeW#9sm+$gSBr`k~h4$9yBT1%Wfb-CV_|%%$3YF-36x9_WTLbDEFsPtX_R%n5sMp zPx%xj3DKe;ivfMWHTfNpl39K81zS+E4%IP*Tsl6V|GkxEVre&Iw&FfmmfVMHvbu@r zlF@NFw{VN}vuQNrD!B%^uZm5CDTW`;;$Z@|RI3I{w-wC_WhwQ;x1{|y{f{+N8Wzri4(RE;J?V+Z;zh!Lx;XfZbG}WSDEqKt=OGi66Dic zZg9w=H@-U#*8Kewc!_J^=DxUFUTfauCf7r07fmSdik;EhI_>2FFgL_4C9rg;?ptIy zxC?K`e|)h6|Ep@P8`bBqC?^D40+xjfz_DAR-%rYLO1C`SnPKs}11y?)_$_B^z1-eU z!J4nyWk9^}KTmT-nH7_^$HKnzkfyMG_7ot0>oO2WDPz`c(EVuDboL|lQ-5N<8#MS_ z@W%}O2DB~wD`M*(VkZ}nkC|-QI!VrGhR;L3X^i|N^Lb`^qjE^FZ!Kja#odEr1btlz z^P@C;fB8bm&lhmsqJCi!xk$<*MYp@s$C;Md@pvTc zFy9brAz@*B#zT4{o=6jO%l;K(`*b|H>&Dta5fqY-bdsa zT_`?L;F%~tLd@>&y_*J_R&3(^pF(hMC?v0JBP1paaxg2K!e(_0?FQecpXHnhL0AeV zYf?oqThjPqhF+D|l1dj8xeVnD{_V*JJugGW)^RU>isGO45Hw{>U82^(DeaNZTl$)x z4Qj#<>Grgjb5I5+jPhX(_DI;e^4s`*QYr zCXf@~riQZMG0m!aG|igih?uZL;qtc#o(n0c74aY_9>0c}UWHVV8|G+eu;2Xh{Ov{N zVl_`!z+vmBG}~IlY`R1(T`iHkk21o3^?YsW0wM~Yvbw(%xplmx!_GF088wDevKNYQ zJwFihqQZXIZ6xp^ zP4}A}#Z(66(}=KM^Uh6=ua6itN14cP0tgKCibx!-yg!szPXJalyL~8ogd!kJzheR+ z@CFas2QmGs;8k7YMY5GhnD<}Xk_*^JS!FhH;{XPdXcZWQ>jIwB3FkrTCtZIAUhUtm zps^d-1j&+x@;gF}y`rj3`@jji*4lsHM=$j){M0|fO-04) z5AvsKLP1vmQtDvYuo!)FuY@?tJ&5|cQX1EPy79^yX4Qqxyu2H~75@6vQ?O?|slx2l zQ>o6upo(gg-M`m1DrmB)S<2-IoUC|s-6NV*RoPgHY7X(T$=FHju0HZXMS5)}6;A>d z-3GiBEs>>Jwn0b&5cdJW5+<0hR=LY5*Lr-|+MrmF_L{Ii_NJO(q`fK1I56DWLWYhK zx}p*GGx?W6y*yt=Mx6=}uoV$)%=E6P{xwGYMO}J4*i)i1&s2vY@`RS(Eo^k>X#ag1 zPi7s?60dRKVOi>a?H9C$TKv%X7g9Jdt>uDVife-ibmWWf5D}f;;HTF-W`68)$X(%4yz?ZGyJcZ*Jq)Z zVtFCtqI}iMUsd37sV&F#$N{kUxTqcw{^3E6#we*K~x@a3By`0q2fq4fC!hoz$C5dN>o-%HevKf~Pcze9O?@CE|F zVRErU|Njj&^1lcT2<2)R|F?sTFD1|Dq>df`^WS6;zJwrAK5JtCZwHfs!zlrfszVO&2xt&AcR(|UP*45+>U6sGZH^tqzWgCvAE$e#E44?KUZxI;QXz~L5n2Vl(k$)Nw^;mFD> z7O;^rXuv$^TJH|cF`F%Abh|oKOJqs|1|;PZz$;TIR4R~~{c3YEi@24vliSmjP)I@V zW)-n?*X>(3jmu=5X5ak0Q#YGM&jr{AOjH_=W|LPhS~g0*cyWkf`hnAl1G#y`Biv0x zq_pbfk3Ut*r4xXcyqj$&->Z%m3~t13SFR>e&U!G?E9mGDJk&U66$uhoxJ^h-ZUx&& z#?sw+!@Q3Y#djecgh(dR#q)UF8JNk(8|DTux9hLc$6qc_n5WYuDDRRx6;`&#XXOU663P^m%V=Wy0<_*qCmxF zqucOU^&+V6f_jU;AnqppmH;{jQ8ym3rAKNA4&OQBlWiXn_FGXqW*J=+<^+I)IA~2< zt2<`!(_u#4767P81iZztO-;*a=R7G%wpD&6pZKNIt+gZi=3>@7b}>$g$I%_PK+fo- z*o06B2y2za(Q2}OOC1BsYuaGWdkMVi>?h;+JQ?)ErCM_H4kt5WIGt)^f@&P>A{{zH zNb7D+7(#Q@!)hQ4GY|*UC+I@xIc3ngo2wDzpaGgu$YPg^YL2d^?FMPB*G7e2w|qkqoJ_>M1?)Kt zA-m%p(3AamPC>hBpN|&vj0ex;MT5;(=^6x3OqMl-5GrCLc`@rZ(c~2sZaA}VOKOE0 z9MDUe`nrONo83a)uaf&@d4t_g`M)lMy+VpL$R>(ZZ`?{Wh$(&&4m1b@k!|^KshfvS z+P_OQDKaIX>(@h0*`K^1^3inKLI9}@+<2)HT~KImGAkoQ8yW$@cT9p8sNPFs7 zkqxfHF!Lo+A1qeI?`MXYh#Sm1-@AP4u&vjHgEaFCvF%FS0c^lT*@qAwD47=*IQ#u6 zaUguQtsw7|ZINcbe!H^DQE%sV&>B6dB6-~te~p9sIx8!ZXTjtT`Zqo>;NG4Opq+{3 zE56%V6vPzh@iy#c{ODL+iHW*1<+@q(J3sMy)}&G`ZK^Fqtz2?i^-v{*1-8o$v$A_S zsyEbP>Xn9hP5B#`h=I-GLIf|+r}j|M^tyE1Z}Rop{f5B&WHQRimez4+*kEr-vkie? z7#*a?n*Qw{ysfMnyqn1+@JT!m(d%{_H$rGE%JGEm{IHU^5W&goXX_q0DswSMq#@db z*QN3ev#0R$qgCAyhl7v|FSp`(UvRr$=a#kaJyDuOReV4LDNWOt;f(|Zjee6V8uf}U z^{%$*AP_T$+qK(vUbWLfEPal?Kq5%Mv8<}DNjb(6A!V%P8jBv{GJe&#^DCC5Y z2!rB*X}L)brSn!w2}{@AX6XF%Ps3RcuJ(du@fVnmHJhZ;8{d?fa=Y37aPWwehJP04 zbWDu=enMn?A6LOb(%yccQi;3C?c&qrRs~NuY-={+DncWS*5kNVedBlRdNVOZQCEB= z+9fzem44kqGLU*v(-K2nz^Ab$(+u)* zb+gw5Gdj{mUo#hqMQ+7J!nl!(F!z$d3F65yWXh6@YBDF-x>@h$J+y|wMN>N!#<5hk zC*!o*+GidOR|{qi{H4_AG}+CicL%d&CkoA1gSxh>Y>3NeZ4`N5X?G_nYT^%gZxvH! zY3Q*&&9!O6#NzTiDz+py%M2vaQIfb$+u>||o+BY^EhJ~F(oc0dw3#zwicQE$Pu_P| z-YH(7YNc5r?Yu5HN?+z|EsNW+hhn%WqgBWfFsYYA7;%B~KiFZ~xm_u-#8I5Cy;@6{ z-fY*`5KkL0eAs#iMx3#nWF1aC*(q`I@P7c&ZyL@Nt8*al3B?6u{5r`?2?0ogb#ZI< z1A~)W{pbrEs{XpwPtB>y@uHDtc*(oVOwW$xO&J#RRr<9MGiB{#p2C2sBD5I;-LrNr z_9|(IE46o+NOitqSaHL1f^?CymaV8>#6-^4i2=f z;c@3!Fcxh%Z5P}18h_j*BSrYXM z6`Htw>K{CgzDaLY;X9-Wzq$@R+MjhF+%d%-JFtq}{me@{NBEptrJ%!6-CXoK!Ou(? zMs(4cE>4m~{f0)ZQoHmfUlf`KRuB#VxID18_ksd`ms8){WZ3)UzrPPgVaR zX?yvjy^J$zU($rYD*uW@Phdrk#6Y+xv)yPquBWP(<%Iq`e^I~Ncy0XE?YEK~qwZ7t zADjd899KxDx|8wz&znm{d9{hyccl+zo8aRI?6P5N#9b^IlbsbeC&nXQ_i4DI!4a=& zo>ffwK_#Qj^X3yG1o@>nAI zc3MwmNI>bam`k><5EPHOOdjLRk(O^3hE4B2T=?m0y*8cEDbPg8n9{1Pb((_Yx+EAGpnFzi8Qo6T|C)U_ta4YJf~_e5U})U>})3bcEsJ|#~Ln<Bp*3~ zvn~TsB_8&&%2e;Ciz74_JqWQA_Z{!hLzQ1slJm{eEdfUm1*P$csw|EYEp^(ys_kf= z)q&|q)qPdXGfi{P1-n5}uIsB;WE|o`{7TCGqqqCAy>^HL;u6q-l=8P_38CUQ5Y=aR zorq89q~p)!;v=wc6Rtlk3zQPD%j%@mbx5mN74*~Aodz#`bQr5LQJg(ltTNdsHJ@>J zNrwTa&;-^N{mRaWCs9z{H#ppyq2C@P2_cvZ+^lAD!cEhZvT05+2fx(@#O)-?dzWcP9jK#0|-^QRsdn&Ulo@Sc(-TA|SF3)Q2G1 zuMc=iXaArhRTo<$@N^w*V7yx|jo>3FwfJ>7l2+Z?bH)jPE=HZEoFau!DhtP5x8hZQ zVr&D6^}N683XNQ2Zof?rC%1c$j@>e#!wpUJRdTq65C!r*wpKSa!YPSf%$~RmXg>Hwovg1)SN5&erdx$ZhL6MBD;AO{%o?sWBU;{Qx4eXPmz*+aimRLr;suCn9F%sV_>Uwv#u z-o8_{l7pga(6J@(^(z0&93`QOV&1w;$NfuXkxoj|N_oyZU6fy2x5ZgqsOjhft!IisOX)sftE5VHWA9D;p*syj6;V9$_+ z*9q>Q-}(KGctOW-MSWHFRl4azPG&=rN$bV>a^?5e?F_wWRzAPgGGzrh%8$Rmv4O_g zOeD)1k2!pnbR$&evfEJL>4^}F>zWnEfOHwjYpdmkY1DCND86WacCLJl>Oztzj7zd_ zTh9O;m;){BN5^1C0OCuU-+}Z}#a%ZB<6vpOGPI{(p5>lXn|F;S)@F^&8yd+Wdy+d$JVNhnRh z2TLp1)efMgu{W;`pN*6^VaSj{0b?KCbN!E|bye#6nUf;)-<+8tn-Pl^y!q&&h9G!( z&|4qeUE8VM*W;BW-wp+qvgS|4rH$%Sr>^b0PIRzCmvYm7#fPt>L~LIjlL_+qGLdjF z`2c%=a4~=KOE)XF`_c0!ni{hya0AZ}_=y8j=mv14mJ2{%3y?}vHHGoo5o@j6Pm}ockOhINd<>GVYw(z@b z-J85n|8WkT$dES^k+rIe!X8ofu4R=EM3^3G#m={%YZB!$LVNPD3}=F+LF{d9PJ!u# z=zgOzN4RxG)Sc(b8}>Y>8+BCk&Wj&&LWn|k6BE+s+d=Q&pVWBZa?+BAWT-7H?%qE- zr9T$sIgPy*ym?1Tz=r$W^0@j(+JV1($>e+47-LL4;oc@bImp+**Y|3%5#C{Uj2|$0 z-GxWvxj<3F9M)O%zlwv@M@L9tj$<w0lZC(GyRrI) zRw$&Z`Z*I_`Od}5UpCKl%z=g2_uhL(kTaq+rE-+nEPk?WrUaK08S`t>dbLGi1u_Af z%*g?e#QAVXaif((_gW`d(5OVC+V+BB!96ISVyEu+T1CKlA7UsC^f3@s;Mr>UQ{Jx& zAP)Hn&oonc4KbZdh45cM@s=2oUO~F-TcW}^2cf8kP4A%jiKUX0_Fcqd$bK#Pi5G~* z4q%hhOYQL!53q74U5=f8f!aXqHYWCgZ{l>x`Th7V*PgV<4Q;EJWyk^y+Wf)~1p;SY z2o?>JZUi70wxoQ{dL2tmuFmX8l6SBcOD@&3(mM$rJQx*kphXjiE5afN3{A^nE&9u~ zJA?ucqO!@S2fHOwO6)-1I*KtPtkR(2HUs0hZTgSyZxYltF?U(j$A#iN%N=$s+1LB~ zqd786eD$^hU>`}7Paj!XE>x@>JPx49#$_LW4`EbO44VhNnL;05dkmkD+ThRRb9+!x z0&R@rJ2e?+Ui3EItcfrzqdN2Ei^@*>iVj*8s`nUn#mbddzA7rf5naOLLfzuN_;{u+ z8caV*gxxOu#+Om2IweX=jB-Jz&%zNFDV5^ak|+;6jwOAQmE>&iF_=fXc$B{NVdC~) zKxYi)=$&aF0L|za89!dMY2-F#NVi;VT%!0+nB+B;X_DI6LjU$bqr-ZrYMX ziHV-PP{>!@I>_>yeZ8sNk0ZrFlV2;!C5o1?1mX`(rK-FfRYDuny6>Um#NybxKaAGO zC`tDb?caZldz^-2;C;=TRVYDhjQ}4q`|xJeMvJNsEt7uxl=CTc8IpVj(h`? z`c)uFia)64sbJmuMtRWC6rB#rg_hs+;K1JUzmuuce&NMlPZ79JmEqK(a6u%Bz?-)tK*Yr)S za74Kb{!C57n2 zJz2`7{7ypUdTTSi_&lry|3JIb5s*Gi% z8owjWCULf;1VYrR5GA}y3;wq_iPeSj$C)j^dEklVZ@CDrh%bE+K3S9^yPoZ!dn73F z)xt5)-Q=T2bD#WpBsqrBVZs`M~hy;-s zZg1K7_W^LVow9yfUUsa=3*^49(ejS$v{XG7LWnpCRC z?hEe4bl`oAAM)Dy~j2&U^ zc7ZjwFa{IiRH{2QjNGl-CncHFdHU>nk0Iq_d9)H>^ZBk3 z;yPa!uVb1;(Y2^I#r+Ju`3=opYKy^T`6&e#(sLUhhAm>Ao=Wj=tbqzpS4dMj>1o7K z=?gMZBF*t~dx}Ntk2zMtVk!gm9CKAcsvd@yf89BcDJo20qsDweN+g@X+MSym0J>bMx5 z+DAm3iCg^IJXb?nX%O*HqNa)_{t5*>ECV~vC;$@@;r1=%Hx{KvK_hbt`?$!(`1M7a z@l65nY?YJ7iZ!A3;DP6ffIIN@(F21LVZ~;|=^u$^^AnI_I!oUIArB|iv*YbHFUT)W z5!xtpou71xpO(f@nSDL$M(^8iH-+{qypE}^poen!_~u9Y?%z%tGmu11q+!gJ5K;(a z;2RKl>BB#pYBM`$x>VfteRl-kmOXyDB?}7jCcFFUIet_0eW3TP^@j1*=0}Itx<5g= z4PuD>(hIXeH6szZtn!Zxy|c=RzC99g>SN4PZTwP?p1itRl!WbxO`MC(FjfcmecyfU zgJG%P%)DC(@0>D^v^t#)p=f6t*O13-O#0}@yS;W{S>h&AaR3*~28*UEOE7*sNqWb1 zF~r28W8l4H-H8+(WAAVeH`PE0Zbd-Y)X#&6Bc&F@V$#_O{MQ{NOucsHjvwXcO1gJ%@)eZp|!Ta5F2 zICrzLR$|0G6yt}D`pA2A<7gVr9m+J9Ir!{xU&&+S2EBPpMhmN4E=p+$YvLB@iWT5| zZwZ*cESc~kd_K-}i_4^JflNrI5yRU(^;3WkSD=bv!@TfYvkwdq?807ZoilKYTPTHk zE4zcSK0&aT=D+tlJvcUm3)>6vJSqMZots29_G~S~jgBOldVZt$kzRn9KlSpLh|FqP zJLjy)DKhGm)NvFeZ0q1GbCS<1GT$%o9rcfWm~t+pLwuhQ)V?uxo#KkV*&P+K*)qd~;d>odq>XGT)W@!Y-dG)~}#|(FI>Wht%QYPjHPbKeV#E<4N zr~^bDxW30Zd3S5B-;vvK?Zj2F!W{h2?2CCpV-HVJ7z1$%lOUvmoF{*HA7oj|+|j41 zA=G=x_~J|t@=PxEb|mjL%o^zR`KafMysBBkTrx{Z5-|}?j}a6Ve?q)3f&R9mnGTCT zHQzvC>Wn%2VM9m2y6}kvU*&|GZv!U2d+(p0c;NF_?WVz@*XqJfl5K(GX6xd!LRj2& zM$YwCAZl*amD_tdRogKQKduM~#5cr9rI?U!^ilc?k-3ACsw~DQQj_21SMYS{?4dYr zB3eo{amsO_J2K&G-_j$SpMf+f4gtph>ybGZ2e-8h7LcC}L<3s8?pT}=V z)`SiI(@tB&!MHa$7TF|Ay|XLmF`*@X>SM?c{pUx}K1UBNrndk6aI>}t&$u>h&`=(C zot~cj&F7#&gZs~mM1?5SbQR2FFmpv-~POwDHeMsecrJj%nh_J?(|B=qZ){(`*ZiZmUN7b zu;4Ikjm*_tfFu;76EQo9N0Y)D84(pzO2?Yv{G^N*>m-&iMNf%4^tB`HDfGyithYJM z8BW`~TsJY?)V9`}?{~D)RjqK`NgB} zn)nE+9$2=98P`krT8!LkFEfNTgLTl8fCqX(Lk z2)MgVPRG{^zul?A`dod-Z`fBd>1g~TVhcj;kT-myHlpnX8Rj zGGA$41YAJjqSF2xrCl|{Yu-|@_bJ%iiKHL>;Au)HOeRT#zCil6MLrSrw_XedJY-ro zD#cb>w)XKOr{>y#kN9#U>ZUjm0;Bl$jurY+x@{u7SjQ!)%9zf8GV5!quCi~^>0IpR z)F4W^9QOj~V`9)V0xT<~`%B*6eYBX*bf|1TX%h(=HdxpSCZ3I5lP&-Xiuo7+^K6IQ zj#3GUN>TfKJr}Vufk!E z0th}%lY8;elNp6KdvJwuSk4QCdLl4@^jNf}l{9bSZV-gNB`H1AP%@gwL+I{Gnzwg+ zQa1E(fy{PX_|L^j3pJoj+B4yBKx4mGbydsb&?%a{#RyJ7m=)@VyiWo?uOSbC#5!`gGqlSo6(k`{_ z3C?vqf^gWpXADt+q?iefHTA^KluVv9u7~_K!j#@4ORVFhQYqf$;l@0xD8KmU8tTE5 zhI*R_#qybsrgPINi%XrJkq(E^YS#8hM&G!X=@6sL6_o-hWao4QoTZ{NOqZuydkYJd zu{&Gft7XVEm0> z7u$r<|2FfYwo~{1>TzekWr$^_H7dM5JQ=O2l0aphg*$Rq?_R7{vXK|FBX*!2K^2Tc`vygV+lf)jh^VZt@tDzpzhfgP+koH z#a=k9sJx;eQBJXiPWl?)rO(YXdjzQrm0XLzUYfT-hBhh zWS(9OyyG!d`dR^|&8mobyvC~E!i)|i!2FdCRWDPU*|3xDmhJWYyvS zp5!xknU?a}T|eX>ei;(+5_Ey6Btl}ibFubCrs6wA$R=1d4ie~6kfO}K!d4^je-Ea? zi@9ep%EW;uj1vJj!9{{fiI8#tc0UPh)T6+>t`bWjP&h&?N z{`fa1^RK2hQGkgm{t6DN5pc7+Ok|9V12hHdGFz%~Z#71Ebq%f#=W@_KbgL*la2fOT zi4u5_cE&g90H$!swZ8`f&uJw8sZRTh|AIX{XGfI1L6LP0nCV|T8Sso(Sqiu2zKaR?VQ>PS)# z5jxA)Ax8A<&&nJRlKhQMmJ(3|bpQR-eJQ2GK~C$z<_?td7oQQTGXHAocK!Z7{7i^% zf#siWzMPmW)8uEl63)vP6NIYl=L?UYtaE<}xoqug1jqcb2)sJ%Z)LPq=5L(;ryuWp z1j5>mm%p(M#^gY2a&No137``1vm0a*SCD2JQU{Qf3;tTJu-NGM>oi+9calO>sWUyd z*uz>|mTZ5)Gyh#qDA$Cl_B@LT$2ZM!*U5fMYAyVgWF0tBCU7DQGsmE%R>R@2J{ui^ zDbwQC;nE8GZJbNm-);F#J+tS30ZCtK4Bz>zhqmRiEE@EOvAp+or7haRMd1g~Ls4gM zhf;!OKm_$pgDJeky)GVOe=GWKWp*;qKz zpDDX@#7J?7FlB?9CBSHoiZ-t%>Hg_>nN{}=qBWkFFp_Q_TbsTp^U>j{RiFCbT_ark zELVB!U+m?W3b}&x_l>($K#~{nu4N6gjD&_m7MM9re}qkceAX8FM?5D((w)_0+N)mdvS!0Y{TVX!B=MHJI3NyBV%a&;o z(<)4^?}E`xk;NP>gK5;Tqr!%MCM|b6xX2^MOY71hRhyZ^(O!ZjZCsRx)(Z~h81j@< znzhM{4;DAuT5&hE1RMQ*o7&<+D0_)t<_plu80P6+MYglKk5nqJMvn}2izP+TyqsV@ z>u}hazuYogDRpLpzMEZ|d;PZ>x)jYzr@`XDPUNfwjE8`~XC2`e^Vj=4Exk?oRnzIu z$VFyktp+Mum^RJD+3{5wZ{#c%HT?*V=VEy%~mlwrhg zk%GiRLcW0ZKGSv8>tV?{FRh)Nz2T@p=-$BVpDyES{rzQh7glE5eFQjp?%(cDC#1EY zkdkrxO%JA$$$c?yPt>}CoqkVGG>Mz;t z&986%J^4}i2tAx1W(87tjw?WWxn6wWdxznKgEbA2|U zhkKu?;Miz^1u6s2q<=HeU>k-Yq&GJCyl)as$l-%W^RlhM!N&RWlY^rizU+^%*2hFf zlXim4i-=qH#WNlqvq{$sN(_FSz!W0M zDpW{)l?S_fnpYzy^y%qjeqIY` zh^Ac;7G_OK)&)M-Gu}<-gh`c!F`=i)G;O%_4~@tkAjrM@&xjCmLvw2%DYRabncVD; zPAsBV2v>@R#q5R7)}Qy~Q1dH^;x*W7ytnXF(vYzT9&o;RWNi1B_voZzgfp=xLHy_1 z!w`=xPJY8L)1s%4hDWM~%hVq`=~bn35p8nO&pMc>U(-NALarG7Ii+d4&f6N%VwiJa z=bp12|E$a!wY?cGzH=*w_)o87d`2W!=U?IEYuYKRq}uNck{59sQMs%aC)`-l!Hu7K zHwa>7dyW#2$zA`bA6i7k%W1JtX7-GZlP*hGKc_;M8_Zl(`_EKH5o_f${w+V^)hLdG zY!x-5xHuFl#yu_riKrey=CE0@A|2HHsC_ci;ee1C-F~p72z6mG(Kc%~Y>-b2xNYd_ zo((H(>VCe>vFl>1n0QDw>e$=eb;SJpX#)kjj)^+*W;>7R_jDz7rTomc@9zi?=d%dJHi%-oaG8Sx^I(I_ThG}zYyA^{ zmJ0n@{d-v3SYVmW9JDQ4dS*^d(@ZNtKkJ#a)oIzJALqRdN}v!jAC)2V{@WW~l?ct% z-x_yYP5%DnE9gC}F(R@`^uaVq?@zgG;sI`~~>8LM_!w+7cnZVIcan<1@Z4sc_c^N&qTm3LGj{8&P8 z@$dcqS-`BN2|KF?K8XD1j^S(L_a@x;?j-;FoUfp+Vc|26=M}L3bD{s=`pTMDBRHqk U&a!dl74Ro6EF)AZpy&I405a7hqyPW_ diff --git a/docs/UsersGuide/source/_static/SUBCONUS_Ind_3km.png b/docs/UsersGuide/source/_static/SUBCONUS_Ind_3km.png deleted file mode 100644 index 8bbcbc7aa3aadd290991cc56b46be672d5811372..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 81808 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

    b4Mo)M@(h-ccf-y5B@+1#kLOFQ$VP1|W{)`=Z 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 q Date: Thu, 6 Jul 2023 14:48:50 -0400 Subject: [PATCH 006/116] minor updates --- .../BackgroundInformation/Components.rst | 119 ------- .../BackgroundInformation/Introduction.rst | 150 -------- .../TechnicalOverview.rst | 321 ------------------ .../source/BackgroundInformation/index.rst | 15 - .../source/BuildingRunningTesting/VXCases.rst | 6 +- .../source/BuildingRunningTesting/index.rst | 5 - docs/UsersGuide/source/Reference/index.rst | 9 +- .../source/TechnicalDetails/index.rst | 5 - docs/UsersGuide/source/index.rst | 2 +- 9 files changed, 6 insertions(+), 626 deletions(-) delete mode 100644 docs/UsersGuide/source/BackgroundInformation/Components.rst delete mode 100644 docs/UsersGuide/source/BackgroundInformation/Introduction.rst delete mode 100644 docs/UsersGuide/source/BackgroundInformation/TechnicalOverview.rst delete mode 100644 docs/UsersGuide/source/BackgroundInformation/index.rst diff --git a/docs/UsersGuide/source/BackgroundInformation/Components.rst b/docs/UsersGuide/source/BackgroundInformation/Components.rst deleted file mode 100644 index 3802c384d3..0000000000 --- a/docs/UsersGuide/source/BackgroundInformation/Components.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. _Components: - -============================ -SRW Application Components -============================ - -The SRW Application assembles a variety of components, including: - -* Pre-processor Utilities & Initial Conditions -* 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 the `GitHub Discussions `__ forum. - -.. _Utils: - -UFS Preprocessing Utilities (UFS_UTILS) -========================================== - -The SRW Application includes a number of pre-processing utilities (UFS_UTILS) that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), these utilities 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 :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3`-:term:`LAM`. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS Technical Documentation `__ and in the `UFS_UTILS Scientific Documentation `__. - -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 `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 (:term:`LAM`) capability (:cite:t:`BlackEtAl2021`). The :term:`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 accessed `here `__. - -Supported model resolutions in this release include 3-, 13-, and 25-km predefined contiguous U.S. (:term:`CONUS`) domains, each with 127 vertical levels. Preliminary tools for users to define their own domain are also available in the release with full, formal support of these tools to be provided in future releases. The Extended Schmidt Gnomonic (ESG) grid is used with the FV3-LAM, which features relatively uniform grid cells across the entirety of the domain. Additional information about the FV3 dynamical core can be found in the `scientific documentation `__, the `technical documentation `__, and on the `NOAA Geophysical Fluid Dynamics Laboratory website `__. - -Model Physics ---------------- - -The Common Community Physics Package (CCPP), described `here `__, 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 most recent SRW App release (v2.1.0) included four supported physics suites, and a fifth has since been added: FV3_RRFS_v1beta, FV3_GFS_v16, FV3_WoFS_v0, FV3_HRRR, and FV3_RAP (new!). The FV3_RRFS_v1beta physics suite is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (:term:`RRFS`) planned for 2023-2024, and the FV3_GFS_v16 is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. A detailed list of CCPP updates since the SRW App v2.0.0 release is available :ref:`here `. A full scientific description of CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. Additionally, a CCPP single-column model (`CCPP-SCM `__) option has also been developed as a child repository. Users can refer to the `CCPP Single Column Model User and Technical Guide `__ for more details. This CCPP-SCM user guide contains a Quick Start Guide with instructions for obtaining the code, compiling, and running test cases, which include five standard test cases and two additional FV3 replay cases (refer to section 5.2 in the CCPP-SCM user guide for more details). Moreover, the CCPP-SCM supports a precompiled version in a docker container, allowing it to be easily executed on NOAA's cloud computing platforms without any issues (see section 2.5 in the CCPP-SCM user guide for more details). - -.. note:: - SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which physics suite definition file (:term:`SDF`) is chosen when turning this option on. Among the supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. - -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. - -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 App, the UPP converts model output data from the model's native :term:`netCDF` format 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). - -.. _MetplusComponent: - -METplus Verification Suite -============================= - -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. - -The METplus verification framework 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) `__. - -METplus *installation* is not included as part of the build process for the most recent release of the SRW App. However, METplus is preinstalled on many `Level 1 & 2 `__ systems; existing builds can be viewed `here `__. - -METplus can be installed on other systems individually or as part of :term:`HPC-Stack` installation. Users on systems without a previous installation of METplus can follow the `MET Installation Guide `__ and `METplus Installation Guide `__ 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. - -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. - -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 (which include conventional point-based surface and upper-air data) in `prepBUFR format `__ 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 (:term:`EMC`), and it is open to community contributions. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. - -AQM Utilities -=============== - -https://github.com/NOAA-EMC/AQM-utils - -NOAA Emission and Exchange Unified System (NEXUS) -=================================================== - -https://github.com/noaa-oar-arl/NEXUS - -Gridpoint Statistical Interpolation (GSI) -============================================ - -https://github.com/NOAA-EMC/GSI - -RRFS Utilities -================ - -https://github.com/NOAA-GSL/rrfs_utl - -Unified Workflow Tools -======================== - -https://github.com/ufs-community/workflow-tools - - -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. This build system collects the components necessary for running the end-to-end SRW Application, including the UFS Weather Model and the pre- and post-processing software. Additional libraries necessary for the application (e.g., :term:`NCEPLIBS-external` and :term:`NCEPLIBS`) are not included in the SRW Application build system but are available pre-built on pre-configured platforms. On other systems, they can be installed via the HPC-Stack (see :doc:`HPC-Stack Documentation `). There is a small set of system libraries and utilities that are assumed to be present on the target computer: the CMake build software; a Fortran, C, and C++ compiler; and an :term:`MPI` library. - -Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see :numref:`Chapter %s ` or the `Rocoto documentation `__ for more information on Rocoto and workflow management). 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 SRW Application allows users to configure various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, integration time step, and the physics suite used for the simulation. It also allows for configuration of other elements of the workflow; for example, users can choose whether to run some or all of the pre-processing, forecast model, and post-processing steps. More information on how to configure the workflow is available in :numref:`Section %s `. - -An optional Python plotting task is also included to create basic visualizations of the model output. The task outputs graphics in PNG format for several standard meteorological variables on the pre-defined :term:`CONUS` domain. A difference plotting option is also included to visually compare two runs for the same domain and resolution. These plots may be used to perform a visual check to verify that the application is producing reasonable results. Configuration instructions are provided in :numref:`Section %s `. - -The SRW Application has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g., Hera, Orion, Jet); the National Center for Atmospheric Research (:term:`NCAR`) Cheyenne system; cloud environment, 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 (Level 3), and build-only (Level 4) platforms. - -Preconfigured (Level 1) systems already have the required external libraries available in a central location (via :term:`HPC-Stack` or :term:`spack-stack`). 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. - -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. Users will need to install the required libraries as part of the :ref:`SRW Application build ` process. Applications and models are expected to build and run once the required libraries are built. Release testing is conducted on these systems to ensure that the SRW App runs smoothly there. - -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. 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. - -On all platforms, the SRW App can be :ref:`run within a container ` that includes the prerequisite software. - -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 `__. - diff --git a/docs/UsersGuide/source/BackgroundInformation/Introduction.rst b/docs/UsersGuide/source/BackgroundInformation/Introduction.rst deleted file mode 100644 index e46f134177..0000000000 --- a/docs/UsersGuide/source/BackgroundInformation/Introduction.rst +++ /dev/null @@ -1,150 +0,0 @@ -.. _Introduction: - -============== -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` (including 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 most recent SRW Application 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 the `GitHub Discussions `__ forum. The SRW App also includes support for a verification package (METplus) for both deterministic and ensemble simulations and support for four stochastically perturbed physics schemes. - -Since the v2.1.0 release, developers have added a variety of features: - - * Bug fixes since the v2.1.0 release - * Rapid Refresh Forecast System (RRFS) capabilities - * Air Quality Modeling (AQM) capabilities - * Updates to :term:`CCPP` that target the top of the ``main`` branch (which is ahead of CCPP v6.0.0). See :ref:`this page ` for a detailed summary of updates that came in ahead of the v2.1.0 release. - * Support for the :term:`UPP` inline post option (see :ref:`here `) - * Documentation updates to reflect the changes above - -The SRW App v2.1.0 citation is as follows and should be used when presenting results based on research conducted with the App: - -UFS Development Team. (2022, Nov. 17). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.1.0). Zenodo. https://doi.org/10.5281/zenodo.7277602 - -Organization of SRW App Documentation -======================================== - -The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Technical Information*; and *Reference*. - -.. hint:: - * To get started with the SRW App, users can try one of the following options: - - #. View :numref:`Chapter %s ` for a quick overview of the workflow steps. - #. To build the application in a container, which provides a more uniform work environment, users can refer to the :ref:`Container-Based Quick Start Guide `. - #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Chapter %s: Building the SRW App ` and :numref:`Chapter %s: Running the SRW App `. - -Background Information ------------------------- - - * This **Introduction** chapter explains how the SRW App documentation is organized, how to use this guide, and where to find user support/documentation. - * :numref:`Chapter %s: Technical Overview ` provides a technical overview, including SRW App prerequisites, code overview/directory structure, and summary of components. - * :numref:`Chapter %s: Components ` provides a more detailed description of the application components, including optional application components. - -Building, Running, and Testing the SRW App --------------------------------------------- - - * :numref:`Chapter %s: Quick Start Guide ` is designed for use on `Level 1 systems `__ or as an overview of the workflow. - * :numref:`Chapter %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers come with SRW App prerequisites already installed and run on a broad range of systems. - * :numref:`Chapter %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. - * :numref:`Chapter %s: Running the SRW App ` provides a *detailed* explanation of how to run the App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. - * :numref:`Chapter %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. - * :numref:`Chapter %s: ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. - * :numref:`Chapter %s: ` explains how to run METplus verification as part of the workflow. - * :numref:`Chapter %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this chapter is a starting point for those interested in AQM. - -Technical Information for Users ---------------------------------- - - * :numref:`Chapter %s: ` documents all of the user-configurable experiment parameters that can be set in ``config.yaml``. - * :numref:`Chapter %s: ` provides information on application input and output files, as well as information on where to get publicly available data. - * :numref:`Chapter %s: ` describes the SRW App predefined grids in detail and explains how to create a custom user-generated grid. - * :numref:`Chapter %s: ` explains how to build or alter the SRW App workflow XML file. - * :numref:`Chapter %s: ` explains how to use template variables. - -Reference Information ------------------------ - - * :numref:`Chapter %s: Rocoto Introductory Information ` provides an introduction to standard Rocoto commands with examples. - * :numref:`Chapter %s: FAQ ` answers users' frequently asked questions. - * :numref:`Chapter %s: Glossary ` defines important terms related to the SRW App. - - -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 `GitHub Discussions `__ forum. - -.. code-block:: console - - Throughout the guide, this presentation style indicates shell commands and options, code examples, etc. - -Variables presented as ``AaBbCc123`` in this User's Guide typically refer to variables in scripts, names of files, or directories. - -File paths and code that include angle brackets (e.g., ``build__``) indicate that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). - -User Support, Documentation, and Contributions to Development -=============================================================== - -The SRW App's `GitHub Discussions `__ forum provides online support 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 | https://ufs-srweather-app.readthedocs.io/en/develop/ | - | User's Guide | | - +----------------------------+---------------------------------------------------------------------------------+ - | UFS_UTILS Technical | https://noaa-emcufs-utils.readthedocs.io/en/latest | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | UFS_UTILS Scientific | https://ufs-community.github.io/UFS_UTILS/index.html | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | UFS Weather Model | https://ufs-weather-model.readthedocs.io/en/latest | - | User's Guide | | - +----------------------------+---------------------------------------------------------------------------------+ - | HPC-Stack Documentation | https://hpc-stack.readthedocs.io/en/latest/ | - +----------------------------+---------------------------------------------------------------------------------+ - | FV3 Scientific | https://repository.library.noaa.gov/view/noaa/30725 | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | FV3 Technical | https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | CCPP Scientific | https://dtcenter.ucar.edu/GMTB/v6.0.0/sci_doc/index.html | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | CCPP Technical | https://ccpp-techdoc.readthedocs.io/en/latest/ | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | Stochastic Physics | https://stochastic-physics.readthedocs.io/en/latest/ | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | ESMF manual | https://earthsystemmodeling.org/docs/release/latest/ESMF_usrdoc/ | - +----------------------------+---------------------------------------------------------------------------------+ - | Unified Post Processor | https://upp.readthedocs.io/en/latest/ | - +----------------------------+---------------------------------------------------------------------------------+ - -The UFS community is encouraged to contribute to the development effort of all related -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 into the authoritative repositories, users must follow the code management rules of each UFS component repository. These rules are usually outlined in the User's Guide (see :numref:`Table %s `) or wiki for each respective repository (see :numref:`Table %s `). Contributions to the `ufs-srweather-app `__ repository should follow the guidelines contained in the `SRW App Contributor's Guide `__. - -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: - -* 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. - - -.. bibliography:: ../references.bib - - - diff --git a/docs/UsersGuide/source/BackgroundInformation/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInformation/TechnicalOverview.rst deleted file mode 100644 index 4eb03e3c7a..0000000000 --- a/docs/UsersGuide/source/BackgroundInformation/TechnicalOverview.rst +++ /dev/null @@ -1,321 +0,0 @@ -.. _TechOverview: - -==================== -Technical Overview -==================== - -This chapter provides information on SRW App prerequistes, code repositories, and directory structure. - -.. _SRWPrerequisites: - -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 (concepts of parameterizations: physical, microphysical, convective) -* Meteorology (in particular, meteorology at the scales being predicted: 25km, 13km, and 3km resolutions) - -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. SRW App `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 - -* >82 GB disk space - - * 53 GB input data for a standard collection of global data, or "fix" file data (topography, climatology, observational data) for a short 12-hour test forecast on the :term:`CONUS` 25km domain. See data download instructions in :numref:`Section %s `. - * 8 GB for full :term:`HPC-Stack` installation - * 3 GB for ``ufs-srweather-app`` installation - * 1 GB for boundary conditions for a short 12-hour test forecast on the CONUS 25km domain. See data download instructions in :numref:`Section %s `. - * 17 GB for a 12-hour test forecast on the CONUS 25km domain, with model output saved hourly. - -* Fortran compiler released since 2018 - - * 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, LLVM clang, GNU) 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 v2.12+ - -* curl - -* wget - -* Lmod - - -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.20+ - -* :term:`MPI` (MPICH, OpenMPI, or other implementation) - - * Only **MPICH** or **OpenMPI** can be built with HPC-Stack. Other implementations must be installed separately by the user (if desired). - -For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew `__ package manager for MacOS. See :doc:`HPC-Stack Documentation: Chapter 3 ` and :numref:`Chapter %s ` for further guidance on installing these prerequisites on MacOS. - -* bash v4.x -* GNU compiler suite v11 or higher with gfortran -* cmake -* make -* coreutils -* gsed - -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 - -.. _SRWStructure: - -Code Repositories and Directory Structure -========================================= - -.. _HierarchicalRepoStr: - -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 tags the appropriate versions of the external repositories associated with the SRW App (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 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, which are documented `here `__. - -.. note:: - The prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The `HPC-Stack `__ repository assembles these prerequisite libraries. The HPC-Stack has already been built on `preconfigured (Level 1) platforms `__. However, it must be built on other systems. See the :doc:`HPC-Stack Documentation ` for details on installing the HPC-Stack. - - -.. _TopLevelDirStructure: - -Directory Structure ----------------------- -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 (see :numref:`Section %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 - ├── (build) - ├── docs - │ └── UsersGuide - ├── etc - ├── (exec) - ├── (include) - ├── jobs - ├── (lib) - ├── manage_externals - ├── modulefiles - ├── parm - ├── (share) - ├── scripts - ├── sorc - │ ├── CMakeLists.txt - │ ├── (gsi) - │ ├── (rrfs_utl) - │ ├── (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 - ├── tests/WE2E - ├── ush - │ ├── bash_utils - │ ├── machine - │ ├── Python - │ ├── python_utils - │ ├── test_data - │ └── wrappers - └── versions - -SRW App SubDirectories -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:numref:`Table %s ` describes the contents of the most important subdirectories. :numref:`Table %s ` provides an in-depth explanation of the ``ufs-srweather-app`` directories. - -.. _Subdirectories: - -.. table:: Subdirectories of the regional workflow - - +-------------------------+----------------------------------------------------+ - | **Directory Name** | **Description** | - +=========================+====================================================+ - | jobs | J-job scripts launched by Rocoto | - +-------------------------+----------------------------------------------------+ - | modulefiles | Files used to load modules needed for building and | - | | running the workflow | - +-------------------------+----------------------------------------------------+ - | scripts | Scripts launched by the J-jobs | - +-------------------------+----------------------------------------------------+ - | tests | Tests for baseline experiment configurations | - +-------------------------+----------------------------------------------------+ - | ush | Utility scripts used by the workflow | - +-------------------------+----------------------------------------------------+ - -.. _ExperimentDirSection: - -Experiment Directory Structure --------------------------------- -When the user generates an experiment using the ``generate_FV3LAM_wflow.py`` script (:numref:`Step %s `), a user-defined experiment directory (``$EXPTDIR``) is created based on information specified in the ``config.yaml`` file. :numref:`Table %s ` shows the contents of the experiment directory before running the experiment workflow. - -.. _ExptDirStructure: - -.. table:: Files and subdirectory initially created in the experiment directory - :widths: 33 67 - - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | **File Name** | **Description** | - +===========================+==============================================================================================================+ - | config.yaml | User-specified configuration file, see :numref:`Section %s ` | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | data_table | :term:`Cycle-independent` input file (empty) | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | field_table | :term:`Tracers ` in the `forecast model | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | input.nml | :term:`Namelist` for the `UFS Weather Model | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | launch_FV3LAM_wflow.sh | Symlink to the ``ufs-srweather-app/ush/launch_FV3LAM_wflow.sh`` shell script, | - | | which can be used to (re)launch the Rocoto workflow. | - | | Each time this script is called, it appends information 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.py``) | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | nems.configure | See `NEMS configuration file | - | | `__ | - +---------------------------+--------------------------------------------------------------------------------------------------------------+ - | suite_{CCPP}.xml | :term:`CCPP` suite definition file (:term:`SDF`) 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, running the SRW App in *community* mode creates the ``fix_am`` and ``fix_lam`` directories (see :numref:`Table %s `) 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 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 symlinks | - | | 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 Rocoto workflow is launched, several files and directories are generated. A log file named ``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_lbcs``) are preprocessing tasks, and these tasks also result in the creation of new files and subdirectories, 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 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 in the ``config.yaml`` file, more than one cycle | - | | directory will be created under the experiment directory. | - +---------------------------+--------------------------------------------------------------------+ - | 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 by its | - | | various tasks. View the files in this directory to determine 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 | The ``launch_FV3LAM_wflow.sh`` script appends its output to this | - | | log file each time it is called. View the last several | - | | 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/BackgroundInformation/index.rst b/docs/UsersGuide/source/BackgroundInformation/index.rst deleted file mode 100644 index 3aead7b5de..0000000000 --- a/docs/UsersGuide/source/BackgroundInformation/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. UFS SR Weather App Users Guide, created by - sphinx-quickstart on Tue Feb 12 08:48:32 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Background Information -========================= - -.. toctree:: - :maxdepth: 3 - - - Introduction - TechnicalOverview - Components diff --git a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst index 2198ce10c4..eca1067baa 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst @@ -1,8 +1,8 @@ .. _VXCases: -============================ -Verification Sample Cases -============================ +=================================== +METplus Verification Sample Cases +=================================== Introduction =============== diff --git a/docs/UsersGuide/source/BuildingRunningTesting/index.rst b/docs/UsersGuide/source/BuildingRunningTesting/index.rst index c002306038..189e458f7f 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/index.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/index.rst @@ -1,8 +1,3 @@ -.. UFS SR Weather App Users Guide, created by - sphinx-quickstart on Tue Feb 12 08:48:32 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Building, Running, and Testing the SRW App ============================================ diff --git a/docs/UsersGuide/source/Reference/index.rst b/docs/UsersGuide/source/Reference/index.rst index df3659a4d6..a62993b625 100644 --- a/docs/UsersGuide/source/Reference/index.rst +++ b/docs/UsersGuide/source/Reference/index.rst @@ -1,10 +1,5 @@ -.. UFS SR Weather App Users Guide, created by - sphinx-quickstart on Tue Feb 12 08:48:32 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -UFS Short-Range Weather App Users Guide -======================================= +Reference +============ .. toctree:: :maxdepth: 3 diff --git a/docs/UsersGuide/source/TechnicalDetails/index.rst b/docs/UsersGuide/source/TechnicalDetails/index.rst index dab9e02a3e..260c073595 100644 --- a/docs/UsersGuide/source/TechnicalDetails/index.rst +++ b/docs/UsersGuide/source/TechnicalDetails/index.rst @@ -1,8 +1,3 @@ -.. UFS SR Weather App Users Guide, created by - sphinx-quickstart on Tue Feb 12 08:48:32 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Technical Details ==================== diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index f05161daa0..95c0c525ba 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -11,7 +11,7 @@ UFS Short-Range Weather App Users Guide :maxdepth: 3 - BackgroundInformation/index + BackgroundInfo/index BuildingRunningTesting/index TechnicalDetails/index Reference/index From e778e1bf4603335bb8af7b5f32a2e1de300eec2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 6 Jul 2023 17:13:33 -0400 Subject: [PATCH 007/116] edit tables, add component info --- .../source/BackgroundInfo/Components.rst | 179 ++++++++++ .../source/BackgroundInfo/Introduction.rst | 154 +++++++++ .../BackgroundInfo/TechnicalOverview.rst | 327 ++++++++++++++++++ .../source/BackgroundInfo/index.rst | 10 + 4 files changed, 670 insertions(+) create mode 100644 docs/UsersGuide/source/BackgroundInfo/Components.rst create mode 100644 docs/UsersGuide/source/BackgroundInfo/Introduction.rst create mode 100644 docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst create mode 100644 docs/UsersGuide/source/BackgroundInfo/index.rst diff --git a/docs/UsersGuide/source/BackgroundInfo/Components.rst b/docs/UsersGuide/source/BackgroundInfo/Components.rst new file mode 100644 index 0000000000..1b86a543cd --- /dev/null +++ b/docs/UsersGuide/source/BackgroundInfo/Components.rst @@ -0,0 +1,179 @@ +.. _Components: + +============================ +SRW Application Components +============================ + +The SRW Application assembles a variety of components, including: + +* Pre-processor Utilities & Initial Conditions +* 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 the `GitHub Discussions `__ forum. + +.. _Utils: + +UFS Preprocessing Utilities (UFS_UTILS) +========================================== + +The SRW Application includes a number of pre-processing utilities (UFS_UTILS) that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), these utilities 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 :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3`-:term:`LAM`. Additional information about the UFS pre-processor utilities can be found in the `UFS_UTILS Technical Documentation `__ and in the `UFS_UTILS Scientific Documentation `__. + +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 `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 (:term:`LAM`) capability (:cite:t:`BlackEtAl2021`). The :term:`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 accessed `here `__. + +Supported model resolutions in this release include 3-, 13-, and 25-km predefined contiguous U.S. (:term:`CONUS`) domains, each with 127 vertical levels. Preliminary tools for users to define their own domain are also available in the release with full, formal support of these tools to be provided in future releases. The Extended Schmidt Gnomonic (ESG) grid is used with the FV3-LAM, which features relatively uniform grid cells across the entirety of the domain. Additional information about the FV3 dynamical core can be found in the `scientific documentation `__, the `technical documentation `__, and on the `NOAA Geophysical Fluid Dynamics Laboratory website `__. + +Model Physics +--------------- + +The Common Community Physics Package (CCPP), described `here `__, 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 most recent SRW App release (v2.1.0) included four supported physics suites, and a fifth has since been added: FV3_RRFS_v1beta, FV3_GFS_v16, FV3_WoFS_v0, FV3_HRRR, and FV3_RAP (new!). The FV3_RRFS_v1beta physics suite is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (:term:`RRFS`) planned for 2023-2024, and the FV3_GFS_v16 is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. A detailed list of CCPP updates since the SRW App v2.0.0 release is available :ref:`here `. A full scientific description of CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. Additionally, a CCPP single-column model (`CCPP-SCM `__) option has also been developed as a child repository. Users can refer to the `CCPP Single Column Model User and Technical Guide `__ for more details. This CCPP-SCM user guide contains a Quick Start Guide with instructions for obtaining the code, compiling, and running test cases, which include five standard test cases and two additional FV3 replay cases (refer to section 5.2 in the CCPP-SCM user guide for more details). Moreover, the CCPP-SCM supports a precompiled version in a docker container, allowing it to be easily executed on NOAA's cloud computing platforms without any issues (see section 2.5 in the CCPP-SCM user guide for more details). + +.. note:: + SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which physics suite definition file (:term:`SDF`) is chosen when turning this option on. Among the supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. + +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. + +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 App, the UPP converts model output data from the model's native :term:`netCDF` format 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). + +.. _MetplusComponent: + +METplus Verification Suite +============================= + +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. + +The METplus verification framework 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) `__. + +METplus *installation* is not included as part of the build process for the most recent release of the SRW App. However, METplus is preinstalled on many `Level 1 & 2 `__ systems; existing builds can be viewed `here `__. + +METplus can be installed on other systems individually or as part of :term:`HPC-Stack` installation. Users on systems without a previous installation of METplus can follow the `MET Installation Guide `__ and `METplus Installation Guide `__ 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. + +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. + +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 (which include conventional point-based surface and upper-air data) in `prepBUFR format `__ 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 (:term:`EMC`), and it is open to community contributions. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. + +AQM Utilities +=============== + +https://github.com/NOAA-EMC/AQM-utils + +NOAA Emission and Exchange Unified System (NEXUS) +=================================================== + +https://github.com/noaa-oar-arl/NEXUS + +Gridpoint Statistical Interpolation (GSI) +============================================ + +https://github.com/NOAA-EMC/GSI + + +The Gridpoint Statistical Interpolation (GSI) system is a variational data assimilation (DA) system that provides , designed to be flexible, state-of-art, and run efficiently on various parallel computing platforms. The GSI system is in the public domain and is freely available for community use. + +GSI is an operational data assimilation system available for community use. Some of these GSI advanced features are: + +Combined with an ensemble system, GSI can be used as an 3D/4D ensemble-variational hybrid data assimilation system. +GSI features capabilities for observation sensitivity calculation. GSI can be used as an observation operator to provide O-B for the EnKF system or other data analysis systems. +For a complete list of capabilities, please see the GSI User's Guide. + +In the future, GSI may be phased out in favor of :term:`JEDI`, and the UFS community welcomes contributions that will facilitate this shift! + + +RRFS Utilities +================ + +The Rapid Refresh Forecast System (RRFS) utilities (rrfs_utl) are a set of tools that that perform tasks required for implementing RRFS capabilities in the SRW App. For example, rrfs_utl performs preprocessing for lightning data, METAR cloud observations, NASA LaRC cloud products, and the NSSL radar reflectivity mosaic. It also provides cloud analysis for the FV3 dycore and radar reflectivity to temperature tendency conversions. For more information on RRFS Utilities, visit the GitHub repository at https://github.com/NOAA-GSL/rrfs_utl or see :numref:`Table %s ` for a detailed description of exeutables. + +.. _rrfs-utl-executables: + +.. list-table:: *rrfs_utl executables* + :widths: 20 50 + :header-rows: 1 + + * - Executable + - Description + * - gsi.x* + - Runs the Gridpoint Statistical Interpolation (GSI). + * - enkf.x* + - Runs the Ensemble Kalman Filter. + * - gen_annual_maxmin_GVF.exe* + - Generate maximum and minimum GVF files based on yearly long GVF observations for update_GVF process. + * - update_GVF.exe* + - Update the greenness vegetation fraction (GVF) in the surface file based on the real-time observations files. + * - ref2tten.exe* + - Calculate temperature tendency based on the radar reflectivity observation at each grid point. This temperature tendency can be used by the model during integration as latent heating initialization for ongoing precipitation systems, especially convection. + * - update_ice.exe* + - Replace ice fields in warm start surface files based on the forecast from cold start forecast using the GFS as the initial file. + * - process_updatesst.exe* + - Update SST field based on the SST analysis from NCEP. + * - check_imssnow_fv3lam.exe* + - This is a tool used to read snow and ice fields from surface files and check that field. + * - gen_cs.exe* + - NCL scripts to do cross section plotting + * - lakesurgery.exe* + - Replace the existing lake depth with the GLOBathy bathymetry. It is designed to work with the HRRR model. + * - process_imssnow_fv3lam.exe* + - Use FV3LAM snow and ice fields based on the snow and ice information from imssnow. + * - gen_ensmean_recenter.exe* + - Runs the ensemble mean/recentering calculation for FV3LAM ensemble files. + * - update_bc.exe* + - Adjust 0-h boundary conditions based on the analysis results during data assimilation cycling. + * - adjust_soiltq.exe* + - Use the lowest level temperature and moisture analysis increments to adjust the soil moisture and soil temperature after analysis. + * - process_NSSL_mosaic.exe* + - Process NSSL MRMS radar reflectivity mosaic observations: read 33 level NSSL MRMS radar reflectivity grib2 files and then interpolate the reflectivity horizontally to the ESG grid. + * - use_raphrrr_sfc.exe* + - Use RAP and HRRR surface fields to replace the surface fields in FV3LAM. This is only used for starting the RRFS surface cycling. + * - process_Lightning.exe* + - Processes lightning data: read NLDN NetCDF observation files and map the lightning observations into FV3LAM ESG grid. + * - process_larccld.exe* + - Process NASA Langley cloud top product: reads the cloud top pressure, temperature, etc and maps them to the ESG grid. + * - process_metarcld.exe* + - Process METAR ceilometers cloud observations: reads the cloud base and coverage observations from PrepBUFR and distributes the cloud observations/weather/visibility observations to the ESG grid. + * - fv3lam_nonvarcldana.exe* + - Runs the non-variational cloud and precipitable hydrometeor analysis based on the METAR cloud observations, satellite retrieved cloud top products, and radar reflectivity. + +Unified Workflow Tools +======================== + +The Unified Workflow (UW) is a set of tools intended to unify the workflow for various UFS applications under one framework. The UW toolkit currently includes templater and config tools, which have been incorporated into the SRW App workflow and will soon be incorporated into other UFS repositories. Additional tools are under development. More details about the UW can be found in the `workflow-tools `__ GitHub repository and in the `UW Documentation `__. + +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. This build system collects the components necessary for running the end-to-end SRW Application, including the UFS Weather Model and the pre- and post-processing software. Additional libraries necessary for the application (e.g., :term:`NCEPLIBS-external` and :term:`NCEPLIBS`) are not included in the SRW Application build system but are available pre-built on pre-configured platforms. On other systems, they can be installed via the HPC-Stack (see :doc:`HPC-Stack Documentation `). There is a small set of system libraries and utilities that are assumed to be present on the target computer: the CMake build software; a Fortran, C, and C++ compiler; and an :term:`MPI` library. + +Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see :numref:`Chapter %s ` or the `Rocoto documentation `__ for more information on Rocoto and workflow management). 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 SRW Application allows users to configure various elements of the workflow. For example, users can modify the parameters of the atmospheric model, such as start and end dates, duration, integration time step, and the physics suite used for the simulation. It also allows for configuration of other elements of the workflow; for example, users can choose whether to run some or all of the pre-processing, forecast model, and post-processing steps. More information on how to configure the workflow is available in :numref:`Section %s `. + +An optional Python plotting task is also included to create basic visualizations of the model output. The task outputs graphics in PNG format for several standard meteorological variables on the pre-defined :term:`CONUS` domain. A difference plotting option is also included to visually compare two runs for the same domain and resolution. These plots may be used to perform a visual check to verify that the application is producing reasonable results. Configuration instructions are provided in :numref:`Section %s `. + +The SRW Application has been tested on a variety of platforms widely used by researchers, including NOAA High-Performance Computing (HPC) systems (e.g., Hera, Orion, Jet); the National Center for Atmospheric Research (:term:`NCAR`) Cheyenne system; cloud environment, 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 (Level 3), and build-only (Level 4) platforms. + +Preconfigured (Level 1) systems already have the required external libraries available in a central location (via :term:`HPC-Stack` or :term:`spack-stack`). 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. + +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. Users will need to install the required libraries as part of the :ref:`SRW Application build ` process. Applications and models are expected to build and run once the required libraries are built. Release testing is conducted on these systems to ensure that the SRW App runs smoothly there. + +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. 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. + +On all platforms, the SRW App can be :ref:`run within a container ` that includes the prerequisite software. + +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 `__. + diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst new file mode 100644 index 0000000000..e7b5776800 --- /dev/null +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -0,0 +1,154 @@ +.. _Introduction: + +============== +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` (including 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 most recent SRW Application 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 the `GitHub Discussions `__ forum. The SRW App also includes support for a verification package (METplus) for both deterministic and ensemble simulations and support for four stochastically perturbed physics schemes. + +Since the v2.1.0 release, developers have added a variety of features: + + * Bug fixes since the v2.1.0 release + * Rapid Refresh Forecast System (RRFS) capabilities + * Air Quality Modeling (AQM) capabilities + * Updates to :term:`CCPP` that target the top of the ``main`` branch (which is ahead of CCPP v6.0.0). See :ref:`this page ` for a detailed summary of updates that came in ahead of the v2.1.0 release. + * Support for the :term:`UPP` inline post option (see :ref:`here `) + * Documentation updates to reflect the changes above + +The SRW App v2.1.0 citation is as follows and should be used when presenting results based on research conducted with the App: + +UFS Development Team. (2022, Nov. 17). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.1.0). Zenodo. https://doi.org/10.5281/zenodo.7277602 + +User's Guide Organization +============================ + +The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Technical Information*; and *Reference*. + +.. hint:: + * To get started with the SRW App, users can try one of the following options: + + #. View :numref:`Chapter %s ` for a quick overview of the workflow steps. + #. To build the application in a container, which provides a more uniform work environment, users can refer to the :ref:`Container-Based Quick Start Guide `. + #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Chapter %s: Building the SRW App ` and :numref:`Chapter %s: Running the SRW App `. + +Background Information +------------------------- + + * This **Introduction** chapter explains how the SRW App documentation is organized, how to use this guide, and where to find user support/documentation. + * :numref:`Chapter %s: Technical Overview ` provides a technical overview, including SRW App prerequisites, code overview/directory structure, and summary of components. + * :numref:`Chapter %s: Components ` provides a more detailed description of the application components, including optional application components. + +Building, Running, and Testing the SRW App +-------------------------------------------- + + * :numref:`Chapter %s: Quick Start Guide ` is designed for use on `Level 1 systems `__ or as an overview of the workflow. + * :numref:`Chapter %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers come with SRW App prerequisites already installed and run on a broad range of systems. + * :numref:`Chapter %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. + * :numref:`Chapter %s: Running the SRW App ` provides a *detailed* explanation of how to run the App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. + * :numref:`Chapter %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. + * :numref:`Chapter %s: Workflow End-to-End (WE2E) Tests ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. + * :numref:`Chapter %s: METplus Verification Sample Cases ` explains how to run METplus verification as part of the workflow. + * :numref:`Chapter %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this chapter is a starting point for those interested in AQM. + +Technical Information for Users +--------------------------------- + + * :numref:`Chapter %s: Workflow Parameters ` documents all of the user-configurable experiment parameters that can be set in ``config.yaml``. + * :numref:`Chapter %s: Input & Output Files ` describes application input and output files, as well as information on where to get publicly available data. + * :numref:`Chapter %s: Limited Area Model (LAM) Grids ` describes the SRW App predefined grids in detail and explains how to create a custom user-generated grid. + * :numref:`Chapter %s: Defining an SRW App Workflow ` explains how to build or alter the SRW App workflow XML file. + * :numref:`Chapter %s: Template Variables ` explains how to use template variables. + +Reference Information +----------------------- + + * :numref:`Chapter %s: Rocoto Introductory Information ` provides an introduction to standard Rocoto commands with examples. + * :numref:`Chapter %s: FAQ ` answers users' frequently asked questions. + * :numref:`Chapter %s: Glossary ` defines important terms related to the SRW App. + + +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 `GitHub Discussions `__ forum. + +.. code-block:: console + + Throughout the guide, this presentation style indicates shell commands and options, code examples, etc. + +Variables presented as ``AaBbCc123`` in this User's Guide typically refer to variables in scripts, names of files, or directories. + +File paths and code that include angle brackets (e.g., ``build__``) indicate that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). + +User Support, Documentation, and Contributions to Development +=============================================================== + +The SRW App's `GitHub Discussions `__ forum provides online support 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 | https://ufs-srweather-app.readthedocs.io/en/develop/ | + | User's Guide | | + +----------------------------+---------------------------------------------------------------------------------+ + | UFS_UTILS Technical | https://noaa-emcufs-utils.readthedocs.io/en/latest | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | UFS_UTILS Scientific | https://ufs-community.github.io/UFS_UTILS/index.html | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | UFS Weather Model | https://ufs-weather-model.readthedocs.io/en/latest | + | User's Guide | | + +----------------------------+---------------------------------------------------------------------------------+ + | HPC-Stack Documentation | https://hpc-stack.readthedocs.io/en/latest/ | + +----------------------------+---------------------------------------------------------------------------------+ + | spack-stack Documentation | https://spack-stack.readthedocs.io/en/latest/ | + +----------------------------+---------------------------------------------------------------------------------+ + | FV3 Scientific | https://repository.library.noaa.gov/view/noaa/30725 | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | FV3 Technical | https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | CCPP Scientific | https://dtcenter.ucar.edu/GMTB/v6.0.0/sci_doc/index.html | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | CCPP Technical | https://ccpp-techdoc.readthedocs.io/en/latest/ | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | Stochastic Physics | https://stochastic-physics.readthedocs.io/en/latest/ | + | Documentation | | + +----------------------------+---------------------------------------------------------------------------------+ + | ESMF manual | https://earthsystemmodeling.org/docs/release/latest/ESMF_usrdoc/ | + +----------------------------+---------------------------------------------------------------------------------+ + | Unified Post Processor | https://upp.readthedocs.io/en/latest/ | + +----------------------------+---------------------------------------------------------------------------------+ + | Unified Workflow | https://unified-workflow.readthedocs.io/en/latest/ | + +----------------------------+---------------------------------------------------------------------------------+ + +The UFS community is encouraged to contribute to the development effort of all related +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 into the authoritative repositories, users must follow the code management rules of each UFS component repository. These rules are usually outlined in the User's Guide (see :numref:`Table %s `) or wiki for each respective repository (see :numref:`Table %s `). Contributions to the `ufs-srweather-app `__ repository should follow the guidelines contained in the `SRW App Contributor's Guide `__. + +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: + +* 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. + + +.. bibliography:: ../references.bib + + + diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst new file mode 100644 index 0000000000..6c6327c225 --- /dev/null +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -0,0 +1,327 @@ +.. _TechOverview: + +==================== +Technical Overview +==================== + +This chapter provides information on SRW App prerequistes, code repositories, and directory structure. + +.. _SRWPrerequisites: + +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 (concepts of parameterizations: physical, microphysical, convective) +* Meteorology (in particular, meteorology at the scales being predicted: 25km, 13km, and 3km resolutions) + +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. SRW App `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 + +* >82 GB disk space + + * 53 GB input data for a standard collection of global data, or "fix" file data (topography, climatology, observational data) for a short 12-hour test forecast on the :term:`CONUS` 25km domain. See data download instructions in :numref:`Section %s `. + * 8 GB for full :term:`HPC-Stack` installation + * 3 GB for ``ufs-srweather-app`` installation + * 1 GB for boundary conditions for a short 12-hour test forecast on the CONUS 25km domain. See data download instructions in :numref:`Section %s `. + * 17 GB for a 12-hour test forecast on the CONUS 25km domain, with model output saved hourly. + +* Fortran compiler released since 2018 + + * 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, LLVM clang, GNU) 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 v2.12+ + +* curl + +* wget + +* Lmod + + +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.20+ + +* :term:`MPI` (MPICH, OpenMPI, or other implementation) + + * Only **MPICH** or **OpenMPI** can be built with HPC-Stack. Other implementations must be installed separately by the user (if desired). + +For MacOS systems, some additional software packages are needed. When possible, it is recommended that users install and/or upgrade this software (along with software listed above) using the `Homebrew `__ package manager for MacOS. See :doc:`HPC-Stack Documentation: Chapter 3 ` and :numref:`Chapter %s ` for further guidance on installing these prerequisites on MacOS. + +* bash v4.x +* GNU compiler suite v11 or higher with gfortran +* cmake +* make +* coreutils +* gsed + +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 + +.. _SRWStructure: + +Code Repositories and Directory Structure +========================================= + +.. _HierarchicalRepoStr: + +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 tags the appropriate versions of the external repositories associated with the SRW App (see :numref:`Table %s `). + +.. _top_level_repos: + +.. list-table:: List of top-level repositories that comprise the UFS SRW Application + :widths: 20 40 + :header-rows: 1 + + * - Repository Description + - Authoritative repository URL + * - Umbrella repository for the UFS Short-Range Weather (SRW) Application + - https://github.com/ufs-community/ufs-srweather-app + * - Repository for the UFS Weather Model + - https://github.com/ufs-community/ufs-weather-model + * - Repository for UFS Utilities, including pre-processing, chgres_cube, and more + - https://github.com/ufs-community/UFS_UTILS + * - Repository for the Unified Post Processor (UPP) + - https://github.com/NOAA-EMC/UPP + * - Repository for Air Quality Modeling (AQM) Utilities + - https://github.com/NOAA-EMC/AQM-utils + * - Repository for NEXUS + - https://github.com/noaa-oar-arl/NEXUS + * - Repository for Gridpoint Statistical Interpolation (GSI) + - https://github.com/NOAA-EMC/GSI + * - Repository for Rapid Refresh Forecast System (RRFS) Utilities + - https://github.com/NOAA-GSL/rrfs_utl + * - Repository for the Unified Workflow (UW) Toolkit + - https://github.com/ufs-community/workflow-tools + +The UFS Weather Model contains a number of sub-repositories, which are documented `here `__. + +.. note:: + The prerequisite libraries (including NCEP Libraries and external libraries) are not included in the UFS SRW Application repository. The `HPC-Stack `__ repository assembles these prerequisite libraries. The HPC-Stack has already been built on `preconfigured (Level 1) platforms `__. However, it must be built on other systems. See the :doc:`HPC-Stack Documentation ` for details on installing the HPC-Stack. + + +.. _TopLevelDirStructure: + +Directory Structure +---------------------- +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 (see :numref:`Section %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 + ├── (build) + ├── docs + │ └── UsersGuide + ├── etc + ├── (exec) + ├── (include) + ├── jobs + ├── (lib) + ├── manage_externals + ├── modulefiles + ├── parm + ├── (share) + ├── scripts + ├── sorc + │ ├── CMakeLists.txt + │ ├── (gsi) + │ ├── (rrfs_utl) + │ ├── (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 + ├── tests/WE2E + ├── ush + │ ├── bash_utils + │ ├── machine + │ ├── Python + │ ├── python_utils + │ ├── test_data + │ └── wrappers + └── versions + +SRW App SubDirectories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:numref:`Table %s ` describes the contents of the most important subdirectories. :numref:`Table %s ` provides an in-depth explanation of the ``ufs-srweather-app`` directories. + +.. _Subdirectories: + +.. table:: Subdirectories of the regional workflow + + +-------------------------+----------------------------------------------------+ + | **Directory Name** | **Description** | + +=========================+====================================================+ + | jobs | J-job scripts launched by Rocoto | + +-------------------------+----------------------------------------------------+ + | modulefiles | Files used to load modules needed for building and | + | | running the workflow | + +-------------------------+----------------------------------------------------+ + | scripts | Scripts launched by the J-jobs | + +-------------------------+----------------------------------------------------+ + | tests | Tests for baseline experiment configurations | + +-------------------------+----------------------------------------------------+ + | ush | Utility scripts used by the workflow | + +-------------------------+----------------------------------------------------+ + +.. _ExperimentDirSection: + +Experiment Directory Structure +-------------------------------- +When the user generates an experiment using the ``generate_FV3LAM_wflow.py`` script (:numref:`Step %s `), a user-defined experiment directory (``$EXPTDIR``) is created based on information specified in the ``config.yaml`` file. :numref:`Table %s ` shows the contents of the experiment directory before running the experiment workflow. + +.. _ExptDirStructure: + +.. table:: Files and subdirectory initially created in the experiment directory + :widths: 33 67 + + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | **File Name** | **Description** | + +===========================+==============================================================================================================+ + | config.yaml | User-specified configuration file, see :numref:`Section %s ` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | data_table | :term:`Cycle-independent` input file (empty) | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | field_table | :term:`Tracers ` in the `forecast model | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | FV3LAM_wflow.xml | Rocoto XML file to run the workflow | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | input.nml | :term:`Namelist` for the `UFS Weather Model | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | launch_FV3LAM_wflow.sh | Symlink to the ``ufs-srweather-app/ush/launch_FV3LAM_wflow.sh`` shell script, | + | | which can be used to (re)launch the Rocoto workflow. | + | | Each time this script is called, it appends information 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.py``) | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | nems.configure | See `NEMS configuration file | + | | `__ | + +---------------------------+--------------------------------------------------------------------------------------------------------------+ + | suite_{CCPP}.xml | :term:`CCPP` suite definition file (:term:`SDF`) 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, running the SRW App in *community* mode creates the ``fix_am`` and ``fix_lam`` directories (see :numref:`Table %s `) 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 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 symlinks | + | | 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 Rocoto workflow is launched, several files and directories are generated. A log file named ``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_lbcs``) are preprocessing tasks, and these tasks also result in the creation of new files and subdirectories, 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 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 in the ``config.yaml`` file, more than one cycle | + | | directory will be created under the experiment directory. | + +---------------------------+--------------------------------------------------------------------+ + | 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 by its | + | | various tasks. View the files in this directory to determine 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 | The ``launch_FV3LAM_wflow.sh`` script appends its output to this | + | | log file each time it is called. View the last several | + | | 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/BackgroundInfo/index.rst b/docs/UsersGuide/source/BackgroundInfo/index.rst new file mode 100644 index 0000000000..07e787bc00 --- /dev/null +++ b/docs/UsersGuide/source/BackgroundInfo/index.rst @@ -0,0 +1,10 @@ +Background Information +========================= + +.. toctree:: + :maxdepth: 3 + + + Introduction + TechnicalOverview + Components From c2a772a5f1637f643986282ebe0d0d35a3f899d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 7 Jul 2023 13:13:03 -0400 Subject: [PATCH 008/116] add info on components --- .../source/BackgroundInfo/Components.rst | 60 +++++++++---------- docs/UsersGuide/source/Reference/Glossary.rst | 5 ++ docs/UsersGuide/source/references.bib | 10 ++++ 3 files changed, 42 insertions(+), 33 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Components.rst b/docs/UsersGuide/source/BackgroundInfo/Components.rst index 1b86a543cd..eaf61906c2 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Components.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Components.rst @@ -68,41 +68,35 @@ Among other techniques, MET provides the capability to compute standard verifica METplus is being actively developed by :term:`NCAR`/Research Applications Laboratory (RAL), NOAA/Earth Systems Research Laboratories (ESRL), and NOAA/Environmental Modeling Center (:term:`EMC`), and it is open to community contributions. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. -AQM Utilities -=============== +Air Quality Modeling (AQM) Utilities +======================================= -https://github.com/NOAA-EMC/AQM-utils +For more information on AQM Utilities (AQM-utils), visit the GitHub repository at https://github.com/NOAA-EMC/AQM-utils. -NOAA Emission and Exchange Unified System (NEXUS) +NOAA Emission and eXchange Unified System (NEXUS) =================================================== -https://github.com/noaa-oar-arl/NEXUS +The NOAA Emission and eXchange Unified System (NEXUS) is an emissions processing system developed at the NOAA Air Resources Laboratory (ARL) for use with regional and global UFS atmospheric composition models. NEXUS provides a streamlined process to include new emissions inventories quickly and can flexibly blend different emissions datasets. NEXUS incorporates the :term:`ESMF`-compliant Harmonized Emissions Component (`HEMCO `__), which "comput[es] emissions from a user-selected ensemble of emission inventories and algorithms" and "allows users to re-grid, combine, overwrite, subset, and scale emissions from different inventories through a configuration file and with no change to the model source code" (:cite:t:`LinEtAl2021`). + +For more information on NEXUS, visit the GitHub repository at https://github.com/noaa-oar-arl/NEXUS. Gridpoint Statistical Interpolation (GSI) ============================================ -https://github.com/NOAA-EMC/GSI - - -The Gridpoint Statistical Interpolation (GSI) system is a variational data assimilation (DA) system that provides , designed to be flexible, state-of-art, and run efficiently on various parallel computing platforms. The GSI system is in the public domain and is freely available for community use. - -GSI is an operational data assimilation system available for community use. Some of these GSI advanced features are: - -Combined with an ensemble system, GSI can be used as an 3D/4D ensemble-variational hybrid data assimilation system. -GSI features capabilities for observation sensitivity calculation. GSI can be used as an observation operator to provide O-B for the EnKF system or other data analysis systems. -For a complete list of capabilities, please see the GSI User's Guide. +The Gridpoint Statistical Interpolation (GSI) system is a variational :term:`data assimilation` (DA) system that provides 3DVar DA capabilities for the SRW App. It takes a set of observations along with an initial 6-hour forecast from the SRW App and generates an "analysis," which combines the forecast results with observational data to generate a starting point for a new regional forecast. -In the future, GSI may be phased out in favor of :term:`JEDI`, and the UFS community welcomes contributions that will facilitate this shift! +GSI is also capable of providing 3D ensemble-variational (3DEnVar) DA, as well as 4D (hourly) variational (4DVar) and ensemble-variational (4DEnVar) DA, but these features have not yet been incorporated into the SRW App. +In the future, GSI may be phased out in favor of :term:`JEDI`, and the UFS community welcomes contributions that will facilitate this shift! In the meantime, users can find more information about GSI on GitHub at https://github.com/NOAA-EMC/GSI. RRFS Utilities ================ -The Rapid Refresh Forecast System (RRFS) utilities (rrfs_utl) are a set of tools that that perform tasks required for implementing RRFS capabilities in the SRW App. For example, rrfs_utl performs preprocessing for lightning data, METAR cloud observations, NASA LaRC cloud products, and the NSSL radar reflectivity mosaic. It also provides cloud analysis for the FV3 dycore and radar reflectivity to temperature tendency conversions. For more information on RRFS Utilities, visit the GitHub repository at https://github.com/NOAA-GSL/rrfs_utl or see :numref:`Table %s ` for a detailed description of exeutables. +The Rapid Refresh Forecast System (RRFS) Utilities (rrfs_utl) are a set of tools that that perform tasks required for implementing RRFS capabilities in the SRW App. For example, rrfs_utl performs preprocessing for lightning data, METAR cloud observations, NASA LaRC cloud products, and the NSSL radar reflectivity mosaic. It also provides cloud analysis for the FV3 dycore and radar reflectivity to temperature tendency conversions. For more information on RRFS Utilities, visit the GitHub repository at https://github.com/NOAA-GSL/rrfs_utl or see :numref:`Table %s ` for a detailed description of executables. .. _rrfs-utl-executables: -.. list-table:: *rrfs_utl executables* +.. list-table:: *rrfs_utl Executables* :widths: 20 50 :header-rows: 1 @@ -113,39 +107,39 @@ The Rapid Refresh Forecast System (RRFS) utilities (rrfs_utl) are a set of tools * - enkf.x* - Runs the Ensemble Kalman Filter. * - gen_annual_maxmin_GVF.exe* - - Generate maximum and minimum GVF files based on yearly long GVF observations for update_GVF process. + - Generates maximum and minimum greenness vegetation fraction (GVF) files based on year-long GVF observations for update_GVF process. * - update_GVF.exe* - - Update the greenness vegetation fraction (GVF) in the surface file based on the real-time observations files. + - Updates the GVF in the surface file based on the real-time observation files. * - ref2tten.exe* - - Calculate temperature tendency based on the radar reflectivity observation at each grid point. This temperature tendency can be used by the model during integration as latent heating initialization for ongoing precipitation systems, especially convection. + - Calculates temperature tendency based on the radar reflectivity observation at each grid point. This temperature tendency can be used by the model during integration as latent heating initialization for ongoing precipitation systems, especially convection. * - update_ice.exe* - - Replace ice fields in warm start surface files based on the forecast from cold start forecast using the GFS as the initial file. + - Replaces ice fields in warm-start surface files based on previous cold-start forecast results using the GFS as the initial file. * - process_updatesst.exe* - - Update SST field based on the SST analysis from NCEP. + - Updates sea surface temperature (SST) field based on the SST analysis from :term:`NCEP`. * - check_imssnow_fv3lam.exe* - This is a tool used to read snow and ice fields from surface files and check that field. * - gen_cs.exe* - - NCL scripts to do cross section plotting + - NCL scripts to perform cross section plotting * - lakesurgery.exe* - - Replace the existing lake depth with the GLOBathy bathymetry. It is designed to work with the HRRR model. + - Replaces the existing lake depth with the GLOBathy bathymetry. It is designed to work with the HRRR model. * - process_imssnow_fv3lam.exe* - - Use FV3LAM snow and ice fields based on the snow and ice information from imssnow. + - Uses :term:`FV3` :term:`LAM` snow and ice fields based on the snow and ice information from imssnow. * - gen_ensmean_recenter.exe* - Runs the ensemble mean/recentering calculation for FV3LAM ensemble files. * - update_bc.exe* - - Adjust 0-h boundary conditions based on the analysis results during data assimilation cycling. + - Adjusts 0-h boundary conditions based on the analysis results during data assimilation cycling. * - adjust_soiltq.exe* - - Use the lowest level temperature and moisture analysis increments to adjust the soil moisture and soil temperature after analysis. + - Uses the lowest level temperature and moisture analysis increments to adjust the soil moisture and soil temperature after analysis. * - process_NSSL_mosaic.exe* - - Process NSSL MRMS radar reflectivity mosaic observations: read 33 level NSSL MRMS radar reflectivity grib2 files and then interpolate the reflectivity horizontally to the ESG grid. + - Processes NSSL MRMS radar reflectivity mosaic observations. Reads 33 level NSSL MRMS radar reflectivity grib2 files and then interpolates the reflectivity horizontally to the ESG grid. * - use_raphrrr_sfc.exe* - - Use RAP and HRRR surface fields to replace the surface fields in FV3LAM. This is only used for starting the RRFS surface cycling. + - Uses RAP and HRRR surface fields to replace the surface fields in FV3LAM. This is only used for starting the RRFS surface cycling. * - process_Lightning.exe* - - Processes lightning data: read NLDN NetCDF observation files and map the lightning observations into FV3LAM ESG grid. + - Processes lightning data. Reads NLDN NetCDF observation files and maps the lightning observations into the FV3LAM ESG grid. * - process_larccld.exe* - - Process NASA Langley cloud top product: reads the cloud top pressure, temperature, etc and maps them to the ESG grid. + - Processes NASA Langley cloud top product. Reads the cloud top pressure, temperature, etc. and maps them to the ESG grid. * - process_metarcld.exe* - - Process METAR ceilometers cloud observations: reads the cloud base and coverage observations from PrepBUFR and distributes the cloud observations/weather/visibility observations to the ESG grid. + - Processes METAR ceilometers cloud observations. Reads the cloud base and coverage observations from PrepBUFR and distributes the cloud observations/weather/visibility observations to the ESG grid. * - fv3lam_nonvarcldana.exe* - Runs the non-variational cloud and precipitable hydrometeor analysis based on the METAR cloud observations, satellite retrieved cloud top products, and radar reflectivity. diff --git a/docs/UsersGuide/source/Reference/Glossary.rst b/docs/UsersGuide/source/Reference/Glossary.rst index 3dbecebbb2..13e1af277e 100644 --- a/docs/UsersGuide/source/Reference/Glossary.rst +++ b/docs/UsersGuide/source/Reference/Glossary.rst @@ -135,6 +135,11 @@ Glossary J-jobs Scripting layer (contained in ``ufs-srweather-app/jobs/``) that should be directly called for each workflow component (either on the command line or by the workflow manager) to run a specific task in the workflow. The different scripting layers are described in detail in the `NCO Implementation Standards document `__ + JEDI + The Joint Effort for Data assimilation Integration (`JEDI `__) is a unified and versatile data assimilation (DA) system for Earth System Prediction. It aims to enable efficient research and accelerated transition from research to operations by providing a framework that takes into account all components of the Earth system in a consistent manner. The JEDI software package can run on a variety of platforms and for a variety of purposes, and it is designed to readily accommodate new atmospheric and oceanic models and new observation systems. The `JEDI User's Guide `__ contains extensive information on the software. + + JEDI is developed and distributed by the `Joint Center for Satellite Data Assimilation `__, a multi-agency research center hosted by the University Corporation for Atmospheric Research (`UCAR `__). JCSDA is dedicated to improving and accelerating the quantitative use of research and operational satellite data in weather, ocean, climate, and environmental analysis and prediction systems. + LAM Limited Area Model (grid type), formerly known as the "Stand-Alone Regional Model," or SAR. LAM grids use a regional (rather than global) configuration of the :term:`FV3` :term:`dynamical core`. diff --git a/docs/UsersGuide/source/references.bib b/docs/UsersGuide/source/references.bib index 0845ca3fa7..196233b372 100644 --- a/docs/UsersGuide/source/references.bib +++ b/docs/UsersGuide/source/references.bib @@ -12,3 +12,13 @@ @misc{Purser_2020 year = {2020}, howpublished = {Unified Forecast System (UFS) Users’ Workshop}, } + +@article{LinEtAl2021, + title={Harmonized Emissions Component (HEMCO) 3.0 as a versatile emissions component for atmospheric models: Application in the GEOS-Chem, NASA GEOS, WRF-GC, CESM2, NOAA GEFS-Aerosol, and NOAA UFS models}, + author={H. Lin and D.J. Jacob and E.W. Lundgren and M.P. Sulprizio and C.A. Keller and T.M. Fritz and S.D. Eastham and L.K. Emmons and P.C. Campbell and B. Baker and R.D. Saylor, and R. Montuoro}, + journal={Geosci. Model Dev.}, + year={2021}, + volume={14}, + pages={5487–5506}, + doi={10.5194/gmd-14-5487-2021}, + } \ No newline at end of file From 48e6038ecf697d06874c6d942ca2c359886617fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 7 Jul 2023 13:19:38 -0400 Subject: [PATCH 009/116] rename Tech Details section --- docs/UsersGuide/source/TechnicalDetails/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/TechnicalDetails/index.rst b/docs/UsersGuide/source/TechnicalDetails/index.rst index 260c073595..2323bef3b9 100644 --- a/docs/UsersGuide/source/TechnicalDetails/index.rst +++ b/docs/UsersGuide/source/TechnicalDetails/index.rst @@ -1,5 +1,5 @@ -Technical Details -==================== +Tinkering with Workflow Details +================================== .. toctree:: :maxdepth: 3 From 57c8b081f54dbdbc5fa415474bfc549986550ac5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 7 Jul 2023 17:15:13 -0400 Subject: [PATCH 010/116] edit build chapter --- .../source/BackgroundInfo/Components.rst | 51 +---- .../BackgroundInfo/TechnicalOverview.rst | 1 + .../BuildingRunningTesting/BuildSRW.rst | 209 +++++++++--------- 3 files changed, 102 insertions(+), 159 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Components.rst b/docs/UsersGuide/source/BackgroundInfo/Components.rst index eaf61906c2..05c28cf485 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Components.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Components.rst @@ -92,56 +92,7 @@ In the future, GSI may be phased out in favor of :term:`JEDI`, and the UFS commu RRFS Utilities ================ -The Rapid Refresh Forecast System (RRFS) Utilities (rrfs_utl) are a set of tools that that perform tasks required for implementing RRFS capabilities in the SRW App. For example, rrfs_utl performs preprocessing for lightning data, METAR cloud observations, NASA LaRC cloud products, and the NSSL radar reflectivity mosaic. It also provides cloud analysis for the FV3 dycore and radar reflectivity to temperature tendency conversions. For more information on RRFS Utilities, visit the GitHub repository at https://github.com/NOAA-GSL/rrfs_utl or see :numref:`Table %s ` for a detailed description of executables. - -.. _rrfs-utl-executables: - -.. list-table:: *rrfs_utl Executables* - :widths: 20 50 - :header-rows: 1 - - * - Executable - - Description - * - gsi.x* - - Runs the Gridpoint Statistical Interpolation (GSI). - * - enkf.x* - - Runs the Ensemble Kalman Filter. - * - gen_annual_maxmin_GVF.exe* - - Generates maximum and minimum greenness vegetation fraction (GVF) files based on year-long GVF observations for update_GVF process. - * - update_GVF.exe* - - Updates the GVF in the surface file based on the real-time observation files. - * - ref2tten.exe* - - Calculates temperature tendency based on the radar reflectivity observation at each grid point. This temperature tendency can be used by the model during integration as latent heating initialization for ongoing precipitation systems, especially convection. - * - update_ice.exe* - - Replaces ice fields in warm-start surface files based on previous cold-start forecast results using the GFS as the initial file. - * - process_updatesst.exe* - - Updates sea surface temperature (SST) field based on the SST analysis from :term:`NCEP`. - * - check_imssnow_fv3lam.exe* - - This is a tool used to read snow and ice fields from surface files and check that field. - * - gen_cs.exe* - - NCL scripts to perform cross section plotting - * - lakesurgery.exe* - - Replaces the existing lake depth with the GLOBathy bathymetry. It is designed to work with the HRRR model. - * - process_imssnow_fv3lam.exe* - - Uses :term:`FV3` :term:`LAM` snow and ice fields based on the snow and ice information from imssnow. - * - gen_ensmean_recenter.exe* - - Runs the ensemble mean/recentering calculation for FV3LAM ensemble files. - * - update_bc.exe* - - Adjusts 0-h boundary conditions based on the analysis results during data assimilation cycling. - * - adjust_soiltq.exe* - - Uses the lowest level temperature and moisture analysis increments to adjust the soil moisture and soil temperature after analysis. - * - process_NSSL_mosaic.exe* - - Processes NSSL MRMS radar reflectivity mosaic observations. Reads 33 level NSSL MRMS radar reflectivity grib2 files and then interpolates the reflectivity horizontally to the ESG grid. - * - use_raphrrr_sfc.exe* - - Uses RAP and HRRR surface fields to replace the surface fields in FV3LAM. This is only used for starting the RRFS surface cycling. - * - process_Lightning.exe* - - Processes lightning data. Reads NLDN NetCDF observation files and maps the lightning observations into the FV3LAM ESG grid. - * - process_larccld.exe* - - Processes NASA Langley cloud top product. Reads the cloud top pressure, temperature, etc. and maps them to the ESG grid. - * - process_metarcld.exe* - - Processes METAR ceilometers cloud observations. Reads the cloud base and coverage observations from PrepBUFR and distributes the cloud observations/weather/visibility observations to the ESG grid. - * - fv3lam_nonvarcldana.exe* - - Runs the non-variational cloud and precipitable hydrometeor analysis based on the METAR cloud observations, satellite retrieved cloud top products, and radar reflectivity. +The Rapid Refresh Forecast System (RRFS) Utilities (rrfs_utl) are a set of tools that that perform tasks required for implementing RRFS capabilities in the SRW App. For example, rrfs_utl performs preprocessing for lightning data, METAR cloud observations, NASA LaRC cloud products, and the NSSL radar reflectivity mosaic. It also provides cloud analysis for the FV3 dycore and radar reflectivity to temperature tendency conversions. For more information on RRFS Utilities, visit the GitHub repository at https://github.com/NOAA-GSL/rrfs_utl or see :numref:`Table %s ` for a detailed description of executables. Unified Workflow Tools ======================== diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index 6c6327c225..b418e74851 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -30,6 +30,7 @@ Additional background knowledge in the following areas could be helpful: * Containerization * Workflow Managers/Rocoto +.. _software-prereqs: Software/Operating System Requirements ----------------------------------------- diff --git a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst index 33450085f6..6d0528dd44 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst @@ -4,11 +4,11 @@ Building 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 built, users can configure experiments and 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 built (i.e., components are assembled/compiled), users can configure experiments and generate predictions of atmospheric behavior over a limited spatial area and on time scales ranging from minutes out to several days. .. attention:: - The SRW Application has `four levels of support `__. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. This chapter can also serve as a starting point for running the SRW App on other systems (including generic Linux/Mac systems), but the user may need to perform additional troubleshooting. + The SRW Application has `four levels of support `__. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. This chapter also provides guidance for running the SRW App on other systems (including generic Linux/Mac systems), but the user may need to perform additional steps and/or troubleshooting. .. note:: The :ref:`container approach ` is recommended for a smoother first-time build and run experience. Building without a container may allow for more customization. However, the non-container approach requires more in-depth system-based knowledge, especially on Level 3 and 4 systems, so it is less appropriate for beginners. @@ -33,7 +33,9 @@ To build the SRW App, users will complete the following steps: Install the Prerequisite Software Stack ========================================== -Currently, installation of the prerequisite software stack is supported via HPC-Stack. :term:`HPC-Stack` is a repository that provides a unified, shell script-based system to build the software stack required for `UFS `__ applications such as the SRW App. +Users on any sufficiently up-to-date machine with a UNIX-based operating system should be able to install the prerequisite software stack and run the SRW Application. However, a list of prerequisites is available in :numref:`Section %s ` for reference. Users should install or update their system as required before attempting to install the software stack. + +Currently, installation of the prerequisite software stack is supported via HPC-Stack. :term:`HPC-Stack` is a :term:`repository` that provides a unified, shell script-based system to build the software stack required for `UFS `__ applications such as the SRW App. .. Attention:: Skip the HPC-Stack installation if working on a `Level 1 system `__ (e.g., Cheyenne, Hera, Orion, NOAA Cloud), and :ref:`continue to the next section `. @@ -41,7 +43,7 @@ Currently, installation of the prerequisite software stack is supported via HPC- 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) 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. +SRW App components, including the UFS Weather Model (:term:`WM `), draw on over 50 code libraries to run. 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 (or :term:`spack-stack`) is required to run the SRW App. Instructions ------------------------- @@ -58,9 +60,9 @@ Users working on systems that fall under `Support Levels 2-4 `. .. attention:: - Although HPC-Stack is the fully-supported option as of the v2.1.0 release, UFS applications are gradually shifting to :term:`spack-stack`, which is a :term:`Spack`-based method for installing UFS prerequisite software libraries. The spack-stack is currently used on NOAA Cloud platforms and in containers, while HPC-Stack is still used on other Level 1 systems and is the software stack validated by the UFS Weather Model as of the v2.1.0 release. Users are encouraged to check out `spack-stack `__ to prepare for the upcoming shift in support from HPC-Stack to spack-stack. + Although HPC-Stack is currently the fully-supported software stack option, UFS applications are gradually shifting to :term:`spack-stack`, which is a :term:`Spack`-based method for installing UFS prerequisite software libraries. The spack-stack is currently used on NOAA Cloud platforms and in containers, while HPC-Stack is still used on other Level 1 systems and is the software stack validated by the UFS Weather Model. Users are encouraged to check out `spack-stack `__ to prepare for the upcoming shift in support from HPC-Stack to spack-stack. -After completing installation, continue to the next section (:numref:`Section %s: Download the UFS SRW Application Code `). +After completing installation, continue to the :ref:`next section ` to download the UFS SRW Application Code. .. _DownloadSRWApp: @@ -91,6 +93,10 @@ The cloned repository contains the configuration files and sub-directories shown +--------------------------------+-----------------------------------------------------------+ | devbuild.sh | SRW App build script | +--------------------------------+-----------------------------------------------------------+ + | devclean.sh | Convenience script that can be used to clean up code if | + | | something goes wrong when checking out externals or | + | | building the application. | + +--------------------------------+-----------------------------------------------------------+ | docs | Contains release notes, documentation, and User's Guide | +--------------------------------+-----------------------------------------------------------+ | environment.yml | Contains information on the package versions required for | @@ -128,11 +134,11 @@ The cloned repository contains the configuration files and sub-directories shown | | using this script. | +--------------------------------+-----------------------------------------------------------+ | scripts | Contains the *ex-script* for each workflow task. | - | | These scripts are where the script logic and executables | + | | These scripts are where the task logic and executables | | | are contained. | +--------------------------------+-----------------------------------------------------------+ - | sorc | Contains CMakeLists.txt; external repositories | - | | will be cloned into this directory. | + | sorc | Contains CMakeLists.txt; source code from external | + | | repositories is cloned into this directory. | +--------------------------------+-----------------------------------------------------------+ | tests | Contains SRW App tests, including workflow end-to-end | | | (WE2E) tests. | @@ -150,8 +156,6 @@ The cloned repository contains the configuration files and sub-directories shown | | respectively. | +--------------------------------+-----------------------------------------------------------+ -.. COMMENT: Is environment.yml deprecated? Remove? - .. _CheckoutExternals: Check Out External Components @@ -170,11 +174,11 @@ The script should output dialogue indicating that it is retrieving different cod To see more options for the ``checkout_externals`` script, users can run ``./manage_externals/checkout_externals -h``. For example: - * ``-S``: Outputs the status of the repositories managed by ``checkout_externals``. By default only summary information is provided. Use with the ``-v`` (verbose) option to see details. + * ``-S``: Outputs the status of the repositories managed by ``checkout_externals``. By default, only summary information is provided. Use with the ``-v`` (verbose) option to see details. * ``-x [EXCLUDE [EXCLUDE ...]]``: allows users to exclude components when checking out externals. - * ``-o``: By default only the required externals are checked out. This flag will also check out the optional externals. + * ``-o``: This flag will check out the optional external repositories in addition to the default repositories (by default, only the required external repositories are checked out). -Generally, users will not need to use the options and can simply run the script, but the options are available for those who are curious. +Generally, users will not need to use these options and can simply run the script, but the options are available for those who are curious. .. _BuildExecutables: @@ -207,7 +211,7 @@ where valid values are ``intel`` or ``gnu``. 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. -If users want to build the optional ``GSI`` and ``rrfs_utl`` components for :term:`RRFS`, they can pass the ``gsi`` and ``rrfs_utils`` arguments to ``devbuild.sh``. For example: +If users want to build the optional ``GSI`` and ``rrfs_utl`` components for :term:`RRFS` capabilities, they can pass the ``gsi`` and ``rrfs_utils`` arguments to ``devbuild.sh``. For example: .. code-block:: console @@ -216,6 +220,8 @@ If users want to build the optional ``GSI`` and ``rrfs_utl`` components for :ter .. note:: RRFS capabilities are currently build-only features. They are not yet available for use at runtime. +.. COMMENT: Is this still true? + The last few lines of the RRFS console output should be: .. code-block:: console @@ -237,6 +243,8 @@ After running ``devbuild.sh``, the executables listed in :numref:`Table %s `, they should skip to step :numref:`Chapter %s `. + * If users successfully built the executables in :numref:`Table %s `, they should skip to step :numref:`Chapter %s: Running the SRW App `. * Users who want to build the SRW App on MacOS or generic Linux systems should skip to :numref:`Section %s ` and follow the approach there. 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, users can run one of the following two commands depending on whether they have a bash or csh shell, respectively: @@ -395,19 +382,23 @@ From here, ``Lmod`` is ready to load the modulefiles needed by the SRW App. Thes .. code-block:: console - module use + module use module load build__ -where ```` is the full path to the ``modulefiles`` directory. +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. Users on Level 2-4 systems (including generic Linux/MacOS systems) will need to modify an appropriate ``build__`` modulefile. One of the current ``build__`` modulefiles can be copied and used as a template. However, users will need to adjust certain environment variables in their modulefile, such as the path to HPC-Stack, so that the SRW App can find and load the appropriate modules. + +.. note:: -This will work on Level 1 systems, where a modulefile is available in the ``modulefiles`` directory. On Level 2-4 systems (including generic Linux/MacOS 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, depending on whether they are using a bash or csh/tcsh shell, respectively: + These instructions assume that Lmod (an SRW App prerequisite) is installed. 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, depending on whether they are using a bash or csh/tcsh shell, respectively: -.. code-block:: + .. code-block:: - export = - setenv + export = + setenv -Note that building the SRW App without Lmod is not supported at this time. It should be possible to do so, but it has not been tested. Users are encouraged to install Lmod on their system. + However, building the SRW App without Lmod is not supported at this time. It should be possible to do so, but it has not been tested. Users are encouraged to install Lmod on their system. .. _BuildCMake: @@ -428,7 +419,7 @@ From the build directory, run the following commands to build the pre-processing cmake .. -DCMAKE_INSTALL_PREFIX=.. -DCMAKE_INSTALL_BINDIR=exec .. make -j 4 >& build.out & -``-DCMAKE_INSTALL_PREFIX`` specifies the location where the ``exec``, ``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`` 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., ``-j 8``, ``-j 2``), it is highly recommended to use at least 4 parallel threads to prevent overly long installation times. +``-DCMAKE_INSTALL_PREFIX`` specifies the location where the ``exec``, ``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`` argument ``-j 4`` indicates that the build will run in parallel with four threads. Although users can specify a larger or smaller number of threads (e.g., ``-j 8``, ``-j 2``), it is highly recommended to use at least four 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/exec`` directory. These executables are described in :numref:`Table %s `. @@ -442,7 +433,7 @@ Additional Details for Building on MacOS or Generic Linux ------------------------------------------------------------ .. note:: - Users who are **not** building the SRW App on MacOS or generic Linux platforms may skip to :numref:`Section %s ` to finish building the SRW App or continue to :numref:`Chapter %s ` to configure and run an experiment. + Users who are **not** building the SRW App on MacOS or generic Linux platforms may skip to :numref:`Section %s ` to finish building the SRW App or continue to :numref:`Section %s ` to configure and run an experiment. The SRW App can be built on MacOS and generic Linux machines after the prerequisite software has been installed on these systems (via :term:`HPC-Stack` or :term:`spack-stack`). The installation for MacOS is architecture-independent and has been tested using both x86_64 and M1 chips (running natively). The following configurations for MacOS have been tested: @@ -452,7 +443,7 @@ The SRW App can be built on MacOS and generic Linux machines after the prerequis Several Linux builds have been tested on systems with x86_64 architectures. -The ``./modulefiles/build__gnu.lua`` modulefile (where ```` is ``macos`` or ``linux``) is written as a Lmod module in the Lua language, and it can be loaded once the Lmod module environment has been initialized (which should have happened even prior to :ref:`installing HPC-Stack `). This module lists the location of the HPC-Stack modules, loads the meta-modules and modules, sets serial and parallel compilers, additional flags, and any environment variables needed for building the SRW App. The modulefile must be modified to include the absolute path to the user's HPC-Stack installation: +The ``$SRW/modulefiles/build__gnu.lua`` modulefile (where ```` is ``macos`` or ``linux``) is written as a Lmod module in the Lua language. It can be loaded once the Lmod module environment has been initialized (which should have happened even prior to :ref:`installing HPC-Stack `). The ``build__gnu`` modulefile lists the location of the HPC-Stack modules, loads the meta-modules and modules, sets serial and parallel compilers, additional flags, and any environment variables needed for building the SRW App. The modulefile must be modified to include the absolute path to the user's HPC-Stack installation: .. code-block:: console From d8e3c30b955ac091d6749c14d3620644a619be7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 10 Jul 2023 14:11:47 -0400 Subject: [PATCH 011/116] add cpld_gridgen def --- docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst index 6d0528dd44..726a4b7ca6 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst @@ -243,7 +243,7 @@ After running ``devbuild.sh``, the executables listed in :numref:`Table %s ` files required for the coupled model. | +------------------------+---------------------------------------------------------------------------------+ | 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 | @@ -296,7 +296,6 @@ After running ``devbuild.sh``, the executables listed in :numref:`Table %s Date: Mon, 10 Jul 2023 14:18:11 -0400 Subject: [PATCH 012/116] rename/reorganize/minor fixes --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 2 +- docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst | 6 +++--- docs/UsersGuide/source/BuildingRunningTesting/index.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 175196d281..a3c31698a7 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -4,7 +4,7 @@ Running the SRW App =========================== -This chapter explains how to set up and run the "out-of-the-box" case for the SRW Application. However, the steps are relevant to any SRW App experiment and can be modified to suit user goals. This chapter assumes that users have already built the SRW App by following the steps in :numref:`Chapter %s `. These steps are also applicable to containerized versions of the SRW App and assume that the user has completed all of :numref:`Section %s `. +This chapter explains how to set up and run the basic "out-of-the-box" case for the SRW Application. However, the steps are relevant to any SRW App experiment and can be modified to suit user goals. This chapter assumes that users have already built the SRW App by following the steps in :numref:`Section %s `. These steps are also applicable to containerized versions of the SRW App and assume that the user has completed all of :numref:`Section %s `. 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 16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. diff --git a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst index 185faa777d..8455e3d0ae 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst @@ -1,8 +1,8 @@ .. _WE2E_tests: -================================== -Workflow End-to-End (WE2E) Tests -================================== +======================= +Testing the SRW App +======================= 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 from start to finish. 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 diff --git a/docs/UsersGuide/source/BuildingRunningTesting/index.rst b/docs/UsersGuide/source/BuildingRunningTesting/index.rst index 189e458f7f..5c0efc3c64 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/index.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/index.rst @@ -9,7 +9,7 @@ Building, Running, and Testing the SRW App ContainerQuickstart BuildSRW RunSRW - Tutorial WE2Etests + Tutorial VXCases AQM From 1cfba00de8342090c93748d7a25be98f9d7c9f45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 10 Jul 2023 15:06:07 -0400 Subject: [PATCH 013/116] minor updates --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 4 ++-- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index e7b5776800..2cfb0df218 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -47,12 +47,12 @@ Building, Running, and Testing the SRW App * :numref:`Chapter %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers come with SRW App prerequisites already installed and run on a broad range of systems. * :numref:`Chapter %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. * :numref:`Chapter %s: Running the SRW App ` provides a *detailed* explanation of how to run the App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. + * :numref:`Chapter %s: Testing the SRW App ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. * :numref:`Chapter %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. - * :numref:`Chapter %s: Workflow End-to-End (WE2E) Tests ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. * :numref:`Chapter %s: METplus Verification Sample Cases ` explains how to run METplus verification as part of the workflow. * :numref:`Chapter %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this chapter is a starting point for those interested in AQM. -Technical Information for Users +Tinkering with Workflow Details --------------------------------- * :numref:`Chapter %s: Workflow Parameters ` documents all of the user-configurable experiment parameters that can be set in ``config.yaml``. diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index a3c31698a7..f17e360d6a 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -4,13 +4,13 @@ Running the SRW App =========================== -This chapter explains how to set up and run the basic "out-of-the-box" case for the SRW Application. However, the steps are relevant to any SRW App experiment and can be modified to suit user goals. This chapter assumes that users have already built the SRW App by following the steps in :numref:`Section %s `. These steps are also applicable to containerized versions of the SRW App and assume that the user has completed all of :numref:`Section %s `. +This section explains how to set up and run the basic "out-of-the-box" case for the SRW Application. However, the steps are relevant to any SRW App experiment and can be modified to suit user goals. This chapter assumes that users have already built the SRW App by following the steps in :numref:`Section %s ` (or :numref:`Section %s ` if running the containerized version of the SRW App). 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 16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. .. attention:: - The SRW Application has `four levels of support `__. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. This chapter can also serve as a starting point for running the SRW App on other systems (including generic Linux/Mac systems), but the user may need to perform additional troubleshooting. + The SRW Application has `four levels of support `__. The steps described in this section will work most smoothly on preconfigured (Level 1) systems. They should also work on other systems (including generic Linux/Mac systems), but the user may need to perform additional troubleshooting. 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. Once the SRW App has been built, as described in :numref:`Chapter %s `, the steps to run a forecast are as follows: From 593c4c6cc62f7606d69d4bf839cb8cf2a658cc30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 10 Jul 2023 15:09:51 -0400 Subject: [PATCH 014/116] minor updates --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 2cfb0df218..c8e8f8d4a7 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -37,8 +37,8 @@ Background Information ------------------------- * This **Introduction** chapter explains how the SRW App documentation is organized, how to use this guide, and where to find user support/documentation. - * :numref:`Chapter %s: Technical Overview ` provides a technical overview, including SRW App prerequisites, code overview/directory structure, and summary of components. - * :numref:`Chapter %s: Components ` provides a more detailed description of the application components, including optional application components. + * :numref:`Chapter %s: Technical Overview ` provides a technical overview, including SRW App prerequisites and an overview of the code directory structure. + * :numref:`Chapter %s: Components ` provides a detailed description of the application components, including optional application components. Building, Running, and Testing the SRW App -------------------------------------------- From e4ba1bcf04d5ac9fe6204ae42ee915dd5885cd14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 10 Jul 2023 16:41:41 -0400 Subject: [PATCH 015/116] change regional_workflow to workflow_tools --- .../BackgroundInfo/TechnicalOverview.rst | 4 +-- .../ContainerQuickstart.rst | 16 +++++----- .../BuildingRunningTesting/Quickstart.rst | 8 ++--- .../source/BuildingRunningTesting/RunSRW.rst | 29 ++++++++++--------- .../BuildingRunningTesting/Tutorial.rst | 10 +++---- .../source/BuildingRunningTesting/VXCases.rst | 12 ++++---- .../TechnicalDetails/InputOutputFiles.rst | 6 ++-- 7 files changed, 43 insertions(+), 42 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index b418e74851..3d24f1f357 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -193,11 +193,11 @@ The ``ufs-srweather-app`` :term:`umbrella repository` structure is determined by SRW App SubDirectories ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:numref:`Table %s ` describes the contents of the most important subdirectories. :numref:`Table %s ` provides an in-depth explanation of the ``ufs-srweather-app`` directories. +:numref:`Table %s ` describes the contents of the most important SRW App subdirectories. :numref:`Table %s ` provides a more comprehensive explanation of the ``ufs-srweather-app`` files and subdirectories. .. _Subdirectories: -.. table:: Subdirectories of the regional workflow +.. table:: *Subdirectories of the ufs-srweather-app repository* +-------------------------+----------------------------------------------------+ | **Directory Name** | **Description** | diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index 8515e097a3..60b9113cd1 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -218,7 +218,7 @@ Generate the Forecast Experiment ================================= To generate the forecast experiment, users must: -#. :ref:`Activate the regional workflow ` +#. :ref:`Activate the workflow ` #. :ref:`Set experiment parameters ` #. :ref:`Run a script to generate the experiment workflow ` @@ -226,8 +226,8 @@ The first two steps depend on the platform being used and are described here for .. _SetUpPythonEnvC: -Activate the Regional Workflow -------------------------------------- +Activate the Workflow +------------------------ Copy the container's modulefiles to the local working directory so that the files can be accessed outside of the container: @@ -237,7 +237,7 @@ Copy the container's modulefiles to the local working directory so that the file After this command runs, the local working directory should contain the ``modulefiles`` directory. -To activate the regional workflow, run the following commands: +To activate the workflow, run the following commands: .. code-block:: console @@ -249,14 +249,14 @@ where: * ```` is replaced with the actual path to the modulefiles on the user's local system (often ``$PWD/modulefiles``), and * ```` is a valid, lowercased machine/platform name (see the ``MACHINE`` variable in :numref:`Section %s `). -The ``wflow_`` modulefile will then output instructions to activate the regional workflow. The user should run the commands specified in the modulefile output. For example, if the output says: +The ``wflow_`` modulefile will then output instructions to activate the workflow. The user should run the commands specified in the modulefile output. For example, if the output says: .. code-block:: console Please do the following to activate conda: - > conda activate regional_workflow + > conda activate workflow_tools -then the user should run ``conda activate regional_workflow``. This will activate the ``regional_workflow`` conda environment. The command(s) will vary from system to system, but the user should see ``(regional_workflow)`` in front of the Terminal prompt at this point. +then the user should run ``conda activate workflow_tools``. This will activate the ``workflow_tools`` conda environment. The command(s) will vary from system to system, but the user should see ``(workflow_tools)`` in front of the Terminal prompt at this point. .. _SetUpConfigFileC: @@ -387,4 +387,4 @@ where: New Experiment =============== -To run a new experiment in the container at a later time, users will need to rerun the commands in :numref:`Section %s ` to reactivate the regional workflow. Then, users can configure a new experiment by updating the environment variables in ``config.yaml`` to reflect the desired experiment configuration. Basic instructions appear in :numref:`Section %s ` above, and detailed instructions can be viewed in :numref:`Section %s `. After adjusting the configuration file, regenerate the experiment by running ``./generate_FV3LAM_wflow.py``. +To run a new experiment in the container at a later time, users will need to rerun the commands in :numref:`Section %s ` to reactivate the workflow. Then, users can configure a new experiment by updating the environment variables in ``config.yaml`` to reflect the desired experiment configuration. Basic instructions appear in :numref:`Section %s ` above, and detailed instructions can be viewed in :numref:`Section %s `. After adjusting the configuration file, regenerate the experiment by running ``./generate_FV3LAM_wflow.py``. diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst index 06a5ee8112..23357e4814 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst @@ -45,7 +45,7 @@ For a detailed explanation of how to build and run the SRW App on any supported #. Users on a `Level 2-4 `__ system must download and stage data (both the fix files and the :term:`IC/LBC ` files) according to the instructions in :numref:`Section %s `. Standard data locations for Level 1 systems appear in :numref:`Table %s `. - #. Load the python environment for the regional workflow. Users on Level 2-4 systems will need to use one of the existing ``wflow_`` modulefiles (e.g., ``wflow_macos``) and adapt it to their system. Then, run: + #. Load the python environment for the workflow. Users on Level 2-4 systems will need to use one of the existing ``wflow_`` modulefiles (e.g., ``wflow_macos``) and adapt it to their system. Then, run: .. code-block:: console @@ -58,9 +58,9 @@ For a detailed explanation of how to build and run the SRW App on any supported .. code-block:: console Please do the following to activate conda: - > conda activate regional_workflow + > conda activate workflow_tools - then the user should run ``conda activate regional_workflow`` to activate the regional workflow environment. + then the user should run ``conda activate workflow_tools`` to activate the workflow environment. .. note:: If users source the *lmod-setup* file on a system that doesn't need it, it will not cause any problems (it will simply do a ``module purge``). @@ -80,7 +80,7 @@ For a detailed explanation of how to build and run the SRW App on any supported ./generate_FV3LAM_wflow.py - #. Run the regional workflow. There are several methods available for this step, which are discussed in :numref:`Section %s `. One possible method is summarized below. It requires the :ref:`Rocoto Workflow Manager `. + #. Run the workflow. There are several methods available for this step, which are discussed in :numref:`Section %s `. One possible method is summarized below. It requires the :ref:`Rocoto Workflow Manager `. .. code-block:: console diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index f17e360d6a..a736e50da5 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -61,14 +61,14 @@ The SRW App requires input files to run. These include static datasets, initial | WCOSS2 | /lfs/h2/emc/lam/noscrub/UFS_SRW_App/develop/input_model_data/ | +--------------+------------------------------------------------------------------------------+ -For Level 2-4 systems, the data must be added to the user's system. Detailed instructions on how to add the data can be found in :numref:`Section %s `. Sections :numref:`%s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. +For Level 2-4 systems, the data must be added to the user's system. Detailed instructions on how to add the data can be found in :numref:`Section %s: Downloading and Staging Input Data `. Sections :numref:`%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 the four predefined grids 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 `. 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 custom predefined grid should refer to :numref:`Section %s ` for instructions. At a minimum, these users will need to add the new grid name to the ``valid_param_vals.yaml`` file and add the corresponding grid-specific parameters in the ``predef_grid_params.yaml`` file. +The SRW App officially supports the four predefined grids 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:`Section %s: Limited Area Model (LAM) Grids `. Users who plan to utilize one of the four predefined domain (grid) options may continue to the next step (:numref:`Step %s: Generate the Forecast Experiment `). Users who plan to create a new custom predefined grid should refer to the instructions in :numref:`Section %s: Creating User-Generated Grids `. At a minimum, these users will need to add the new grid name to the ``valid_param_vals.yaml`` file and add the corresponding grid-specific parameters in the ``predef_grid_params.yaml`` file. .. _PredefinedGrids: @@ -86,6 +86,7 @@ The SRW App officially supports the four predefined grids shown in :numref:`Tabl | SUBCONUS_Ind_3km | ESG grid | lambert_conformal | +----------------------+-------------------+--------------------------------+ +.. COMMENT: Revisit before SRW w/RRFS release .. _GenerateForecast: @@ -93,18 +94,18 @@ Generate the Forecast Experiment ================================= Generating the forecast experiment requires three steps: -#. :ref:`Load the python environment for the regional workflow ` +#. :ref:`Load the python environment required for the regional workflow ` #. :ref:`Set experiment configuration 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 reflect their machine configuration if they are working on a Level 2-4 platform. Information in :numref:`Chapter %s: Configuring the Workflow ` can help with this. +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 reflect their machine configuration if they are working on a Level 2-4 platform. Information in :numref:`Section %s: Configuring the Workflow ` can help with this. .. _SetUpPythonEnv: -Load the Conda/Python Environment for the Regional Workflow --------------------------------------------------------------- +Load the Conda/Python Environment +------------------------------------ -The workflow requires Python3 installed using conda, with the additional packages built in a separate conda evironment named ``regional_workflow``. This environment has the following additional packages: ``PyYAML``, ``Jinja2``, ``f90nml``, ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``. This conda/Python environment has already been set up on Level 1 platforms and can be activated in the following way: +The SRW App workflow is often referred to as the *regional workflow* because it runs experiments on a regional scale (unlike the *global workflow* used in other applications). The regional workflow requires installation of Python3 using conda; it also requires additional packages (``PyYAML``, ``Jinja2``, ``f90nml``, ``scipy``, ``matplotlib``, ``pygrib``, and ``cartopy``) built in a separate conda evironment named ``workflow_tools``. This conda/Python environment has already been set up on Level 1 platforms and can be activated in the following way: .. code-block:: console @@ -124,17 +125,17 @@ The ``wflow_`` modulefile will then output instructions to activate th .. code-block:: console Please do the following to activate conda: - > conda activate regional_workflow + > conda activate workflow_tools -then the user should run ``conda activate regional_workflow``. This activates the ``regional_workflow`` conda environment, and the user typically sees ``(regional_workflow)`` in front of the Terminal prompt at this point. +then the user should run ``conda activate workflow_tools``. This activates the ``workflow_tools`` conda environment, and the user typically sees ``(workflow_tools)`` in front of the Terminal prompt at this point. Preparing the Workflow Environment on Non-Level 1 Systems ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Users on non-Level 1 systems can copy one of the provided ``wflow_`` files and use it as a template to create a ``wflow_`` file that works for their system. The ``wflow_macos`` and ``wflow_linux`` template modulefiles are provided in the ``modulefiles`` directory. Modifications are required to provide paths for python, miniconda modules, module loads, conda initialization, and the path for user's ``regional_workflow`` conda environment. After making modifications to a ``wflow_`` file, users can run the commands from :numref:`Step %s ` above to activate the regional workflow. +Users on non-Level 1 systems can copy one of the provided ``wflow_`` files and use it as a template to create a ``wflow_`` file that works for their system. The ``wflow_macos`` and ``wflow_linux`` template modulefiles are provided in the ``modulefiles`` directory. Modifications are required to provide paths for python, miniconda modules, module loads, conda initialization, and the path for user's ``workflow_tools`` conda environment. After making modifications to a ``wflow_`` file, users can run the commands from :numref:`Step %s ` above to activate the regional workflow. .. note:: - ``conda`` needs to be initialized before running ``conda activate regional_workflow`` command. Depending on the user's system and login setup, this may be accomplished in a variety of ways. Conda initialization usually involves the following command: ``source /etc/profile.d/conda.sh``, where ```` is the base conda installation directory. + ``conda`` needs to be initialized before running ``conda activate workflow_tools`` command. Depending on the user's system and login setup, this may be accomplished in a variety of ways. Conda initialization usually involves the following command: ``source /etc/profile.d/conda.sh``, where ```` is the base conda installation directory. .. _ExptConfig: @@ -525,12 +526,12 @@ MacOS requires the installation of a few additional packages and, possibly, an u Creating a *conda* Environment on Linux and Mac `````````````````````````````````````````````````` -Users need to create a conda ``regional_workflow`` environment. The environment can be stored in a local path, which could be a default location or a user-specified location (e.g. ``$HOME/condaenv/venvs/`` directory). (To determine the default location, use the ``conda info`` command, and look for the ``envs directories`` list.) A brief recipe for creating a virtual conda environment on non-Level 1 platforms: +Users need to create a conda ``workflow_tools`` environment. The environment can be stored in a local path, which could be a default location or a user-specified location (e.g. ``$HOME/condaenv/venvs/`` directory). (To determine the default location, use the ``conda info`` command, and look for the ``envs directories`` list.) A brief recipe for creating a virtual conda environment on non-Level 1 platforms: .. code-block:: console - conda create --name regional_workflow python= - conda activate regional_workflow + conda create --name workflow_tools python= + conda activate workflow_tools conda install -c conda-forge f90nml conda install jinja2 conda install pyyaml diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst index f96e39ef52..270782861d 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst @@ -52,10 +52,10 @@ On `Level 1 `` is a valid, lowercased machine name (see ``MACHINE`` in :numref:`Section %s ` for valid values). -After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate regional_workflow``. For example, a user on Hera with permissions on the ``nems`` project may issue the following commands to load the regional workflow (replacing ``User.Name`` with their actual username): +After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate workflow_tools``. For example, a user on Hera with permissions on the ``nems`` project may issue the following commands to load the workflow (replacing ``User.Name`` with their actual username): .. code-block:: console source /scratch1/NCEPDEV/nems/User.Name/ufs-srweather-app/etc/lmod-setup.sh hera module use /scratch1/NCEPDEV/nems/User.Name/ufs-srweather-app/modulefiles module load wflow_hera - conda activate regional_workflow + conda activate workflow_tools Configuration ------------------------- diff --git a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst index eca1067baa..0bf58336f9 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst @@ -80,10 +80,10 @@ Record the path to this file output using the ``pwd`` command: Users can untar the fix files and Natural Earth files by substituting those file names in the commands above. -Load the Regional Workflow -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Load the Workflow +^^^^^^^^^^^^^^^^^^^^ -First, navigate to the ``ufs-srweather-app/ush`` directory. Then, load the regional workflow environment: +First, navigate to the ``ufs-srweather-app/ush`` directory. Then, load the workflow environment: .. code-block:: console @@ -93,12 +93,12 @@ First, navigate to the ``ufs-srweather-app/ush`` directory. Then, load the regio Users running a csh/tcsh shell would run ``source `` in place of the first command above. -After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate regional_workflow``. +After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate workflow_tools``. Configure the Verification Sample Case ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Once the regional workflow is loaded, copy the out-of-the-box configuration: +Once the workflow environment is loaded, copy the out-of-the-box configuration: .. code-block:: console @@ -189,7 +189,7 @@ If a problem occurs and a task goes DEAD, view the task log files in ``$EXPTDIR/ Generate Plots ^^^^^^^^^^^^^^^^^ -The plots are created using the graphics generation script that comes with the SRW App v2.1.0 release. Information on the plots and instructions on how to run the script can be found in :doc:`Chapter 12 ` of the v2.1.0 release documentation. If the python environment is already loaded (i.e., ``(regional_workflow)`` is visible in the command prompt), users can navigate to the directory with the plotting scripts and run ``plot_allvars.py``: +The plots are created using the graphics generation script that comes with the SRW App v2.1.0 release. Information on the plots and instructions on how to run the script can be found in :doc:`Chapter 12 ` of the v2.1.0 release documentation. If the python environment is already loaded (i.e., ``(workflow_tools)`` is visible in the command prompt), users can navigate to the directory with the plotting scripts and run ``plot_allvars.py``: .. code-block:: console diff --git a/docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst b/docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst index 391affd49c..8755fae6c7 100644 --- a/docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst +++ b/docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst @@ -27,7 +27,7 @@ The data format for these files can be :term:`GRIB2` or :term:`NEMSIO`. More inf Pre-processing (UFS_UTILS) --------------------------- -When a user generates the regional workflow as described in :numref:`Section %s `, 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 `Technical Documentation `__ and `Scientific Documentation `__. +When a user generates the SRW App workflow as described in :numref:`Section %s `, 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 `Technical Documentation `__ and `Scientific Documentation `__. UFS Weather Model ----------------- @@ -53,7 +53,7 @@ and are shown in :numref:`Table %s `. .. _TemplateFiles: -.. table:: Template Files for the Regional Workflow +.. table:: Template Files for the SRW App Workflow +-----------------------------+--------------------------------------------------------------+ | **File Name** | **Description** | @@ -101,7 +101,7 @@ Additional information related to ``diag_table.[CCPP]``, ``field_table.[CCPP]``, Migratory Route of the Input Files in the Workflow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:numref:`Figure %s ` shows how the input files in the template directory (``ufs-srweather-app/parm``) 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 ``parm`` 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/parm``) 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 SRW App 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 ``parm`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. .. _MigratoryRoute: From e5df5c038490f9409b3fee6e23804927116259a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 10 Jul 2023 16:48:16 -0400 Subject: [PATCH 016/116] change regional workflow to workflow or SRW App workflow --- .../source/BuildingRunningTesting/RunSRW.rst | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index a736e50da5..9b74786c8e 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -17,14 +17,14 @@ The overall procedure for generating an experiment is shown in :numref:`Figure % #. :ref:`Download and stage data ` #. :ref:`Optional: Configure a new grid ` - #. :ref:`Generate a regional workflow experiment ` + #. :ref:`Generate an SRW App experiment ` - * :ref:`Load the python environment for the regional workflow ` + * :ref:`Load the python environment for the SRW App workflow ` * :ref:`Set the experiment configuration parameters ` * :ref:`Optional: Plot the output ` * :ref:`Optional: Configure METplus Verification Suite ` - #. :ref:`Run the regional workflow ` + #. :ref:`Run the SRW App workflow ` .. _AppOverallProc: @@ -94,7 +94,7 @@ Generate the Forecast Experiment ================================= Generating the forecast experiment requires three steps: -#. :ref:`Load the python environment required for the regional workflow ` +#. :ref:`Load the python environment required for the SRW App workflow ` #. :ref:`Set experiment configuration parameters ` #. :ref:`Run a script to generate the experiment workflow ` @@ -105,7 +105,7 @@ The first two steps depend on the platform being used and are described here for Load the Conda/Python Environment ------------------------------------ -The SRW App workflow is often referred to as the *regional workflow* because it runs experiments on a regional scale (unlike the *global workflow* used in other applications). The regional workflow requires installation of Python3 using conda; it also requires additional packages (``PyYAML``, ``Jinja2``, ``f90nml``, ``scipy``, ``matplotlib``, ``pygrib``, and ``cartopy``) built in a separate conda evironment named ``workflow_tools``. This conda/Python environment has already been set up on Level 1 platforms and can be activated in the following way: +The SRW App workflow is often referred to as the *regional workflow* because it runs experiments on a regional scale (unlike the *global workflow* used in other applications). The workflow requires installation of Python3 using conda; it also requires additional packages (``PyYAML``, ``Jinja2``, ``f90nml``, ``scipy``, ``matplotlib``, ``pygrib``, and ``cartopy``) built in a separate conda evironment named ``workflow_tools``. This conda/Python environment has already been set up on Level 1 platforms and can be activated in the following way: .. code-block:: console @@ -118,9 +118,9 @@ where ```` refers to a valid machine name (see :numref:`Section %s `. +A brief recipe for building the workflow environment on a Linux or Mac system can be found in :numref:`Section %s `. -The ``wflow_`` modulefile will then output instructions to activate the regional workflow. The user should run the commands specified in the modulefile output. The command may vary from system to system. For example, if the output says: +The ``wflow_`` modulefile will then output instructions to activate the SRW App workflow. The user should run the commands specified in the modulefile output. The command may vary from system to system. For example, if the output says: .. code-block:: console @@ -132,7 +132,7 @@ then the user should run ``conda activate workflow_tools``. This activates the ` Preparing the Workflow Environment on Non-Level 1 Systems ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Users on non-Level 1 systems can copy one of the provided ``wflow_`` files and use it as a template to create a ``wflow_`` file that works for their system. The ``wflow_macos`` and ``wflow_linux`` template modulefiles are provided in the ``modulefiles`` directory. Modifications are required to provide paths for python, miniconda modules, module loads, conda initialization, and the path for user's ``workflow_tools`` conda environment. After making modifications to a ``wflow_`` file, users can run the commands from :numref:`Step %s ` above to activate the regional workflow. +Users on non-Level 1 systems can copy one of the provided ``wflow_`` files and use it as a template to create a ``wflow_`` file that works for their system. The ``wflow_macos`` and ``wflow_linux`` template modulefiles are provided in the ``modulefiles`` directory. Modifications are required to provide paths for python, miniconda modules, module loads, conda initialization, and the path for user's ``workflow_tools`` conda environment. After making modifications to a ``wflow_`` file, users can run the commands from :numref:`Step %s ` above to activate the workflow environment. .. note:: ``conda`` needs to be initialized before running ``conda activate workflow_tools`` command. Depending on the user's system and login setup, this may be accomplished in a variety of ways. Conda initialization usually involves the following command: ``source /etc/profile.d/conda.sh``, where ```` is the base conda installation directory. @@ -420,7 +420,7 @@ A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yam .. note:: - The regional workflow must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. + The ``workflow_tools`` environment must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. In addition, various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. @@ -736,8 +736,8 @@ Users who have already staged the observation data needed for METplus (i.e., the .. _GenerateWorkflow: -Generate the Regional Workflow -------------------------------------------- +Generate the SRW App Workflow +-------------------------------- Run the following command from the ``ufs-srweather-app/ush`` directory to generate the workflow: @@ -1156,11 +1156,11 @@ If the experiment fails, the ``rocotostat`` command will indicate which task fai Run the Workflow Using Stand-Alone Scripts --------------------------------------------- -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. +The SRW App 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. .. attention:: - When working on an HPC system, users should allocate a compute node prior to running their experiment. The proper command will depend on the system's resource manager, but some guidance is offered in :numref:`Section %s `. It may be necessay to reload the regional workflow (see :numref:`Section %s `). It may also be necessary to load the ``build__`` scripts as described in :numref:`Section %s `. + When working on an HPC system, users should allocate a compute node prior to running their experiment. The proper command will depend on the system's resource manager, but some guidance is offered in :numref:`Section %s `. It may be necessay to reload the workflow environment (see :numref:`Section %s `). It may also be necessary to load the ``build__`` scripts as described in :numref:`Section %s `. #. ``cd`` into the experiment directory. For example, from ``ush``, presuming default directory settings: @@ -1219,7 +1219,7 @@ Check the batch script output file in your experiment directory for a “SUCCESS .. _RegionalWflowTasks: -.. table:: List of tasks in the regional workflow in the order that they are executed. +.. table:: List of tasks in the SRW App 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. For a brief description of tasks, see :numref:`Table %s `. From 92dd46da74d2ff11f6172bbd0f512919dfc95747 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 10 Jul 2023 18:38:16 -0400 Subject: [PATCH 017/116] update info on loading wflow env for L1 v L2-4 systems --- .../source/BuildingRunningTesting/RunSRW.rst | 156 ++++++++++++------ 1 file changed, 106 insertions(+), 50 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 9b74786c8e..4c11080962 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -19,7 +19,7 @@ The overall procedure for generating an experiment is shown in :numref:`Figure % #. :ref:`Optional: Configure a new grid ` #. :ref:`Generate an SRW App experiment ` - * :ref:`Load the python environment for the SRW App workflow ` + * :ref:`Load the workflow environment ` * :ref:`Set the experiment configuration parameters ` * :ref:`Optional: Plot the output ` * :ref:`Optional: Configure METplus Verification Suite ` @@ -94,32 +94,41 @@ Generate the Forecast Experiment ================================= Generating the forecast experiment requires three steps: -#. :ref:`Load the python environment required for the SRW App workflow ` +#. :ref:`Load the workflow environment ` #. :ref:`Set experiment configuration 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 reflect their machine configuration if they are working on a Level 2-4 platform. Information in :numref:`Section %s: Configuring the Workflow ` can help with this. +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 reflect their machine's configuration if they are working on a Level 2-4 platform. Information in :numref:`Section %s: Configuring the Workflow ` can help with this. .. _SetUpPythonEnv: Load the Conda/Python Environment ------------------------------------ -The SRW App workflow is often referred to as the *regional workflow* because it runs experiments on a regional scale (unlike the *global workflow* used in other applications). The workflow requires installation of Python3 using conda; it also requires additional packages (``PyYAML``, ``Jinja2``, ``f90nml``, ``scipy``, ``matplotlib``, ``pygrib``, and ``cartopy``) built in a separate conda evironment named ``workflow_tools``. This conda/Python environment has already been set up on Level 1 platforms and can be activated in the following way: +The SRW App workflow is often referred to as the *regional workflow* because it runs experiments on a regional scale (unlike the *global workflow* used in other applications). The SRW App workflow requires installation of Python3 using conda; it also requires additional packages (``PyYAML``, ``Jinja2``, ``f90nml``, ``scipy``, ``matplotlib``, ``pygrib``, and ``cartopy``) built in a separate conda evironment named ``workflow_tools``. On Level 1 systems, a ``workflow_tools`` environment already exists, and users merely need to load the environment. On Level 2-4 systems, users must create and then load the environment. The process for each is described in detail below. + +.. _Load-WF-L1: + +Loading the Workflow Environment on Level 1 Systems +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. attention:: + + Users on a Level 2-4 system should skip to the :ref:`next section ` for instructions. + +The ``workflow_tools`` conda/Python environment has already been set up on Level 1 platforms and can be activated in the following way: .. code-block:: console - source - module use + source + module use module load wflow_ -where ```` refers to a valid machine name (see :numref:`Section %s `). +where ```` refers to a valid machine name (see :numref:`Section %s ` for ``MACHINE`` options). .. note:: If users source the lmod-setup file on a system that doesn't need it, it will not cause any problems (it will simply do a ``module purge``). -A brief recipe for building the workflow environment on a Linux or Mac system can be found in :numref:`Section %s `. - The ``wflow_`` modulefile will then output instructions to activate the SRW App workflow. The user should run the commands specified in the modulefile output. The command may vary from system to system. For example, if the output says: .. code-block:: console @@ -129,10 +138,95 @@ The ``wflow_`` modulefile will then output instructions to activate th then the user should run ``conda activate workflow_tools``. This activates the ``workflow_tools`` conda environment, and the user typically sees ``(workflow_tools)`` in front of the Terminal prompt at this point. -Preparing the Workflow Environment on Non-Level 1 Systems -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +After loading the workflow environment, users may continue to :numref:`Section %s ` for instructions on setting the experiment configuration parameters. + +.. _Load-WF-L234: + +Loading the Workflow Environment on Level 2-4 Systems +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Users on non-Level 1 systems will need to create a conda workflow environment, modify a ``wflow_*`` file to reflect the location of required modules, and load the workflow modules using the modified ``wflow_*`` file. + +Create a *conda* Workflow Environment +``````````````````````````````````````` + +.. note:: + Examples in this subsection presume that the user is running in the Terminal with a bash shell environment. If this is not the case, users will need to adjust the commands to fit their command line application and shell environment. + +.. _MacMorePackages: + +MacOS ONLY: Install/Upgrade Mac-Specific Packages +""""""""""""""""""""""""""""""""""""""""""""""""""" + +.. attention:: + + This subsection is for Mac OS users only. Users on Linux systems can skip to :ref:`Creating the workflow_tools Environment on Linux and Mac OS ` for instructions. + + +MacOS requires the installation of a few additional packages and, possibly, an upgrade to bash. Users running on MacOS should execute the following commands: + +.. code-block:: console + + bash --version + brew install bash # or: brew upgrade bash + brew install coreutils + brew gsed # follow directions to update the PATH env variable + + +.. _LinuxMacVEnv: + +Creating the ``workflow_tools`` Environment on Linux and Mac OS +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +On generic Mac and Linux systems, users need to create a conda ``workflow_tools`` environment. The environment can be stored in a local path, which could be a default location or a user-specified location (e.g., ``$HOME/condaenv/venvs/`` directory). (To determine the default location, use the ``conda info`` command, and look for the ``envs directories`` list.) The following is a brief recipe for creating a virtual conda environment on non-Level 1 platforms: + +.. code-block:: console + + conda create --name workflow_tools python= + conda activate workflow_tools + conda install -c conda-forge f90nml + conda install jinja2 + conda install pyyaml + # install packages for graphics environment + conda install scipy + conda install matplotlib + conda install -c conda-forge pygrib + conda install cartopy + # verify the packages installed + conda list + conda deactivate + +where ```` is a numeric version (e.g., ``3.9.12``) in the conda base installation resulting from the query ``python3 --version``. + +Modify a ``wflow_`` File +`````````````````````````````````````` + +Users can copy one of the provided ``wflow_`` files from the ``modulefiles`` directory and use it as a template to create a ``wflow_`` file that functions on their system. The ``wflow_macos`` and ``wflow_linux`` template modulefiles are provided as a starting point, but any ``wflow_`` file could be used. Users must modify the files to provide paths for python, miniconda modules, module loads, conda initialization, and the user's ``workflow_tools`` conda environment. + +Load the Workflow Environment +``````````````````````````````` + +After creating a ``workflow_tools`` environment and making modifications to a ``wflow_`` file, users can run the commands below to activate the workflow environment: + +.. code-block:: console + + source + module use + module load wflow_ + +where ```` refers to a valid machine name (i.e., ``linux`` or ``macos``). + +.. note:: + If users source the lmod-setup file on a system that doesn't need it, it will not cause any problems (it will simply do a ``module purge``). + +The ``wflow_`` modulefile will then output the following instructions: -Users on non-Level 1 systems can copy one of the provided ``wflow_`` files and use it as a template to create a ``wflow_`` file that works for their system. The ``wflow_macos`` and ``wflow_linux`` template modulefiles are provided in the ``modulefiles`` directory. Modifications are required to provide paths for python, miniconda modules, module loads, conda initialization, and the path for user's ``workflow_tools`` conda environment. After making modifications to a ``wflow_`` file, users can run the commands from :numref:`Step %s ` above to activate the workflow environment. +.. code-block:: console + + Please do the following to activate conda: + > conda activate workflow_tools + +After running ``conda activate workflow_tools``, the user will typically see ``(workflow_tools)`` in front of the Terminal prompt. This indicates that the workflow environment has been loaded successfully. .. note:: ``conda`` needs to be initialized before running ``conda activate workflow_tools`` command. Depending on the user's system and login setup, this may be accomplished in a variety of ways. Conda initialization usually involves the following command: ``source /etc/profile.d/conda.sh``, where ```` is the base conda installation directory. @@ -508,44 +602,6 @@ The configuration process for Linux and MacOS systems is similar to the process .. note:: Examples in this subsection presume that the user is running in the Terminal with a bash shell environment. If this is not the case, users will need to adjust the commands to fit their command line application and shell environment. -.. _MacMorePackages: - -Install/Upgrade Mac-Specific Packages -```````````````````````````````````````` -MacOS requires the installation of a few additional packages and, possibly, an upgrade to bash. Users running on MacOS should execute the following commands: - -.. code-block:: console - - bash --version - brew install bash # or: brew upgrade bash - brew install coreutils - brew gsed # follow directions to update the PATH env variable - -.. _LinuxMacVEnv: - -Creating a *conda* Environment on Linux and Mac -`````````````````````````````````````````````````` - -Users need to create a conda ``workflow_tools`` environment. The environment can be stored in a local path, which could be a default location or a user-specified location (e.g. ``$HOME/condaenv/venvs/`` directory). (To determine the default location, use the ``conda info`` command, and look for the ``envs directories`` list.) A brief recipe for creating a virtual conda environment on non-Level 1 platforms: - -.. code-block:: console - - conda create --name workflow_tools python= - conda activate workflow_tools - conda install -c conda-forge f90nml - conda install jinja2 - conda install pyyaml - # install packages for graphics environment - conda install scipy - conda install matplotlib - conda install -c conda-forge pygrib - conda install cartopy - # verify the packages installed - conda list - conda deactivate - -where ```` is a numeric version (e.g. ``3.9.12``) in the conda base installation resulting from the query ``python3 --version``. - .. _LinuxMacExptConfig: Configuring an Experiment on General Linux and MacOS Systems From 0a1e7a261ecd9a1600bbcc7a424b23efda368aae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 10 Jul 2023 19:45:59 -0400 Subject: [PATCH 018/116] move config_defaults table out of Run chapter --- .../DefaultVarsTable.rst | 71 ++++++++++++ .../source/BuildingRunningTesting/RunSRW.rst | 102 +----------------- 2 files changed, 73 insertions(+), 100 deletions(-) create mode 100644 docs/UsersGuide/source/BuildingRunningTesting/DefaultVarsTable.rst diff --git a/docs/UsersGuide/source/BuildingRunningTesting/DefaultVarsTable.rst b/docs/UsersGuide/source/BuildingRunningTesting/DefaultVarsTable.rst new file mode 100644 index 0000000000..063676675e --- /dev/null +++ b/docs/UsersGuide/source/BuildingRunningTesting/DefaultVarsTable.rst @@ -0,0 +1,71 @@ +:orphan: + +================================================ +Table of Variables in ``config_defaults.yaml`` +================================================ + +.. list-table:: Configuration variables specified in the config_defaults.yaml script + :widths: 20 50 + :header-rows: 1 + + * - Group Name + - Configuration variables + * - User + - RUN_ENVIR, MACHINE, ACCOUNT, HOMEdir, USHdir, SCRIPTSdir, JOBSdir, SORCdir, PARMdir, MODULESdir, EXECdir, VX_CONFIG_DIR, METPLUS_CONF, MET_CONFIG, UFS_WTHR_MDL_DIR, ARL_NEXUS_DIR + * - Platform + - WORKFLOW_MANAGER, NCORES_PER_NODE, TASKTHROTTLE, BUILD_MOD_FN, WFLOW_MOD_FN, BUILD_VER_FN, RUN_VER_FN, SCHED,PARTITION_DEFAULT, QUEUE_DEFAULT, PARTITION_HPSS, + QUEUE_HPSS, PARTITION_FCST, QUEUE_FCST, REMOVE_MEMORY, RUN_CMD_SERIAL, RUN_CMD_UTILS, RUN_CMD_FCST, RUN_CMD_POST, RUN_CMD_PRDGEN, RUN_CMD_AQM, + RUN_CMD_AQMLBC, SCHED_NATIVE_CMD, MET_INSTALL_DIR, MET_BIN_EXEC, METPLUS_PATH, CCPA_OBS_DIR, MRMS_OBS_DIR, NDAS_OBS_DIR, DOMAIN_PREGEN_BASEDIR, PRE_TASK_CMDS, + TEST_EXTRN_MDL_SOURCE_BASEDIR, TEST_AQM_INPUT_BASEDIR, TEST_PREGEN_BASEDIR, TEST_ALT_EXTRN_MDL_SYSBASEDIR_ICS, TEST_ALT_EXTRN_MDL_SYSBASEDIR_LBCS, + TEST_VX_FCST_INPUT_BASEDIR, FIXgsm, FIXaer, FIXlut, FIXorg, FIXsfc, FIXshp, FIXgsi, FIXcrtm, FIXcrtmupp, EXTRN_MDL_DATA_STORES + * - Workflow + - WORKFLOW_ID, RELATIVE_LINK_FLAG, USE_CRON_TO_RELAUNCH, CRON_RELAUNCH_INTVL_MNTS, CRONTAB_LINE, LOAD_MODULES_RUN_TASK_FP, EXPT_BASEDIR, EXPT_SUBDIR, EXEC_SUBDIR, + EXPTDIR, DOT_OR_USCORE, EXPT_CONFIG_FN, CONSTANTS_FN, RGNL_GRID_NML_FN, FV3_NML_FN, FV3_NML_BASE_SUITE_FN, FV3_NML_YAML_CONFIG_FN, FV3_NML_BASE_ENS_FN, + FV3_EXEC_FN, DATA_TABLE_FN, DIAG_TABLE_FN, FIELD_TABLE_FN, DIAG_TABLE_TMPL_FN, FIELD_TABLE_TMPL_FN, MODEL_CONFIG_FN, NEMS_CONFIG_FN, AQM_RC_FN, AQM_RC_TMPL_FN, + FV3_NML_BASE_SUITE_FP, FV3_NML_YAML_CONFIG_FP, FV3_NML_BASE_ENS_FP, DATA_TABLE_TMPL_FP, DIAG_TABLE_TMPL_FP, FIELD_TABLE_TMPL_FP, + MODEL_CONFIG_TMPL_FP, NEMS_CONFIG_TMPL_FP, AQM_RC_TMPL_FP, DATA_TABLE_FP, FIELD_TABLE_FP, NEMS_CONFIG_FP, FV3_NML_FP, FV3_NML_CYCSFC_FP, + FV3_NML_RESTART_FP, FV3_NML_STOCH_FP, FV3_NML_RESTART_STOCH_FP, FCST_MODEL, WFLOW_XML_FN, GLOBAL_VAR_DEFNS_FN, ROCOTO_YAML_FN, EXTRN_MDL_VAR_DEFNS_FN, + WFLOW_LAUNCH_SCRIPT_FN, WFLOW_LAUNCH_LOG_FN, GLOBAL_VAR_DEFNS_FP, ROCOTO_YAML_FP, WFLOW_LAUNCH_SCRIPT_FP, WFLOW_LAUNCH_LOG_FP, FIXdir, FIXam, + FIXclim, FIXlam, THOMPSON_MP_CLIMO_FN, THOMPSON_MP_CLIMO_FP, CCPP_PHYS_SUITE, CCPP_PHYS_SUITE_FN, CCPP_PHYS_SUITE_IN_CCPP_FP, CCPP_PHYS_SUITE_FP, + FIELD_DICT_FN, FIELD_DICT_IN_UWM_FP, FIELD_DICT_FP, GRID_GEN_METHOD, PREDEF_GRID_NAME, DATE_FIRST_CYCL, DATE_LAST_CYCL, INCR_CYCL_FREQ, FCST_LEN_HRS, + FCST_LEN_CYCL, LONG_FCST_LEN, CYCL_HRS_SPINSTART, CYCL_HRS_PRODSTART, BOUNDARY_LEN_HRS, BOUNDARY_LONG_LEN_HRS, BOUNDARY_PROC_GROUP_NUM, + PREEXISTING_DIR_METHOD, VERBOSE, DEBUG, COMPILER, SYMLINK_FIX_FILES, DO_REAL_TIME, COLDSTART, WARMSTART_CYCLE_DIR, + * - + - + * - NCO + - envir, NET, model_ver, RUN, OPSROOT + * - task_make_grid + - GRID_DIR, ESGgrid_LON_CTR, ESGgrid_LAT_CTR, ESGgrid_DELX, ESGgrid_DELY, ESGgrid_NX, ESGgrid_NY, ESGgrid_PAZI, ESGgrid_WIDE_HALO_WIDTH, + GFDLgrid_LON_T6_CTR, GFDLgrid_LAT_T6_CTR, GFDLgrid_NUM_CELLS, GFDLgrid_STRETCH_FAC, GFDLgrid_REFINE_RATIO, GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G, + GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G, GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G, GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G, GFDLgrid_USE_NUM_CELLS_IN_FILENAMES + * - task_make_orog + - KMP_AFFINITY_MAKE_OROG, OMP_NUM_THREADS_MAKE_OROG, OMP_STACKSIZE_MAKE_OROG, OROG_DIR + * - task_make_sfc_climo + - KMP_AFFINITY_MAKE_SFC_CLIMO, OMP_NUM_THREADS_MAKE_SFC_CLIMO, OMP_STACKSIZE_MAKE_SFC_CLIMO, SFC_CLIMO_DIR + * - task_get_extrn_ics + - EXTRN_MDL_NAME_ICS, EXTRN_MDL_ICS_OFFSET_HRS, FV3GFS_FILE_FMT_ICS, EXTRN_MDL_SYSBASEDIR_ICS, USE_USER_STAGED_EXTRN_FILES, + EXTRN_MDL_SOURCE_BASEDIR_ICS, EXTRN_MDL_FILES_ICS, EXTRN_MDL_FILES_ICS, EXTRN_MDL_FILES_ICS, EXTRN_MDL_DATA_STORES, NOMADS, NOMADS_file_type + * - task_get_extrn_lbcs + - EXTRN_MDL_NAME_LBCS, LBC_SPEC_INTVL_HRS, EXTRN_MDL_LBCS_OFFSET_HRS, FV3GFS_FILE_FMT_LBCS, EXTRN_MDL_SYSBASEDIR_LBCS, + USE_USER_STAGED_EXTRN_FILES, EXTRN_MDL_SOURCE_BASEDIR_LBCS, EXTRN_MDL_FILES_LBCS, EXTRN_MDL_DATA_STORE, NOMADS, NOMADS_file_type + * - task_make_ics + - KMP_AFFINITY_MAKE_ICS, OMP_NUM_THREADS_MAKE_ICS, OMP_STACKSIZE_MAKE_ICS, USE_FVCOM, FVCOM_WCSTART, FVCOM_DIR, FVCOM_FILE + * - task_make_lbcs + - KMP_AFFINITY_MAKE_LBCS, OMP_NUM_THREADS_MAKE_LBCS, OMP_STACKSIZE_MAKE_LBCS + * - task_run_fcst + - KMP_AFFINITY_RUN_FCST, OMP_NUM_THREADS_RUN_FCST, OMP_STACKSIZE_RUN_FCST, DT_ATMOS, RESTART_INTERVAL, WRITE_DOPOST, + LAYOUT_X, LAYOUT_Y, BLOCKSIZE, QUILTING, PRINT_ESMF, WRTCMP_write_groups, WRTCMP_write_tasks_per_group, 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, PREDEF_GRID_NAME, USE_MERRA_CLIMO, + SFC_CLIMO_FIELDS, FIXgsm, FIXaer, FIXlut, TOPO_DIR, SFC_CLIMO_INPUT_DIR, SYMLINK_FIX_FILES, 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 + * - task_run_post + - KMP_AFFINITY_RUN_POST, OMP_NUM_THREADS_RUN_POST, OMP_STACKSIZE_RUN_POST, SUB_HOURLY_POST, DT_SUB_HOURLY_POST_MNTS, + USE_CUSTOM_POST_CONFIG_FILE, CUSTOM_POST_CONFIG_FP, POST_OUTPUT_DOMAIN_NAME + * - Global + - USE_CRTM, CRTM_DIR, DO_ENSEMBLE, NUM_ENS_MEMBERS, NEW_LSCALE, DO_SHUM, ISEED_SHUM, SHUM_MAG, SHUM_LSCALE, SHUM_TSCALE, SHUM_INT, + DO_SPPT, ISEED_SPPT, SPPT_MAG, SPPT_LOGIT, SPPT_LSCALE, SPPT_TSCALE, SPPT_INT, SPPT_SFCLIMIT, USE_ZMTNBLCK, DO_SKEB, ISEED_SKEB, + SKEB_MAG, SKEB_LSCALE, SKEP_TSCALE, SKEB_INT, SKEBNORM, SKEB_VDOF, DO_SPP, ISEED_SPP, SPP_VAR_LIST, SPP_MAG_LIST, SPP_LSCALE, + SPP_TSCALE, SPP_SIGTOP1, SPP_SIGTOP2, SPP_STDDEV_CUTOFF, DO_LSM_SPP, LSM_SPP_TSCALE, LSM_SPP_LSCALE, ISEED_LSM_SPP, LSM_SPP_VAR_LIST, + LSM_SPP_MAG_LIST, HALO_BLEND diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 4c11080962..49eecbb4eb 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -238,112 +238,14 @@ Set Experiment Configuration Parameters Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in ``config_defaults.yaml`` and in the user-specified ``config.yaml`` file. When generating a new experiment, the SRW App first reads and assigns default values from ``config_defaults.yaml``. Then, it reads and (re)assigns variables from the user's custom ``config.yaml`` file. -For background info on ``config_defaults.yaml``, read :numref:`Section %s `, or jump to :numref:`Section %s ` to continue configuring the experiment. +For background info on ``config_defaults.yaml``, read :numref:`Section %s ` below, or jump to :numref:`Section %s ` to continue configuring the experiment if they prefer. .. _DefaultConfigSection: Default configuration: ``config_defaults.yaml`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. note:: - This section provides background information on available parameters and how the SRW App uses the ``config_defaults.yaml`` file. It is informative, but users do not need to modify ``config_defaults.yaml`` to run the out-of-the-box case for the SRW App. Therefore, users may skip to :numref:`Step %s ` to continue configuring their experiment. - -Configuration parameters in the ``config_defaults.yaml`` 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.yaml`` file. Any settings provided in ``config.yaml`` will override the settings in ``config_defaults.yaml``. 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 ``config_defaults.yaml`` file comments and in :numref:`Chapter %s `. - -.. _ConfigVarsDefault: - -.. table:: Configuration variables specified in the config_defaults.yaml script - - +-----------------------------+-----------------------------------------------------------------------+ - | **Group Name** | **Configuration variables** | - +=============================+=======================================================================+ - | User | RUN_ENVIR, MACHINE, MACHINE_FILE, ACCOUNT | - +-----------------------------+-----------------------------------------------------------------------+ - | Platform | WORKFLOW_MANAGER, NCORES_PER_NODE, BUILD_MOD_FN, WFLOW_MOD_FN, | - | | BUILD_VER_FN, RUN_VER_FN, SCHED, DOMAIN_PREGEN_BASEDIR, | - | | ENV_INIT_SCRIPTS_FPS, PRE_TASK_CMDS, PARTITION_DEFAULT, QUEUE_DEFAULT,| - | | PARTITION_HPSS, QUEUE_HPSS, PARTITION_FCST, QUEUE_FCST, | - | | RUN_CMD_UTILS, RUN_CMD_FCST, RUN_CMD_POST, SLURM_NATIVE_CMD, | - | | MODEL, MET_INSTALL_DIR, METPLUS_PATH, MET_BIN_EXEC, CCPA_OBS_DIR, | - | | MRMS_OBS_DIR, NDAS_OBS_DIR | - +-----------------------------+-----------------------------------------------------------------------+ - | Workflow | WORKFLOW_ID, USE_CRON_TO_RELAUNCH, CRON_RELAUNCH_INTVL_MNTS, | - | | EXPT_BASEDIR, EXPT_SUBDIR, EXEC_SUBDIR, DOT_OR_USCORE, | - | | EXPT_CONFIG_FN, CONSTANTS_FN, RGNL_GRID_NML_FN, | - | | FV3_NML_BASE_SUITE_FN, FV3_NML_YAML_CONFIG_FN, FV3_NML_BASE_ENS_FN, | - | | FV3_EXEC_FN, DIAG_TABLE_TMPL_FN, FIELD_TABLE_TMPL_FN, | - | | DATA_TABLE_TMPL_FN, MODEL_CONFIG_TMPL_FN, NEMS_CONFIG_TMPL_FN, | - | | FCST_MODEL, WFLOW_XML_FN, GLOBAL_VAR_DEFNS_FN, | - | | EXTRN_MDL_VAR_DEFNS_FN, WFLOW_LAUNCH_SCRIPT_FN, WFLOW_LAUNCH_LOG_FN, | - | | CCPP_PHYS_SUITE, GRID_GEN_METHOD, DATE_FIRST_CYCL, DATE_LAST_CYCL, | - | | INCR_CYCL_FREQ, FCST_LEN_HRS, GET_OBS, MAXTRIES_VX_ENSGRID_PROB_REFC, | - | | PREEXISTING_DIR_METHOD, VERBOSE, DEBUG, COMPILER | - +-----------------------------+-----------------------------------------------------------------------+ - | NCO | envir, NET, model_ver, RUN, OPSROOT | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_grid | GRID_DIR, ESGgrid_LON_CTR, ESGgrid_LAT_CTR, | - | | ESGgrid_DELX, ESGgrid_DELY, ESGgrid_NX, ESGgrid_NY, ESGgrid_PAZI, | - | | ESGgrid_WIDE_HALO_WIDTH, GFDLgrid_LON_T6_CTR, GFDLgrid_LAT_T6_CTR, | - | | GFDLgrid_NUM_CELLS, GFDLgrid_STRETCH_FAC, GFDLgrid_REFINE_RATIO, | - | | GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G, GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G, | - | | GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G, GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G, | - | | GFDLgrid_USE_NUM_CELLS_IN_FILENAMES | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_orog | KMP_AFFINITY_MAKE_OROG, OMP_NUM_THREADS_MAKE_OROG | - | | OMP_STACKSIZE_MAKE_OROG, OROG_DIR | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_sfc_climo | KMP_AFFINITY_MAKE_SFC_CLIMO, OMP_NUM_THREADS_MAKE_SFC_CLIMO, | - | | OMP_STACKSIZE_MAKE_SFC_CLIMO, SFC_CLIMO_DIR | - +-----------------------------+-----------------------------------------------------------------------+ - | task_get_extrn_ics | EXTRN_MDL_NAME_ICS, EXTRN_MDL_ICS_OFFSET_HRS, FV3GFS_FILE_FMT_ICS, | - | | EXTRN_MDL_SYSBASEDIR_ICS, USE_USER_STAGED_EXTRN_FILES, | - | | EXTRN_MDL_SOURCE_BASEDIR_ICS, EXTRN_MDL_FILES_ICS, | - | | EXTRN_MDL_FILES_ICS, EXTRN_MDL_FILES_ICS, EXTRN_MDL_DATA_STORES, | - | | NOMADS, NOMADS_file_type | - +-----------------------------+-----------------------------------------------------------------------+ - | task_get_extrn_lbcs | EXTRN_MDL_NAME_LBCS, | - | | LBC_SPEC_INTVL_HRS, EXTRN_MDL_LBCS_OFFSET_HRS, FV3GFS_FILE_FMT_LBCS, | - | | EXTRN_MDL_SYSBASEDIR_LBCS, USE_USER_STAGED_EXTRN_FILES, | - | | EXTRN_MDL_SOURCE_BASEDIR_LBCS, EXTRN_MDL_FILES_LBCS, | - | | EXTRN_MDL_DATA_STORE, NOMADS, NOMADS_file_type | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_ics | KMP_AFFINITY_MAKE_ICS, OMP_NUM_THREADS_MAKE_ICS, | - | | OMP_STACKSIZE_MAKE_ICS, USE_FVCOM, FVCOM_WCSTART, FVCOM_DIR, | - | | FVCOM_FILE | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_lbcs | KMP_AFFINITY_MAKE_LBCS, OMP_NUM_THREADS_MAKE_LBCS, | - | | OMP_STACKSIZE_MAKE_LBCS | - +-----------------------------+-----------------------------------------------------------------------+ - | task_run_fcst | KMP_AFFINITY_RUN_FCST, OMP_NUM_THREADS_RUN_FCST, | - | | OMP_STACKSIZE_RUN_FCST, DT_ATMOS, RESTART_INTERVAL, WRITE_DOPOST, | - | | LAYOUT_X, LAYOUT_Y, BLOCKSIZE, QUILTING, PRINT_ESMF, | - | | WRTCMP_write_groups, WRTCMP_write_tasks_per_group, | - | | 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, PREDEF_GRID_NAME, USE_MERRA_CLIMO, | - | | SFC_CLIMO_FIELDS, FIXgsm, FIXaer, FIXlut, TOPO_DIR, | - | | SFC_CLIMO_INPUT_DIR, SYMLINK_FIX_FILES, 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 | - +-----------------------------+-----------------------------------------------------------------------+ - | task_run_post | KMP_AFFINITY_RUN_POST, OMP_NUM_THREADS_RUN_POST, | - | | OMP_STACKSIZE_RUN_POST, SUB_HOURLY_POST, DT_SUB_HOURLY_POST_MNTS, | - | | USE_CUSTOM_POST_CONFIG_FILE, CUSTOM_POST_CONFIG_FP, | - | | POST_OUTPUT_DOMAIN_NAME | - +-----------------------------+-----------------------------------------------------------------------+ - | Global | USE_CRTM, CRTM_DIR, DO_ENSEMBLE, NUM_ENS_MEMBERS, | - | | NEW_LSCALE, DO_SHUM, ISEED_SHUM, SHUM_MAG, SHUM_LSCALE, SHUM_TSCALE, | - | | SHUM_INT, DO_SPPT, ISEED_SPPT, SPPT_MAG, SPPT_LOGIT, SPPT_LSCALE, | - | | SPPT_TSCALE, SPPT_INT, SPPT_SFCLIMIT, USE_ZMTNBLCK, DO_SKEB, | - | | ISEED_SKEB, SKEB_MAG, SKEB_LSCALE, SKEP_TSCALE, SKEB_INT, SKEBNORM, | - | | SKEB_VDOF, DO_SPP, ISEED_SPP, SPP_VAR_LIST, SPP_MAG_LIST, SPP_LSCALE, | - | | SPP_TSCALE, SPP_SIGTOP1, SPP_SIGTOP2, SPP_STDDEV_CUTOFF, DO_LSM_SPP, | - | | LSM_SPP_TSCALE, LSM_SPP_LSCALE, ISEED_LSM_SPP, LSM_SPP_VAR_LIST, | - | | LSM_SPP_MAG_LIST, HALO_BLEND | - +-----------------------------+-----------------------------------------------------------------------+ +Configuration parameters in the ``config_defaults.yaml`` file appear in :doc:`this table `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified ``config.yaml`` file. Any settings provided in ``config.yaml`` will override the settings in ``config_defaults.yaml``. 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 ``config_defaults.yaml`` file comments and in :numref:`Section %s: Workflow Parameters `. .. _UserSpecificConfig: From 36b2901bbcbba321213f7655e1e1d673acc06701 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 11 Jul 2023 22:22:48 -0400 Subject: [PATCH 019/116] update run ch & tables --- .../source/BackgroundInfo/Components.rst | 3 +- .../DefaultVarsTable.rst | 75 ++++++++--- .../source/BuildingRunningTesting/RunSRW.rst | 118 ++++++++---------- 3 files changed, 110 insertions(+), 86 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Components.rst b/docs/UsersGuide/source/BackgroundInfo/Components.rst index 05c28cf485..c7e71d3425 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Components.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Components.rst @@ -71,7 +71,8 @@ METplus is being actively developed by :term:`NCAR`/Research Applications Labora Air Quality Modeling (AQM) Utilities ======================================= -For more information on AQM Utilities (AQM-utils), visit the GitHub repository at https://github.com/NOAA-EMC/AQM-utils. +AQM Utilities (AQM-utils) includes the utility executables and python scripts to run SRW-AQM (Online-CMAQ). +For more information on AQM-utils, visit the GitHub repository at https://github.com/NOAA-EMC/AQM-utils. NOAA Emission and eXchange Unified System (NEXUS) =================================================== diff --git a/docs/UsersGuide/source/BuildingRunningTesting/DefaultVarsTable.rst b/docs/UsersGuide/source/BuildingRunningTesting/DefaultVarsTable.rst index 063676675e..c115c159e1 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/DefaultVarsTable.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/DefaultVarsTable.rst @@ -30,12 +30,19 @@ Table of Variables in ``config_defaults.yaml`` FIELD_DICT_FN, FIELD_DICT_IN_UWM_FP, FIELD_DICT_FP, GRID_GEN_METHOD, PREDEF_GRID_NAME, DATE_FIRST_CYCL, DATE_LAST_CYCL, INCR_CYCL_FREQ, FCST_LEN_HRS, FCST_LEN_CYCL, LONG_FCST_LEN, CYCL_HRS_SPINSTART, CYCL_HRS_PRODSTART, BOUNDARY_LEN_HRS, BOUNDARY_LONG_LEN_HRS, BOUNDARY_PROC_GROUP_NUM, PREEXISTING_DIR_METHOD, VERBOSE, DEBUG, COMPILER, SYMLINK_FIX_FILES, DO_REAL_TIME, COLDSTART, WARMSTART_CYCLE_DIR, - * - - - * - NCO - - envir, NET, model_ver, RUN, OPSROOT + - envir_default, NET_default, RUN_default, model_ver_default, OPSROOT_default, COMROOT_default, DATAROOT_default, DCOMROOT_default, LOGBASEDIR_default, + COMIN_BASEDIR, COMOUT_BASEDIR, NWGES, NWGES_BASEDIR, DBNROOT_default, SENDECF_default, SENDDBN_default, SENDDBN_NTC_default, SENDCOM_default, + SENDWEB_default, KEEPDATA_default, MAILTO_default, MAILCC_default + * - gsi + - niter1, niter2, l_obsprvdiag, diag_radardbz, write_diag_2, bkgerr_vs, bkgerr_hzscl, usenewgfsberror, netcdf_diag, binary_diag, readin_localization, + beta1_inv, ens_h, ens_v, regional_ensemble_option, grid_ratio_fv3, grid_ratio_ens, i_en_perts_io, q_hyb_ens, ens_fast_read, l_PBL_pseudo_SurfobsT, + l_PBL_pseudo_SurfobsQ, i_use_2mQ4B, i_use_2mT4B, i_T_Q_adjust, l_rtma3d, i_precip_vertical_check, HYBENSMEM_NMIN, ANAVINFO_FN, ANAVINFO_DBZ_FN, + ENKF_ANAVINFO_FN, ENKF_ANAVINFO_DBZ_FN, CONVINFO_FN, BERROR_FN, OBERROR_FN, HYBENSINFO_FN, cld_bld_hgt, l_precip_clear_only, l_qnr_from_qr, beta_recenter + * - rrfs + - DO_RRFS_DEV, DO_NLDN_LGHT, DO_ENKFUPDATE, DO_DACYCLE, DO_SURFACE_CYCLE * - task_make_grid - - GRID_DIR, ESGgrid_LON_CTR, ESGgrid_LAT_CTR, ESGgrid_DELX, ESGgrid_DELY, ESGgrid_NX, ESGgrid_NY, ESGgrid_PAZI, ESGgrid_WIDE_HALO_WIDTH, + - GRID_DIR, ESGgrid_LON_CTR, ESGgrid_LAT_CTR, ESGgrid_DELX, ESGgrid_DELY, ESGgrid_NX, ESGgrid_NY, ESGgrid_WIDE_HALO_WIDTH, ESGgrid_PAZI, GFDLgrid_LON_T6_CTR, GFDLgrid_LAT_T6_CTR, GFDLgrid_NUM_CELLS, GFDLgrid_STRETCH_FAC, GFDLgrid_REFINE_RATIO, GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G, GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G, GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G, GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G, GFDLgrid_USE_NUM_CELLS_IN_FILENAMES * - task_make_orog @@ -44,28 +51,56 @@ Table of Variables in ``config_defaults.yaml`` - KMP_AFFINITY_MAKE_SFC_CLIMO, OMP_NUM_THREADS_MAKE_SFC_CLIMO, OMP_STACKSIZE_MAKE_SFC_CLIMO, SFC_CLIMO_DIR * - task_get_extrn_ics - EXTRN_MDL_NAME_ICS, EXTRN_MDL_ICS_OFFSET_HRS, FV3GFS_FILE_FMT_ICS, EXTRN_MDL_SYSBASEDIR_ICS, USE_USER_STAGED_EXTRN_FILES, - EXTRN_MDL_SOURCE_BASEDIR_ICS, EXTRN_MDL_FILES_ICS, EXTRN_MDL_FILES_ICS, EXTRN_MDL_FILES_ICS, EXTRN_MDL_DATA_STORES, NOMADS, NOMADS_file_type + EXTRN_MDL_SOURCE_BASEDIR_ICS, EXTRN_MDL_FILES_ICS * - task_get_extrn_lbcs - - EXTRN_MDL_NAME_LBCS, LBC_SPEC_INTVL_HRS, EXTRN_MDL_LBCS_OFFSET_HRS, FV3GFS_FILE_FMT_LBCS, EXTRN_MDL_SYSBASEDIR_LBCS, - USE_USER_STAGED_EXTRN_FILES, EXTRN_MDL_SOURCE_BASEDIR_LBCS, EXTRN_MDL_FILES_LBCS, EXTRN_MDL_DATA_STORE, NOMADS, NOMADS_file_type + - EXTRN_MDL_NAME_LBCS, LBC_SPEC_INTVL_HRS, EXTRN_MDL_LBCS_OFFSET_HRS, FV3GFS_FILE_FMT_LBCS, LBCS_SEARCH_HRS, EXTRN_MDL_LBCS_SEARCH_OFFSET_HRS, EXTRN_MDL_SYSBASEDIR_LBCS, + USE_USER_STAGED_EXTRN_FILES,EXTRN_MDL_SOURCE_BASEDIR_LBCS, EXTRN_MDL_FILES_LBCS * - task_make_ics - - KMP_AFFINITY_MAKE_ICS, OMP_NUM_THREADS_MAKE_ICS, OMP_STACKSIZE_MAKE_ICS, USE_FVCOM, FVCOM_WCSTART, FVCOM_DIR, FVCOM_FILE + - KMP_AFFINITY_MAKE_ICS, OMP_NUM_THREADS_MAKE_ICS, OMP_STACKSIZE_MAKE_ICS, USE_FVCOM, FVCOM_WCSTART, FVCOM_DIR, FVCOM_FILE, VCOORD_FILE * - task_make_lbcs - - KMP_AFFINITY_MAKE_LBCS, OMP_NUM_THREADS_MAKE_LBCS, OMP_STACKSIZE_MAKE_LBCS + - KMP_AFFINITY_MAKE_LBCS, OMP_NUM_THREADS_MAKE_LBCS, OMP_STACKSIZE_MAKE_LBCS, VCOORD_FILE * - task_run_fcst - - KMP_AFFINITY_RUN_FCST, OMP_NUM_THREADS_RUN_FCST, OMP_STACKSIZE_RUN_FCST, DT_ATMOS, RESTART_INTERVAL, WRITE_DOPOST, - LAYOUT_X, LAYOUT_Y, BLOCKSIZE, QUILTING, PRINT_ESMF, WRTCMP_write_groups, WRTCMP_write_tasks_per_group, WRTCMP_cen_lon, + - NNODES_RUN_FCST, PPN_RUN_FCST, FV3_EXEC_FP, IO_LAYOUT_Y, KMP_AFFINITY_RUN_FCST, OMP_NUM_THREADS_RUN_FCST, OMP_STACKSIZE_RUN_FCST, DT_ATMOS, FHROT, RESTART_INTERVAL, WRITE_DOPOST, + LAYOUT_X, LAYOUT_Y, BLOCKSIZE, QUILTING, PRINT_ESMF, PE_MEMBER01, 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, PREDEF_GRID_NAME, USE_MERRA_CLIMO, - SFC_CLIMO_FIELDS, FIXgsm, FIXaer, FIXlut, TOPO_DIR, SFC_CLIMO_INPUT_DIR, SYMLINK_FIX_FILES, 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 + WRTCMP_dlat, WRTCMP_stdlat1, WRTCMP_stdlat2, WRTCMP_nx, WRTCMP_ny, WRTCMP_dx, WRTCMP_dy, USE_MERRA_CLIMO, DO_FCST_RESTART * - task_run_post - KMP_AFFINITY_RUN_POST, OMP_NUM_THREADS_RUN_POST, OMP_STACKSIZE_RUN_POST, SUB_HOURLY_POST, DT_SUB_HOURLY_POST_MNTS, - USE_CUSTOM_POST_CONFIG_FILE, CUSTOM_POST_CONFIG_FP, POST_OUTPUT_DOMAIN_NAME + USE_CUSTOM_POST_CONFIG_FILE, CUSTOM_POST_CONFIG_FP, POST_OUTPUT_DOMAIN_NAME, TESTBED_FIELDS_FN + * - task_run_prdgen: + - KMP_AFFINITY_RUN_PRDGEN, OMP_NUM_THREADS_RUN_PRDGEN, OMP_STACKSIZE_RUN_PRDGEN, DO_PARALLEL_PRDGEN, ADDNL_OUTPUT_GRIDS: [] + * - task_plot_allvars: + - COMOUT_REF, PLOT_FCST_START, PLOT_FCST_INC, PLOT_FCST_END, PLOT_DOMAINS + * - task_analysis_gsi + - TN_ANALYSIS_GSI, TN_OBSERVER_GSI, TN_OBSERVER_GSI_ENSMEAN, KMP_AFFINITY_ANALYSIS, OMP_NUM_THREADS_ANALYSIS, OMP_STACKSIZE_ANALYSIS, OBSPATH_TEMPLATE + * - task_process_radarref + - RADAR_REF_THINNING, RADARREFL_MINS, RADARREFL_TIMELEVEL, OBS_SUFFIX + * - task_get_da_obs + - NLDN_NEEDED, NLDN_LIGHTNING, NSSLMOSAIC, RAP_OBS_BUFR + * - task_process_bufrobs + - OBSPATH_TEMPLATE + * - task_nexus_emission + - PPN_NEXUS_EMISSION, KMP_AFFINITY_NEXUS_EMISSION, OMP_NUM_THREADS_NEXUS_EMISSION, OMP_STACKSIZE_NEXUS_EMISSION + * - task_bias_correction_o3 + - KMP_AFFINITY_BIAS_CORRECTION_O3, OMP_NUM_THREADS_BIAS_CORRECTION_O3, OMP_STACKSIZE_BIAS_CORRECTION_O3 + * - task_bias_correction_pm25 + - KMP_AFFINITY_BIAS_CORRECTION_PM25, OMP_NUM_THREADS_BIAS_CORRECTION_PM25, OMP_STACKSIZE_BIAS_CORRECTION_PM25 * - Global - - USE_CRTM, CRTM_DIR, DO_ENSEMBLE, NUM_ENS_MEMBERS, NEW_LSCALE, DO_SHUM, ISEED_SHUM, SHUM_MAG, SHUM_LSCALE, SHUM_TSCALE, SHUM_INT, - DO_SPPT, ISEED_SPPT, SPPT_MAG, SPPT_LOGIT, SPPT_LSCALE, SPPT_TSCALE, SPPT_INT, SPPT_SFCLIMIT, USE_ZMTNBLCK, DO_SKEB, ISEED_SKEB, - SKEB_MAG, SKEB_LSCALE, SKEP_TSCALE, SKEB_INT, SKEBNORM, SKEB_VDOF, DO_SPP, ISEED_SPP, SPP_VAR_LIST, SPP_MAG_LIST, SPP_LSCALE, + - USE_CRTM, CRTM_DIR, DO_ENSEMBLE, NUM_ENS_MEMBERS, ENSMEM_NAMES, FV3_NML_ENSMEM_FPS, ENS_TIME_LAG_HRS, DO_SHUM, DO_SPPT, DO_SKEB, ISEED_SHUM, ISEED_SPPT, ISEED_SKEB, NEW_LSCALE, SHUM_MAG, SHUM_LSCALE, SHUM_TSCALE, SHUM_INT, + SPPT_MAG, SPPT_LOGIT, SPPT_LSCALE, SPPT_TSCALE, SPPT_INT, SPPT_SFCLIMIT, + SKEB_MAG, SKEB_LSCALE, SKEP_TSCALE, SKEB_INT, SKEBNORM, SKEB_VDOF, USE_ZMTNBLCK, DO_SPP, ISEED_SPP, SPP_VAR_LIST, SPP_MAG_LIST, SPP_LSCALE, SPP_TSCALE, SPP_SIGTOP1, SPP_SIGTOP2, SPP_STDDEV_CUTOFF, DO_LSM_SPP, LSM_SPP_TSCALE, LSM_SPP_LSCALE, ISEED_LSM_SPP, LSM_SPP_VAR_LIST, - LSM_SPP_MAG_LIST, HALO_BLEND + LSM_SPP_MAG_LIST, HALO_BLEND, PRINT_DIFF_PGR + * - Verification + - OBS_CCPA_APCP01h_FN_TEMPLATE, OBS_CCPA_APCPgt01h_FN_TEMPLATE, OBS_MRMS_REFC_FN_TEMPLATE, OBS_MRMS_RETOP_FN_TEMPLATE, + OBS_NDAS_SFCorUPA_FN_TEMPLATE, OBS_NDAS_SFCorUPA_FN_METPROC_TEMPLATE, VX_FCST_MODEL_NAME, VX_FIELDS, VX_APCP_ACCUMS_HRS, VX_FCST_INPUT_BASEDIR, + VX_OUTPUT_BASEDIR, VX_NDIGITS_ENSMEM_NAMES, FCST_SUBDIR_TEMPLATE, FCST_FN_TEMPLATE, FCST_FN_METPROC_TEMPLATE, NUM_MISSING_OBS_FILES_MAX, NUM_MISSING_FCST_FILES_MAX + * - cpl_aqm_parm + - CPL_AQM, DO_AQM_DUST, DO_AQM_CANOPY, DO_AQM_PRODUCT, DO_AQM_CHEM_LBCS, DO_AQM_GEFS_LBCS, DO_AQM_SAVE_AIRNOW_HIST, DO_AQM_SAVE_FIRE, DCOMINbio_default, + DCOMINdust_default, DCOMINcanopy_default, DCOMINfire_default, DCOMINchem_lbcs_default, DCOMINgefs_default, DCOMINpt_src_default, + DCOMINairnow_default, COMINbicor, COMOUTbicor, AQM_CONFIG_DIR, AQM_BIO_FILE, AQM_DUST_FILE_PREFIX, AQM_DUST_FILE_SUFFIX, AQM_CANOPY_FILE_PREFIX, + AQM_CANOPY_FILE_SUFFIX, AQM_FIRE_FILE_PREFIX, AQM_FIRE_FILE_SUFFIX, AQM_FIRE_FILE_OFFSET_HRS, AQM_FIRE_ARCHV_DIR, AQM_RC_FIRE_FREQUENCY, + AQM_RC_PRODUCT_FN, AQM_RC_PRODUCT_FREQUENCY, AQM_LBCS_FILES, AQM_GEFS_FILE_PREFIX, AQM_GEFS_FILE_CYC, NEXUS_INPUT_DIR, NEXUS_FIX_DIR, + NEXUS_GRID_FN, NUM_SPLIT_NEXUS: 3NEXUS_GFS_SFC_OFFSET_HRS, NEXUS_GFS_SFC_DIR, NEXUS_GFS_SFC_ARCHV_DIR + * - Rocoto + - attrs, cycledefs, entities, log, tasks: taskgroups diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 49eecbb4eb..a707722646 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -236,23 +236,21 @@ After running ``conda activate workflow_tools``, the user will typically see ``( Set Experiment Configuration Parameters ------------------------------------------ -Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in ``config_defaults.yaml`` and in the user-specified ``config.yaml`` file. When generating a new experiment, the SRW App first reads and assigns default values from ``config_defaults.yaml``. Then, it reads and (re)assigns variables from the user's custom ``config.yaml`` file. - -For background info on ``config_defaults.yaml``, read :numref:`Section %s ` below, or jump to :numref:`Section %s ` to continue configuring the experiment if they prefer. +Each experiment requires certain basic information to run (e.g., date, grid, physics suite). Default values are assigned in ``config_defaults.yaml``, and users adjust the desired variables in the experiment configuration file named ``config.yaml``. When generating a new experiment, the SRW App first reads and assigns default values from ``config_defaults.yaml``. Then, it reads and (re)assigns variables from the user's custom ``config.yaml`` file. .. _DefaultConfigSection: Default configuration: ``config_defaults.yaml`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Configuration parameters in the ``config_defaults.yaml`` file appear in :doc:`this table `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in the user-specified ``config.yaml`` file. Any settings provided in ``config.yaml`` will override the settings in ``config_defaults.yaml``. 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 ``config_defaults.yaml`` file comments and in :numref:`Section %s: Workflow Parameters `. +In general, ``config_defaults.yaml`` is split into sections by category (e.g., ``user:``, ``platform:``, ``workflow:``, ``task_make_grid:``). Users can view a full list of categories and configuration parameters in the :doc:`Table of Variables in config_defaults.yaml `. Definitions and default values of each of the variables can be found in the ``config_defaults.yaml`` file comments and in :numref:`Section %s: Workflow Parameters `. Some of these default values are intentionally invalid in order to ensure that the user assigns valid values in their ``config.yaml`` file. There is usually no need for a user to modify ``config_defaults.yaml`` because any settings provided in ``config.yaml`` will override the settings in ``config_defaults.yaml``. .. _UserSpecificConfig: User-specific configuration: ``config.yaml`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The user must specify certain basic experiment configuration information in a ``config.yaml`` file located in the ``ufs-srweather-app/ush`` directory. Two example templates are provided in that directory: ``config.community.yaml`` and ``config.nco.yaml``. The first file is a minimal example for creating and running an experiment in *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 is fully supported for this release. The operational/NCO mode is typically used by developers at the Environmental Modeling Center (:term:`EMC`) and at the Global Systems Laboratory (:term:`GSL`) working on pre-implementation testing for the Rapid Refresh Forecast System (RRFS). :numref:`Table %s ` compares the configuration variables that appear in the ``config.community.yaml`` with their default values in ``config_default.yaml``. +The user must set the specifics of their experiment configuration in a ``config.yaml`` file located in the ``ufs-srweather-app/ush`` directory. Two example templates are provided in that directory: ``config.community.yaml`` and ``config.nco.yaml``. The first file is a basic example for creating and running an experiment in *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 user support is available for running in community mode. The operational/NCO mode is typically used by developers at the Environmental Modeling Center (:term:`EMC`) and the Global Systems Laboratory (:term:`GSL`) who are working on pre-implementation testing for the Rapid Refresh Forecast System (:term:`RRFS`). :numref:`Table %s ` compares the configuration variables that appear in the ``config.community.yaml`` with their default values in ``config_default.yaml``. .. _ConfigCommunity: @@ -267,22 +265,24 @@ The user must specify certain basic experiment configuration information in a `` +--------------------------------+-------------------+------------------------------------+ | ACCOUNT | "project_name" | "an_account" | +--------------------------------+-------------------+------------------------------------+ - | MODEL | "" | "FV3_GFS_v16_CONUS_25km" | + | MET_INSTALL_DIR | "" | "" | +--------------------------------+-------------------+------------------------------------+ | METPLUS_PATH | "" | "" | +--------------------------------+-------------------+------------------------------------+ - | MET_INSTALL_DIR | "" | "" | - +--------------------------------+-------------------+------------------------------------+ | CCPA_OBS_DIR | "" | "" | +--------------------------------+-------------------+------------------------------------+ | MRMS_OBS_DIR | "" | "" | +--------------------------------+-------------------+------------------------------------+ | NDAS_OBS_DIR | "" | "" | +--------------------------------+-------------------+------------------------------------+ + | USE_CRON_TO_RELAUNCH | false | false | + +--------------------------------+-------------------+------------------------------------+ | EXPT_SUBDIR | "" | "test_community" | +--------------------------------+-------------------+------------------------------------+ | CCPP_PHYS_SUITE | "FV3_GFS_v16" | "FV3_GFS_v16" | +--------------------------------+-------------------+------------------------------------+ + | PREDEF_GRID_NAME | "" | "RRFS_CONUS_25km" | + +--------------------------------+-------------------+------------------------------------+ | DATE_FIRST_CYCL | "YYYYMMDDHH" | '2019061518' | +--------------------------------+-------------------+------------------------------------+ | DATE_LAST_CYCL | "YYYYMMDDHH" | '2019061518' | @@ -301,42 +301,29 @@ The user must specify certain basic experiment configuration information in a `` +--------------------------------+-------------------+------------------------------------+ | EXTRN_MDL_NAME_LBCS | "FV3GFS" | "FV3GFS" | +--------------------------------+-------------------+------------------------------------+ - | FV3GFS_FILE_FMT_LBCS | "nemsio" | "grib2" | - +--------------------------------+-------------------+------------------------------------+ | LBC_SPEC_INTVL_HRS | 6 | 6 | +--------------------------------+-------------------+------------------------------------+ - | WTIME_RUN_FCST | "04:30:00" | "02:00:00" | + | FV3GFS_FILE_FMT_LBCS | "nemsio" | "grib2" | +--------------------------------+-------------------+------------------------------------+ | QUILTING | true | true | +--------------------------------+-------------------+------------------------------------+ - | PREDEF_GRID_NAME | "" | "RRFS_CONUS_25km" | + | COMOUT_REF | "" | "" | +--------------------------------+-------------------+------------------------------------+ | DO_ENSEMBLE | false | false | +--------------------------------+-------------------+------------------------------------+ | NUM_ENS_MEMBERS | 1 | 2 | +--------------------------------+-------------------+------------------------------------+ - -To get started, make a copy of ``config.community.yaml``. From the ``ufs-srweather-app`` directory, run: +To get started with a basic forecast in *community* mode, make a copy of ``config.community.yaml``. From the ``ufs-srweather-app`` directory, run: .. code-block:: console - cd /path/to/ufs-srweather-app/ush + cd ush cp config.community.yaml config.yaml 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. -.. note:: - - Users who have a previous configuration using the former shell-script-based can convert their ``config.sh`` file to a ``config.yaml`` file by running: - - .. code-block:: console - - ./config_utils.py -c $PWD/config.sh -t $PWD/config_defaults.yaml -o yaml >config.yaml - - Use caution when upgrading your experiment in this way, as many intervening changes in the workflow have occurred since the python changeover. - -Next, users should edit the new ``config.yaml`` file to customize it for their machine. At a minimum, users must change the ``MACHINE`` and ``ACCOUNT`` variables. Then, they can choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If users have pre-staged initialization data for the experiment, they can 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``. If the modulefile used to set up the build environment in :numref:`Section %s ` uses a GNU compiler, check that the line ``COMPILER: "gnu"`` appears in the ``workflow:`` section of the ``config.yaml`` file. On platforms where Rocoto and :term:`cron` are available, users can automate resubmission of their experiment workflow by adding the following lines to the ``workflow:`` section of the ``config.yaml`` file: +Next, users should edit the new ``config.yaml`` file to customize it for their machine. At a minimum, users will usually need to change the ``MACHINE`` and ``ACCOUNT`` variables. Then, select a name for the experiment directory by renaming ``EXPT_SUBDIR`` from ``test_community`` to a name describing the experiment (e.g., ``basic_wflow_test``). If users have pre-staged initialization data for the experiment, they can 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``. If the modulefile used to set up the build environment in :numref:`Section %s ` uses a GNU compiler, check that the line ``COMPILER: "gnu"`` appears in the ``workflow:`` section of the ``config.yaml`` file. On platforms where Rocoto and :term:`cron` are available, users can automate resubmission of their experiment workflow by adding the following lines to the ``workflow:`` section of the ``config.yaml`` file: .. code-block:: console @@ -347,7 +334,7 @@ Next, users should edit the new ``config.yaml`` file to customize it for their m Generic Linux and MacOS users should refer to :numref:`Section %s ` for additional details on configuring an experiment and python environment. -Detailed information on additional parameter options can be viewed in :numref:`Chapter %s: Configuring the Workflow `. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. +Detailed information on additional parameter options can be viewed in :numref:`Section %s: Configuring the Workflow `. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Section %s: Limited Area Model (LAM) Grids `. On Level 1 systems, the following fields typically need to be updated or added to the appropriate section of the ``config.yaml`` file in order to run the out-of-the-box SRW App case: @@ -374,7 +361,7 @@ where: 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. * ``EXPT_SUBDIR`` is changed to an experiment name of the user's choice. - * ```` is the path to the SRW App data on the user's machine (see :numref:`Section %s `). + * ``/path/to/`` is the path to the SRW App data on the user's machine (see :numref:`Section %s `). * ```` refers to a subdirectory containing the experiment data from a particular model. Valid values on Level 1 systems correspond to the valid values for ``EXTRN_MDL_NAME_ICS`` and ``EXTRN_MDL_NAME_LBCS`` (see :numref:`Chapter %s ` for options). * ```` refers to one of 3 possible data formats: ``grib2``, ``nemsio``, or ``netcdf``. * ```` refers to a subdirectory containing data for the :term:`cycle` date (in YYYYMMDDHH format). @@ -401,22 +388,23 @@ For example, to run the out-of-the-box experiment on Gaea, add or modify variabl EXTRN_MDL_SOURCE_BASEDIR_LBCS: /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/develop/input_model_data/FV3GFS/grib2/2019061518 EXTRN_MDL_DATA_STORES: disk -To determine whether the ``config.yaml`` file adjustments are valid, users can run the following script from the ``ush`` directory: +.. COMMENT: Delete? + To determine whether the ``config.yaml`` file adjustments are valid, users can run the following script from the ``ush`` directory: -.. code-block:: console + .. code-block:: console - ./config_utils.py -c $PWD/config.yaml -v $PWD/config_defaults.yaml + ./config_utils.py -c $PWD/config.yaml -v $PWD/config_defaults.yaml -A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yaml`` file with problems will output a ``FAILURE`` message describing the problem. For example: + A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yaml`` file with problems will output a ``FAILURE`` message describing the problem. For example: -.. code-block:: console + .. code-block:: console - INVALID ENTRY: EXTRN_MDL_FILES_ICS=[] - FAILURE + INVALID ENTRY: EXTRN_MDL_FILES_ICS=[] + FAILURE -.. note:: + .. note:: - The ``workflow_tools`` environment must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. + The ``workflow_tools`` environment must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. In addition, various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. @@ -983,18 +971,18 @@ The workflow run is complete when all tasks have "SUCCEEDED". If everything goes CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION ========================================================================================================== - 201906151800 make_grid 4953154 SUCCEEDED 0 1 5.0 - 201906151800 make_orog 4953176 SUCCEEDED 0 1 26.0 - 201906151800 make_sfc_climo 4953179 SUCCEEDED 0 1 33.0 - 201906151800 get_extrn_ics 4953155 SUCCEEDED 0 1 2.0 - 201906151800 get_extrn_lbcs 4953156 SUCCEEDED 0 1 2.0 - 201906151800 make_ics 4953184 SUCCEEDED 0 1 16.0 - 201906151800 make_lbcs 4953185 SUCCEEDED 0 1 71.0 - 201906151800 run_fcst 4953196 SUCCEEDED 0 1 1035.0 - 201906151800 run_post_f000 4953244 SUCCEEDED 0 1 5.0 - 201906151800 run_post_f001 4953245 SUCCEEDED 0 1 4.0 + 201906151800 make_grid 4953154 SUCCEEDED 0 1 5.0 + 201906151800 make_orog 4953176 SUCCEEDED 0 1 26.0 + 201906151800 make_sfc_climo 4953179 SUCCEEDED 0 1 33.0 + 201906151800 get_extrn_ics 4953155 SUCCEEDED 0 1 2.0 + 201906151800 get_extrn_lbcs 4953156 SUCCEEDED 0 1 2.0 + 201906151800 make_ics 4953184 SUCCEEDED 0 1 16.0 + 201906151800 make_lbcs 4953185 SUCCEEDED 0 1 71.0 + 201906151800 run_fcst 4953196 SUCCEEDED 0 1 1035.0 + 201906151800 run_post_mem000_f000 4953244 SUCCEEDED 0 1 5.0 + 201906151800 run_post_mem000_f001 4953245 SUCCEEDED 0 1 4.0 ... - 201906151800 run_post_f012 4953381 SUCCEEDED 0 1 7.0 + 201906151800 run_post_mem000_f012 4953381 SUCCEEDED 0 1 7.0 If users choose to run METplus verification tasks as part of their experiment, the output above will include additional lines after ``run_post_f012``. The output will resemble the following but may be significantly longer when using ensemble verification: @@ -1004,7 +992,7 @@ If users choose to run METplus verification tasks as part of their experiment, t ========================================================================================================== 201906151800 make_grid 30466134 SUCCEEDED 0 1 5.0 ... - 201906151800 run_post_f012 30468271 SUCCEEDED 0 1 7.0 + 201906151800 run_post_mem000_f012 30468271 SUCCEEDED 0 1 7.0 201906151800 run_gridstatvx 30468420 SUCCEEDED 0 1 53.0 201906151800 run_gridstatvx_refc 30468421 SUCCEEDED 0 1 934.0 201906151800 run_gridstatvx_retop 30468422 SUCCEEDED 0 1 1002.0 @@ -1040,23 +1028,23 @@ This will output the last 40 lines of the log file, which list the status of the .. code-block:: console - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION ====================================================================================================== - 201906151800 make_grid druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 make_orog - - - - - - 201906151800 make_sfc_climo - - - - - - 201906151800 get_extrn_ics druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 get_extrn_lbcs druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 make_ics - - - - - - 201906151800 make_lbcs - - - - - - 201906151800 run_fcst - - - - - - 201906151800 run_post_00 - - - - - - 201906151800 run_post_01 - - - - - - 201906151800 run_post_02 - - - - - - 201906151800 run_post_03 - - - - - - 201906151800 run_post_04 - - - - - - 201906151800 run_post_05 - - - - - - 201906151800 run_post_06 - - - - - + 201906151800 make_grid druby://hfe01:33728 SUBMITTING - 0 0.0 + 201906151800 make_orog - - - - - + 201906151800 make_sfc_climo - - - - - + 201906151800 get_extrn_ics druby://hfe01:33728 SUBMITTING - 0 0.0 + 201906151800 get_extrn_lbcs druby://hfe01:33728 SUBMITTING - 0 0.0 + 201906151800 make_ics - - - - - + 201906151800 make_lbcs - - - - - + 201906151800 run_fcst - - - - - + 201906151800 run_post_mem000_f000 - - - - - + 201906151800 run_post_mem000_f001 - - - - - + 201906151800 run_post_mem000_f002 - - - - - + 201906151800 run_post_mem000_f003 - - - - - + 201906151800 run_post_mem000_f004 - - - - - + 201906151800 run_post_mem000_f005 - - - - - + 201906151800 run_post_mem000_f006 - - - - - Summary of workflow status: ~~~~~~~~~~~~~~~~~~~~~~~~~~ From fdf7ed2092550ef43fcbd2be803d36bf53ecd40e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 12 Jul 2023 12:37:46 -0400 Subject: [PATCH 020/116] config section updates/reorg --- .../source/BuildingRunningTesting/RunSRW.rst | 220 +++++++++--------- 1 file changed, 113 insertions(+), 107 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index a707722646..f898a1f821 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -313,7 +313,12 @@ The user must set the specifics of their experiment configuration in a ``config. +--------------------------------+-------------------+------------------------------------+ | NUM_ENS_MEMBERS | 1 | 2 | +--------------------------------+-------------------+------------------------------------+ - + +.. _GeneralConfig: + +General Instructions for All Systems +``````````````````````````````````````` + To get started with a basic forecast in *community* mode, make a copy of ``config.community.yaml``. From the ``ufs-srweather-app`` directory, run: .. code-block:: console @@ -323,20 +328,7 @@ To get started with a basic forecast in *community* mode, make a copy of ``confi 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, users should edit the new ``config.yaml`` file to customize it for their machine. At a minimum, users will usually need to change the ``MACHINE`` and ``ACCOUNT`` variables. Then, select a name for the experiment directory by renaming ``EXPT_SUBDIR`` from ``test_community`` to a name describing the experiment (e.g., ``basic_wflow_test``). If users have pre-staged initialization data for the experiment, they can 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``. If the modulefile used to set up the build environment in :numref:`Section %s ` uses a GNU compiler, check that the line ``COMPILER: "gnu"`` appears in the ``workflow:`` section of the ``config.yaml`` file. On platforms where Rocoto and :term:`cron` are available, users can automate resubmission of their experiment workflow by adding the following lines to the ``workflow:`` section of the ``config.yaml`` file: - -.. code-block:: console - - USE_CRON_TO_RELAUNCH: true - CRON_RELAUNCH_INTVL_MNTS: 3 - -.. note:: - - Generic Linux and MacOS users should refer to :numref:`Section %s ` for additional details on configuring an experiment and python environment. - -Detailed information on additional parameter options can be viewed in :numref:`Section %s: Configuring the Workflow `. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Section %s: Limited Area Model (LAM) Grids `. - -On Level 1 systems, the following fields typically need to be updated or added to the appropriate section of the ``config.yaml`` file in order to run the out-of-the-box SRW App case: +Next, users should edit the new ``config.yaml`` file to customize it for their machine. On most systems, the following fields need to be updated or added to the appropriate section of the ``config.yaml`` file in order to run the out-of-the-box SRW App case: .. code-block:: console @@ -366,11 +358,20 @@ where: * ```` refers to one of 3 possible data formats: ``grib2``, ``nemsio``, or ``netcdf``. * ```` refers to a subdirectory containing data for the :term:`cycle` date (in YYYYMMDDHH format). +On platforms where Rocoto and :term:`cron` are available, users can automate resubmission of their experiment workflow by adding the following lines to the ``workflow:`` section of the ``config.yaml`` file: + +.. code-block:: console + + USE_CRON_TO_RELAUNCH: true + CRON_RELAUNCH_INTVL_MNTS: 3 + +When running with GNU compilers (i.e., if the modulefile used to set up the build environment in :numref:`Section %s ` uses a GNU compiler), users must also set ``COMPILER: "gnu"`` in the ``workflow:`` section of the ``config.yaml`` file. + .. note:: On ``JET``, users should also add ``PARTITION_DEFAULT: xjet`` and ``PARTITION_FCST: xjet`` to the ``platform:`` section of the ``config.yaml`` file. -For example, to run the out-of-the-box experiment on Gaea, add or modify variables in the ``user``, ``workflow``, ``task_get_extrn_ics``, and ``task_get_extrn_lbcs`` sections of ``config.yaml`` (unmodified variables are not shown in this example): +For example, to run the out-of-the-box experiment on Gaea using cron to automate job submission, users should add or modify variables in the ``user``, ``workflow``, ``task_get_extrn_ics``, and ``task_get_extrn_lbcs`` sections of ``config.yaml`` (unmodified variables are not shown in this example): .. code-block:: @@ -379,14 +380,16 @@ For example, to run the out-of-the-box experiment on Gaea, add or modify variabl ACCOUNT: hfv3gfs workflow: EXPT_SUBDIR: run_basic_srw + USE_CRON_TO_RELAUNCH: true + CRON_RELAUNCH_INTVL_MNTS: 3 task_get_extrn_ics: USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_ICS: /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/develop/input_model_data/FV3GFS/grib2/2019061518 - EXTRN_MDL_DATA_STORES: disk task_get_extrn_lbcs: USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_LBCS: /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/develop/input_model_data/FV3GFS/grib2/2019061518 - EXTRN_MDL_DATA_STORES: disk + +Detailed information on these and other parameter options can be viewed in :numref:`Section %s: Configuring the Workflow `. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Section %s: Limited Area Model (LAM) Grids `. .. COMMENT: Delete? To determine whether the ``config.yaml`` file adjustments are valid, users can run the following script from the ``ush`` directory: @@ -406,97 +409,26 @@ For example, to run the out-of-the-box experiment on Gaea, add or modify variabl The ``workflow_tools`` environment must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. -Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. In addition, various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. - -To configure an experiment and python environment for a general Linux or Mac system, see the :ref:`next section `. To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. Otherwise, skip to :numref:`Section %s ` to generate the workflow. - -.. _PlotOutput: - -Plotting Configuration (optional) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -An optional Python plotting task (PLOT_ALLVARS) can be activated in the workflow to generate plots for the :term:`FV3`-:term:`LAM` post-processed :term:`GRIB2` -output over the :term:`CONUS`. It generates graphics plots for a number of variables, including: - - * 2-m temperature - * 2-m dew point temperature - * 10-m winds - * 250 hPa winds - * Accumulated precipitation - * Composite reflectivity - * Surface-based :term:`CAPE`/:term:`CIN` - * Max/Min 2-5 km updraft helicity - * Sea level pressure (SLP) - -.. COMMENT: * 500 hPa heights, winds, and vorticity --> seems to be omitted? Why? - -This workflow task can produce both plots from a single experiment and difference plots that compare the same cycle from two experiments. When plotting the difference, the two experiments must be on the same domain and available for -the same cycle starting date/time and forecast hours. Other parameters may differ (e.g., the experiments may use different physics suites). - -.. _Cartopy: - -Cartopy Shapefiles -````````````````````` - -The Python plotting tasks require a path to the directory where the Cartopy Natural Earth shapefiles are located. The medium scale (1:50m) cultural and physical shapefiles are used to create coastlines and other geopolitical borders on the map. On `Level 1 `__ systems, this path is already set in the system's machine file using the variable ``FIXshp``. Users on other systems will need to download the shapefiles and update the path of ``$FIXshp`` in the machine file they are using (e.g., ``$SRW/ush/machine/macos.yaml`` for a generic MacOS system, where ``$SRW`` is the path to the ``ufs-srweather-app`` directory). The subset of shapefiles required for the plotting task can be obtained from the `SRW Data Bucket `__. The full set of medium-scale (1:50m) Cartopy shapefiles can be downloaded `here `__. - -Task Configuration -````````````````````` - -Users will need to add or modify certain variables in ``config.yaml`` to run the plotting task(s). At a minimum, to activate the ``plot_allvars`` tasks, users must add it to the default list of ``taskgroups`` under the ``rocoto: tasks:`` section. - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' - -Users may also wish to adjust the start, end, and increment value for the plotting task. For example: - -.. code-block:: console - - task_plot_allvars: - PLOT_FCST_START: 0 - PLOT_FCST_INC: 6 - PLOT_FCST_END: 12 - -If the user chooses not to set these values, the default values will be used (see :numref:`Section %s `). - -.. note:: - If a forecast starts at 18h, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. - -When plotting output from a single experiment, no further adjustments are necessary. The output files (in ``.png`` format) will be located in the experiment directory under the ``$CDATE/postprd`` subdirectory where ``$CDATE`` -corresponds to the cycle date and hour in YYYYMMDDHH format (e.g., ``2019061518``). - -Plotting the Difference Between Two Experiments -"""""""""""""""""""""""""""""""""""""""""""""""""" - -When plotting the difference between two experiments (``expt1`` and ``expt2``), users must set the ``COMOUT_REF`` template variable in ``expt2``'s ``config.yaml`` file to point at forecast output from the ``expt1`` directory. For example, in *community* mode, users can set ``COMOUT_REF`` as follows in the ``expt2`` configuration file: - -.. code-block:: console - - task_plot_allvars: - COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd' - -This will ensure that ``expt2`` can produce a difference plot comparing ``expt1`` and ``expt2``. In *community* mode, using default directory names and settings, ``$COMOUT_REF`` will resemble ``/path/to/expt_dirs/test_community/2019061518/postprd``. Additional details on the plotting variables are provided in :numref:`Section %s `. - -The output files (in ``.png`` format) will be located in the ``postprd`` directory for the experiment. +.. note:: -.. _LinuxMacEnvConfig: + Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. In addition, various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. -User-Specific Configuration on a Generic Linux/MacOS System -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**Next Steps:** -The configuration process for Linux and MacOS systems is similar to the process for other systems, but it requires a few extra steps. +* To configure an experiment for a general Linux or Mac system, see the :ref:`next section ` for additional required steps. +* To add the graphics plotting tasks to the experiment workflow, go to section :numref:`Section %s: Plotting Configuration `. +* To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. +* Otherwise, skip to :numref:`Section %s ` to generate the workflow. -.. note:: - Examples in this subsection presume that the user is running in the Terminal with a bash shell environment. If this is not the case, users will need to adjust the commands to fit their command line application and shell environment. .. _LinuxMacExptConfig: Configuring an Experiment on General Linux and MacOS Systems `````````````````````````````````````````````````````````````` +.. note:: + Examples in this subsection presume that the user is running in the Terminal with a bash shell environment. If this is not the case, users will need to adjust the commands to fit their command line application and shell environment. + **Optional: Install Rocoto** .. note:: @@ -505,14 +437,7 @@ Configuring an Experiment on General Linux and MacOS Systems **Configure the SRW App:** -Configure an experiment using a template. Copy the contents of ``config.community.yaml`` into ``config.yaml``: - -.. code-block:: console - - cd /path/to/ufs-srweather-app/ush - cp config.community.yaml config.yaml - -In the ``config.yaml`` file, set ``MACHINE: macos`` or ``MACHINE: linux``, and modify the account and experiment info. For example: +After following the steps in :numref:`Section %s: General Configuration ` above, users should have a ``config.yaml`` file that looks similar to this: .. code-block:: console @@ -537,6 +462,8 @@ In the ``config.yaml`` file, set ``MACHINE: macos`` or ``MACHINE: linux``, and m PREDEF_GRID_NAME: RRFS_CONUS_25km QUILTING: true +.. COMMENT: Edit above! + Due to the limited number of processors on MacOS systems, users must also configure the domain decomposition parameters directly in the section of the ``predef_grid_params.yaml`` file pertaining to the grid they want to use. Domain decomposition needs to take into account the number of available CPUs and configure the variables ``LAYOUT_X``, ``LAYOUT_Y``, and ``WRTCMP_write_tasks_per_group`` accordingly. The example below is for systems with 8 CPUs: @@ -610,6 +537,85 @@ The ``data:`` section of the machine file can point to various data sources that This can be helpful when conducting multiple experiments with different types of data. +**Next Steps:** + +* To add the graphics plotting tasks to the experiment workflow, go to section :numref:`Section %s: Plotting Configuration `. +* To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. +* Otherwise, skip to :numref:`Section %s ` to generate the workflow. + + +.. _PlotOutput: + +Plotting Configuration (optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An optional Python plotting task (PLOT_ALLVARS) can be activated in the workflow to generate plots for the :term:`FV3`-:term:`LAM` post-processed :term:`GRIB2` +output over the :term:`CONUS`. It generates graphics plots for a number of variables, including: + + * 2-m temperature + * 2-m dew point temperature + * 10-m winds + * 250 hPa winds + * Accumulated precipitation + * Composite reflectivity + * Surface-based :term:`CAPE`/:term:`CIN` + * Max/Min 2-5 km updraft helicity + * Sea level pressure (SLP) + +.. COMMENT: * 500 hPa heights, winds, and vorticity --> seems to be omitted? Why? + +This workflow task can produce both plots from a single experiment and difference plots that compare the same cycle from two experiments. When plotting the difference, the two experiments must be on the same domain and available for +the same cycle starting date/time and forecast hours. Other parameters may differ (e.g., the experiments may use different physics suites). + +.. _Cartopy: + +Cartopy Shapefiles +````````````````````` + +The Python plotting tasks require a path to the directory where the Cartopy Natural Earth shapefiles are located. The medium scale (1:50m) cultural and physical shapefiles are used to create coastlines and other geopolitical borders on the map. On `Level 1 `__ systems, this path is already set in the system's machine file using the variable ``FIXshp``. Users on other systems will need to download the shapefiles and update the path of ``$FIXshp`` in the machine file they are using (e.g., ``$SRW/ush/machine/macos.yaml`` for a generic MacOS system, where ``$SRW`` is the path to the ``ufs-srweather-app`` directory). The subset of shapefiles required for the plotting task can be obtained from the `SRW Data Bucket `__. The full set of medium-scale (1:50m) Cartopy shapefiles can be downloaded `here `__. + +Task Configuration +````````````````````` + +Users will need to add or modify certain variables in ``config.yaml`` to run the plotting task(s). At a minimum, to activate the ``plot_allvars`` tasks, users must add it to the default list of ``taskgroups`` under the ``rocoto: tasks:`` section. + +.. code-block:: console + + rocoto: + tasks: + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' + +Users may also wish to adjust the start, end, and increment value for the plotting task. For example: + +.. code-block:: console + + task_plot_allvars: + PLOT_FCST_START: 0 + PLOT_FCST_INC: 6 + PLOT_FCST_END: 12 + +If the user chooses not to set these values, the default values will be used (see :numref:`Section %s `). + +.. note:: + If a forecast starts at 18h, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. + +When plotting output from a single experiment, no further adjustments are necessary. The output files (in ``.png`` format) will be located in the experiment directory under the ``$CDATE/postprd`` subdirectory where ``$CDATE`` +corresponds to the cycle date and hour in YYYYMMDDHH format (e.g., ``2019061518``). + +Plotting the Difference Between Two Experiments +"""""""""""""""""""""""""""""""""""""""""""""""""" + +When plotting the difference between two experiments (``expt1`` and ``expt2``), users must set the ``COMOUT_REF`` template variable in ``expt2``'s ``config.yaml`` file to point at forecast output from the ``expt1`` directory. For example, in *community* mode, users can set ``COMOUT_REF`` as follows in the ``expt2`` configuration file: + +.. code-block:: console + + task_plot_allvars: + COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd' + +This will ensure that ``expt2`` can produce a difference plot comparing ``expt1`` and ``expt2``. In *community* mode, using default directory names and settings, ``$COMOUT_REF`` will resemble ``/path/to/expt_dirs/test_community/2019061518/postprd``. Additional details on the plotting variables are provided in :numref:`Section %s `. + +The output files (in ``.png`` format) will be located in the ``postprd`` directory for the experiment. + .. _VXConfig: Configure METplus Verification Suite (Optional) From ffc7f8623c24427c68931e328d8896d827b8354d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 12 Jul 2023 14:53:56 -0400 Subject: [PATCH 021/116] minor run updates --- .../source/BuildingRunningTesting/RunSRW.rst | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index f898a1f821..e7ebb938b3 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -346,15 +346,15 @@ Next, users should edit the new ``config.yaml`` file to customize it for their m where: * ``MACHINE`` refers to a valid machine name (see :numref:`Section %s ` for options). - * ``ACCOUNT`` refers to a valid account name. Not all systems require a valid account name, but most do. + * ``ACCOUNT`` refers to a valid account name. Not all systems require a valid account name, but most Level 1 & 2 systems do. .. hint:: 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. * ``EXPT_SUBDIR`` is changed to an experiment name of the user's choice. - * ``/path/to/`` is the path to the SRW App data on the user's machine (see :numref:`Section %s `). - * ```` refers to a subdirectory containing the experiment data from a particular model. Valid values on Level 1 systems correspond to the valid values for ``EXTRN_MDL_NAME_ICS`` and ``EXTRN_MDL_NAME_LBCS`` (see :numref:`Chapter %s ` for options). + * ``/path/to/`` is the path to the SRW App data on the user's machine (see :numref:`Section %s ` for data locations on Level 1 systems). + * ```` refers to a subdirectory containing the experiment data from a particular model. Valid values on Level 1 systems correspond to the valid values for ``EXTRN_MDL_NAME_ICS`` and ``EXTRN_MDL_NAME_LBCS`` (see :numref:`Section %s ` or :numref:`%s ` for options). * ```` refers to one of 3 possible data formats: ``grib2``, ``nemsio``, or ``netcdf``. * ```` refers to a subdirectory containing data for the :term:`cycle` date (in YYYYMMDDHH format). @@ -369,9 +369,9 @@ When running with GNU compilers (i.e., if the modulefile used to set up the buil .. note:: - On ``JET``, users should also add ``PARTITION_DEFAULT: xjet`` and ``PARTITION_FCST: xjet`` to the ``platform:`` section of the ``config.yaml`` file. + On ``JET``, users should add ``PARTITION_DEFAULT: xjet`` and ``PARTITION_FCST: xjet`` to the ``platform:`` section of the ``config.yaml`` file. -For example, to run the out-of-the-box experiment on Gaea using cron to automate job submission, users should add or modify variables in the ``user``, ``workflow``, ``task_get_extrn_ics``, and ``task_get_extrn_lbcs`` sections of ``config.yaml`` (unmodified variables are not shown in this example): +For example, to run the out-of-the-box experiment on Gaea using cron to automate job submission, users can add or modify variables in the ``user``, ``workflow``, ``task_get_extrn_ics``, and ``task_get_extrn_lbcs`` sections of ``config.yaml`` according to the following example (unmodified variables are not shown here): .. code-block:: @@ -389,37 +389,35 @@ For example, to run the out-of-the-box experiment on Gaea using cron to automate USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_LBCS: /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/develop/input_model_data/FV3GFS/grib2/2019061518 -Detailed information on these and other parameter options can be viewed in :numref:`Section %s: Configuring the Workflow `. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Section %s: Limited Area Model (LAM) Grids `. +To determine whether the ``config.yaml`` file adjustments are valid, users can run the following script from the ``ush`` directory: -.. COMMENT: Delete? - To determine whether the ``config.yaml`` file adjustments are valid, users can run the following script from the ``ush`` directory: - - .. code-block:: console +.. code-block:: console - ./config_utils.py -c $PWD/config.yaml -v $PWD/config_defaults.yaml + ./config_utils.py -c $PWD/config.yaml -v $PWD/config_defaults.yaml -k "(?\!rocoto\b)" - A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yaml`` file with problems will output a ``FAILURE`` message describing the problem. For example: +A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yaml`` file with problems will output a ``FAILURE`` message describing the problem. For example: - .. code-block:: console +.. code-block:: console - INVALID ENTRY: EXTRN_MDL_FILES_ICS=[] - FAILURE + INVALID ENTRY: EXTRN_MDL_FILES_ICS=[] + FAILURE - .. note:: +.. hint:: - The ``workflow_tools`` environment must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. + * The ``workflow_tools`` environment must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. -.. note:: + * Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. In addition, various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. - Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. In addition, various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. +Users can find detailed information on configuration parameter options in :numref:`Section %s: Configuring the Workflow `. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Section %s: Limited Area Model (LAM) Grids `. -**Next Steps:** +.. attention:: -* To configure an experiment for a general Linux or Mac system, see the :ref:`next section ` for additional required steps. -* To add the graphics plotting tasks to the experiment workflow, go to section :numref:`Section %s: Plotting Configuration `. -* To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. -* Otherwise, skip to :numref:`Section %s ` to generate the workflow. + **Next Steps:** + * To configure an experiment for a general Linux or Mac system, see the :ref:`next section ` for additional required steps. + * To add the graphics plotting tasks to the experiment workflow, go to section :numref:`Section %s: Plotting Configuration `. + * To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. + * Otherwise, skip to :numref:`Section %s ` to generate the workflow. .. _LinuxMacExptConfig: @@ -537,11 +535,13 @@ The ``data:`` section of the machine file can point to various data sources that This can be helpful when conducting multiple experiments with different types of data. -**Next Steps:** +.. attention:: + + **Next Steps:** -* To add the graphics plotting tasks to the experiment workflow, go to section :numref:`Section %s: Plotting Configuration `. -* To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. -* Otherwise, skip to :numref:`Section %s ` to generate the workflow. + * To add the graphics plotting tasks to the experiment workflow, go to section :numref:`Section %s: Plotting Configuration `. + * To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. + * Otherwise, skip to :numref:`Section %s ` to generate the workflow. .. _PlotOutput: From 0729d1b05beea127e9640d47b32b6b531b9054e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 12 Jul 2023 17:02:52 -0400 Subject: [PATCH 022/116] plotting & VX updates --- .../source/BuildingRunningTesting/RunSRW.rst | 103 ++++++++++-------- 1 file changed, 58 insertions(+), 45 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index e7ebb938b3..5e09186254 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -406,13 +406,13 @@ A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yam * The ``workflow_tools`` environment must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. - * Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. In addition, various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. - -Users can find detailed information on configuration parameter options in :numref:`Section %s: Configuring the Workflow `. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Section %s: Limited Area Model (LAM) Grids `. + * Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. + + * Various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. -.. attention:: + * Users can find detailed information on configuration parameter options in :numref:`Section %s: Configuring the Workflow `. - **Next Steps:** +**Next Steps:** * To configure an experiment for a general Linux or Mac system, see the :ref:`next section ` for additional required steps. * To add the graphics plotting tasks to the experiment workflow, go to section :numref:`Section %s: Plotting Configuration `. @@ -435,32 +435,22 @@ Configuring an Experiment on General Linux and MacOS Systems **Configure the SRW App:** -After following the steps in :numref:`Section %s: General Configuration ` above, users should have a ``config.yaml`` file that looks similar to this: +After following the steps in :numref:`Section %s: General Configuration ` above, users should have a ``config.yaml`` file with the setting from ``community.config.yaml`` and updates similar to this: .. code-block:: console user: - RUN_ENVIR: community MACHINE: macos ACCOUNT: user workflow: - EXPT_SUBDIR: test_community - PREEXISTING_DIR_METHOD: rename - VERBOSE: true + EXPT_SUBDIR: my_test_expt COMPILER: gnu task_get_extrn_ics: USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/input_model_data/FV3GFS/grib2/2019061518 - EXTRN_MDL_DATA_STORES: disk task_get_extrn_lbcs: USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/input_model_data/FV3GFS/grib2/2019061518 - EXTRN_MDL_DATA_STORES: disk - task_run_fcst: - PREDEF_GRID_NAME: RRFS_CONUS_25km - QUILTING: true - -.. COMMENT: Edit above! Due to the limited number of processors on MacOS systems, users must also configure the domain decomposition parameters directly in the section of the ``predef_grid_params.yaml`` file pertaining to the grid they want to use. Domain decomposition needs to take into account the number of available CPUs and configure the variables ``LAYOUT_X``, ``LAYOUT_Y``, and ``WRTCMP_write_tasks_per_group`` accordingly. @@ -535,15 +525,12 @@ The ``data:`` section of the machine file can point to various data sources that This can be helpful when conducting multiple experiments with different types of data. -.. attention:: - - **Next Steps:** +**Next Steps:** - * To add the graphics plotting tasks to the experiment workflow, go to section :numref:`Section %s: Plotting Configuration `. + * To add the graphics plotting tasks to the experiment workflow, go to the next section :ref:`Plotting Configuration `. * To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. * Otherwise, skip to :numref:`Section %s ` to generate the workflow. - .. _PlotOutput: Plotting Configuration (optional) @@ -577,7 +564,7 @@ The Python plotting tasks require a path to the directory where the Cartopy Natu Task Configuration ````````````````````` -Users will need to add or modify certain variables in ``config.yaml`` to run the plotting task(s). At a minimum, to activate the ``plot_allvars`` tasks, users must add it to the default list of ``taskgroups`` under the ``rocoto: tasks:`` section. +Users will need to add or modify certain variables in ``config.yaml`` to run the plotting task(s). At a minimum, to activate the ``plot_allvars`` tasks, users must add the task yaml file to the default list of ``taskgroups`` under the ``rocoto: tasks:`` section. .. code-block:: console @@ -585,7 +572,7 @@ Users will need to add or modify certain variables in ``config.yaml`` to run the tasks: taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' -Users may also wish to adjust the start, end, and increment value for the plotting task. For example: +Users may also wish to adjust the start, end, and increment value for the plotting task in the ``config.yaml`` file. For example: .. code-block:: console @@ -594,7 +581,7 @@ Users may also wish to adjust the start, end, and increment value for the plotti PLOT_FCST_INC: 6 PLOT_FCST_END: 12 -If the user chooses not to set these values, the default values will be used (see :numref:`Section %s `). +If the user chooses not to set these values, the default values will be used (see :numref:`Section %s ` for defaults). .. note:: If a forecast starts at 18h, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. @@ -642,23 +629,38 @@ To use METplus verification, the path to the MET and METplus directories must be METPLUS_PATH: MET_INSTALL_DIR: -To turn on verification tasks in the workflow, include the ``parm/wflow/verify.yaml`` file in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml``. +To turn on verification tasks in the workflow, include the desired ``parm/wflow/verify_*.yaml`` file(s) in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml``. .. code-block:: console rocoto: tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify_pre.yaml", "parm/wflow/verify_det.yaml"]|include }}' + +The ``verify_*.yaml`` files include the definitions of several common verification tasks by default. :numref:`Table %s ` indicates which functions each ``verify_*.yaml`` file configures. The tasks in each file are independent of each other, so users may want to turn some off 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 `. + +.. _VX-yamls: -The ``verify.yaml`` file includes the definitions of several common verification tasks by default. They are independent of each other, so users may want to turn some off 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 `. +.. list-table:: Verification YAML Task Groupings + :widths: 20 50 + :header-rows: 1 -To turn off a task, simply include its entry from ``verify.yaml`` as an empty YAML entry. For example, to turn off PointStat tasks: + * - File + - Description + * - verify_pre.yaml + - Contains (meta)tasks that are prerequisites for both deterministic and ensemble verification (vx) + * - verify_det.yaml + - Perform deterministic vx + * - verify_ens.yaml + - Perform ensemble vx + +To turn off a task, simply include its entry from ``verify_*.yaml`` as an empty YAML entry in ``config.yaml``. For example, to turn off PointStat tasks: .. code-block:: console rocoto: tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify_det.yaml"]|include }}' metatask_vx_ens_member: metatask_PointStat_mem#mem#: @@ -982,9 +984,9 @@ The workflow run is complete when all tasks have "SUCCEEDED". If everything goes 201906151800 make_sfc_climo 4953179 SUCCEEDED 0 1 33.0 201906151800 get_extrn_ics 4953155 SUCCEEDED 0 1 2.0 201906151800 get_extrn_lbcs 4953156 SUCCEEDED 0 1 2.0 - 201906151800 make_ics 4953184 SUCCEEDED 0 1 16.0 - 201906151800 make_lbcs 4953185 SUCCEEDED 0 1 71.0 - 201906151800 run_fcst 4953196 SUCCEEDED 0 1 1035.0 + 201906151800 make_ics_mem000 4953184 SUCCEEDED 0 1 16.0 + 201906151800 make_lbcs_mem000 4953185 SUCCEEDED 0 1 71.0 + 201906151800 run_fcst_mem000 4953196 SUCCEEDED 0 1 1035.0 201906151800 run_post_mem000_f000 4953244 SUCCEEDED 0 1 5.0 201906151800 run_post_mem000_f001 4953245 SUCCEEDED 0 1 4.0 ... @@ -994,19 +996,30 @@ If users choose to run METplus verification tasks as part of their experiment, t .. code-block:: console - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ========================================================================================================== - 201906151800 make_grid 30466134 SUCCEEDED 0 1 5.0 + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + ================================================================================================================ + 201906151800 make_grid 30466134 SUCCEEDED 0 1 5.0 ... - 201906151800 run_post_mem000_f012 30468271 SUCCEEDED 0 1 7.0 - 201906151800 run_gridstatvx 30468420 SUCCEEDED 0 1 53.0 - 201906151800 run_gridstatvx_refc 30468421 SUCCEEDED 0 1 934.0 - 201906151800 run_gridstatvx_retop 30468422 SUCCEEDED 0 1 1002.0 - 201906151800 run_gridstatvx_03h 30468491 SUCCEEDED 0 1 43.0 - 201906151800 run_gridstatvx_06h 30468492 SUCCEEDED 0 1 29.0 - 201906151800 run_gridstatvx_24h 30468493 SUCCEEDED 0 1 20.0 - 201906151800 run_pointstatvx 30468423 SUCCEEDED 0 1 670.0 - + 201906151800 run_post_mem000_f012 30468271 SUCCEEDED 0 1 7.0 + 201906151800 get_obs_ccpa 46903539 SUCCEEDED 0 1 9.0 + 201906151800 get_obs_mrms 46903540 SUCCEEDED 0 1 12.0 + 201906151800 get_obs_ndas 46903541 SUCCEEDED 0 1 9.0 + ... + 201906151800 run_gridstatvx 30468420 SUCCEEDED 0 1 53.0 + 201906151800 run_gridstatvx_refc 30468421 SUCCEEDED 0 1 934.0 + 201906151800 run_gridstatvx_retop 30468422 SUCCEEDED 0 1 1002.0 + 201906151800 run_gridstatvx_03h 30468491 SUCCEEDED 0 1 43.0 + 201906151800 run_gridstatvx_06h 30468492 SUCCEEDED 0 1 29.0 + 201906151800 run_gridstatvx_24h 30468493 SUCCEEDED 0 1 20.0 + 201906151800 run_pointstatvx 30468423 SUCCEEDED 0 1 670.0 + ... + 201906151800 run_MET_GridStat_vx_APCP01h_mem000 - - - - - + 201906151800 run_MET_GridStat_vx_APCP03h_mem000 - - - - - + 201906151800 run_MET_GridStat_vx_APCP06h_mem000 - - - - - + 201906151800 run_MET_GridStat_vx_REFC_mem000 - - - - - + 201906151800 run_MET_GridStat_vx_RETOP_mem000 - - - - - + 201906151800 run_MET_PointStat_vx_SFC_mem000 - - - - - + 201906151800 run_MET_PointStat_vx_UPA_mem000 - - - - - Launch the Rocoto Workflow Using a Script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 9237772e07dacf7c14ef67ebaba93adde0cbacfc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 13 Jul 2023 09:54:55 -0400 Subject: [PATCH 023/116] minor updates --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 5e09186254..d7a2306460 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -637,7 +637,7 @@ To turn on verification tasks in the workflow, include the desired ``parm/wflow/ tasks: taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify_pre.yaml", "parm/wflow/verify_det.yaml"]|include }}' -The ``verify_*.yaml`` files include the definitions of several common verification tasks by default. :numref:`Table %s ` indicates which functions each ``verify_*.yaml`` file configures. The tasks in each file are independent of each other, so users may want to turn some off 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 `. +The ``verify_*.yaml`` files include the definitions of several common verification tasks by default. :numref:`Table %s ` indicates which functions each ``verify_*.yaml`` file configures. The tasks in each file are independent of each other, so users may want to turn some off depending on the needs of their experiment. Note that the ENSGRID and ENSPOINT tasks apply only to ensemble model verification. Individual verification tasks appear in :numref:`Table %s `. .. _VX-yamls: @@ -686,8 +686,6 @@ Users who have already staged the observation data needed for METplus (i.e., the task_get_obs_mrms: task_get_obs_ndas: - - .. _GenerateWorkflow: Generate the SRW App Workflow From 1860238b5b7d07e5495502e8568c5562e7d768a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 13 Jul 2023 13:33:41 -0400 Subject: [PATCH 024/116] add info about NCO-compliant structure --- .../source/BackgroundInfo/TechnicalOverview.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index 3d24f1f357..fb9a42dfd6 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -143,7 +143,7 @@ The UFS Weather Model contains a number of sub-repositories, which are documente Directory Structure ---------------------- -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 (see :numref:`Section %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` is an NCO-compliant repository. Its structure follows the standards laid out in :term:`NCEP` Central Operations (NCO) WCOSS `Implementation Standards `__. This structure is implemented using the ``local_path`` settings contained within the ``Externals.cfg`` file. After ``manage_externals/checkout_externals`` is run (see :numref:`Section %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 @@ -193,7 +193,7 @@ The ``ufs-srweather-app`` :term:`umbrella repository` structure is determined by SRW App SubDirectories ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:numref:`Table %s ` describes the contents of the most important SRW App subdirectories. :numref:`Table %s ` provides a more comprehensive explanation of the ``ufs-srweather-app`` files and subdirectories. +:numref:`Table %s ` describes the contents of the most important SRW App subdirectories. :numref:`Table %s ` provides a more comprehensive explanation of the ``ufs-srweather-app`` files and subdirectories. Users can reference the `NCO Implementation Standards `__ (p. 19) for additional details on repository structure in NCO-compliant repositories. .. _Subdirectories: @@ -202,13 +202,20 @@ SRW App SubDirectories +-------------------------+----------------------------------------------------+ | **Directory Name** | **Description** | +=========================+====================================================+ + | docs | Repository documentation | + +-------------------------+----------------------------------------------------+ | jobs | J-job scripts launched by Rocoto | +-------------------------+----------------------------------------------------+ | modulefiles | Files used to load modules needed for building and | | | running the workflow | +-------------------------+----------------------------------------------------+ + | parm | Parameter files used to configure the model, | + | | physics, workflow, and various SRW App components | + +-------------------------+----------------------------------------------------+ | scripts | Scripts launched by the J-jobs | +-------------------------+----------------------------------------------------+ + | sorc | External source code used to build the SRW App | + +-------------------------+----------------------------------------------------+ | tests | Tests for baseline experiment configurations | +-------------------------+----------------------------------------------------+ | ush | Utility scripts used by the workflow | From b88cf5942f083aadd9cf92d8baad99fdb51ca89f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 13 Jul 2023 18:12:36 -0400 Subject: [PATCH 025/116] update wflow & VX task tables --- .../source/BuildingRunningTesting/RunSRW.rst | 240 ++++++++---------- 1 file changed, 103 insertions(+), 137 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index d7a2306460..cd4cdf9a37 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -435,7 +435,7 @@ Configuring an Experiment on General Linux and MacOS Systems **Configure the SRW App:** -After following the steps in :numref:`Section %s: General Configuration ` above, users should have a ``config.yaml`` file with the setting from ``community.config.yaml`` and updates similar to this: +After following the steps in :numref:`Section %s: General Configuration ` above, users should have a ``config.yaml`` file with settings from ``community.config.yaml`` and updates similar to this: .. code-block:: console @@ -603,18 +603,24 @@ This will ensure that ``expt2`` can produce a difference plot comparing ``expt1` The output files (in ``.png`` format) will be located in the ``postprd`` directory for the experiment. +**Next Steps:** + + * To configure an experiment to run METplus verification tasks, see the :ref:`next section `. + * Otherwise, skip to :numref:`Section %s ` to generate the workflow. + + .. _VXConfig: Configure METplus Verification Suite (Optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Users who want to use the METplus verification suite to evaluate their forecasts need to add additional information to their ``config.yaml`` file. Other users may skip to the :ref:`next section `. +Users who want to use the METplus verification suite to evaluate their forecasts need to add additional information to their ``config.yaml`` file. Other users may skip to the next step (:numref:`Section %s: Generate the SRW App Workflow `). .. attention:: - METplus *installation* is not included as part of the build process for this release of the SRW App. However, METplus is preinstalled on many `Level 1 & 2 `__ systems. For the v2.1.0 release, METplus *use* is supported on systems with a functioning METplus installation, although installation itself is not supported. For more information about METplus, see :numref:`Section %s `. + METplus *installation* is not included as part of the build process for the SRW App. However, METplus is preinstalled on many `Level 1 & 2 `__ systems. METplus *use* is supported on systems with a functioning METplus installation, but installation itself is not supported. For more information about METplus, see :numref:`Section %s `. .. note:: - If METplus users update their METplus installation, they must update the module load statements in ``ufs-srweather-app/modulefiles/tasks//run_vx.local`` file to correspond to their system's updated installation: + If METplus users update their METplus installation, they must update the module load statements in ``ufs-srweather-app/modulefiles/tasks//run_vx.local`` to correspond to their system's updated installation: .. code-block:: console @@ -629,7 +635,9 @@ To use METplus verification, the path to the MET and METplus directories must be METPLUS_PATH: MET_INSTALL_DIR: -To turn on verification tasks in the workflow, include the desired ``parm/wflow/verify_*.yaml`` file(s) in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml``. +On Level 1 systems, users can find this path in the machine file for their system. On other systems, users will need to determine where MET and METplus were installed. + +To turn on verification (VX) tasks in the workflow, include the desired ``parm/wflow/verify_*.yaml`` file(s) in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml``. For example: .. code-block:: console @@ -637,7 +645,7 @@ To turn on verification tasks in the workflow, include the desired ``parm/wflow/ tasks: taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify_pre.yaml", "parm/wflow/verify_det.yaml"]|include }}' -The ``verify_*.yaml`` files include the definitions of several common verification tasks by default. :numref:`Table %s ` indicates which functions each ``verify_*.yaml`` file configures. The tasks in each file are independent of each other, so users may want to turn some off depending on the needs of their experiment. Note that the ENSGRID and ENSPOINT tasks apply only to ensemble model verification. Individual verification tasks appear in :numref:`Table %s `. +:numref:`Table %s ` indicates which functions each ``verify_*.yaml`` file configures. Users must add ``verify_pre.yaml`` anytime they want to do VX; it runs preprocessing tasks that are necessary for both deterministic and ensemble VX. Then users can add ``verify_det.yaml`` for deterministic VX or ``verify_ens.yaml`` for ensemble VX (or both). Note that ensemble VX requires the user to be running an ensemble forecast or to stage ensemble forecast files in an appropriate location. .. _VX-yamls: @@ -654,24 +662,28 @@ The ``verify_*.yaml`` files include the definitions of several common verificati * - verify_ens.yaml - Perform ensemble vx +The ``verify_*.yaml`` files include the definitions of several common verification tasks by default. The tasks in each file are independent of each other, so users may want to turn some off depending on the needs of their experiment. Note that the ENSGRID and ENSPOINT tasks apply only to ensemble model verification. Individual verification tasks appear in :numref:`Table %s `. + +.. COMMENT: Check task names (still ENSGRID and ENSPOINT?) + To turn off a task, simply include its entry from ``verify_*.yaml`` as an empty YAML entry in ``config.yaml``. For example, to turn off PointStat tasks: .. code-block:: console rocoto: tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify_det.yaml"]|include }}' + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify_pre.yaml", "parm/wflow/verify_det.yaml"]|include }}' metatask_vx_ens_member: metatask_PointStat_mem#mem#: More information about configuring the ``rocoto:`` section can be found in :numref:`Section %s `. -If users have access to NOAA :term:`HPSS` but have not pre-staged the data, the default ``verify.yaml`` taskgroup will activate the tasks, and the workflow will attempt to download the appropriate data from NOAA HPSS. In this case, the ``*_OBS_DIR`` paths must be set to the location where users want the downloaded data to reside. +If users have access to NOAA :term:`HPSS` but have not pre-staged the data, the default ``verify_pre.yaml`` taskgroup will activate the tasks, and the workflow will attempt to download the appropriate data from NOAA HPSS. In this case, 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 `__. -Users who have already staged the observation data needed for METplus (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data and turn off the corresponding task by including them with no entry in ``config.yaml``. +Users who have already staged the observation data needed for METplus (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data in ``config.yaml`` and turn off the corresponding task by including them with no entry in the ``rocoto:`` section of ``config.yaml``. .. code-block:: console @@ -681,7 +693,7 @@ Users who have already staged the observation data needed for METplus (i.e., the NDAS_OBS_DIR: /path/to/UFS_SRW_App/develop/obs_data/ndas/proc rocoto: tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify_pre.yaml", "parm/wflow/verify_det.yaml"]|include }}' task_get_obs_ccpa: task_get_obs_mrms: task_get_obs_ndas: @@ -697,11 +709,19 @@ Run the following command from the ``ufs-srweather-app/ush`` directory to genera ./generate_FV3LAM_wflow.py -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 if users have the Rocoto workflow manager installed on their system. +The last line of output from this script, starting with ``*/1 * * * *`` or ``*/3 * * * *``, can be saved and used later to automatically run portions of the workflow if users have the Rocoto workflow manager installed on their system. + +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. The ``generate_FV3LAM_wflow.py``: -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.py`` runs the ``setup.py`` script to set the configuration parameters. Second, it symlinks the time-independent (fix) files and other necessary data input files from their location to the experiment directory (``$EXPTDIR``). Third, it creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` file in the ``parm`` directory. Lastly, it creates the workflow XML file ``FV3LAM_wflow.xml`` that is executed when running the experiment with the Rocoto workflow manager. + #. Runs the ``setup.py`` script to set the configuration parameters. This script reads three other configuration scripts in order: + + a. ``config_defaults.yaml`` (:numref:`Section %s `) + b. ``config.yaml`` (:numref:`Section %s `), and + c. ``set_predef_grid_params.py``. -The ``setup.py`` script reads three other configuration scripts in order: (1) ``config_defaults.yaml`` (:numref:`Section %s `), (2) ``config.yaml`` (:numref:`Section %s `), and (3) ``set_predef_grid_params.py``. If a parameter is specified differently in these scripts, the file containing the last defined value will be used. + #. Symlinks the time-independent (fix) files and other necessary data input files from their location to the experiment directory (``$EXPTDIR``). + #. Creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` file in the ``parm`` directory. + #. Creates the workflow XML file ``FV3LAM_wflow.xml`` that is executed when running the experiment with the Rocoto workflow manager. The generated workflow will appear in ``$EXPTDIR``, where ``EXPTDIR=${EXPT_BASEDIR}/${EXPT_SUBDIR}``. These variables were specified in ``config_defaults.yaml`` and ``config.yaml`` in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.py`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in ``$EXPTDIR``. @@ -720,7 +740,7 @@ Description of Workflow Tasks .. note:: 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 baseline 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 removing the ``prep.yaml`` file from the default ``taskgroups`` entry in the ``config.yaml`` file before running the ``generate_FV3LAM_wflow.py`` script: +:numref:`Figure %s ` illustrates the overall workflow. Individual tasks that make up the workflow are detailed in the ``FV3LAM_wflow.xml`` file. :numref:`Table %s ` describes the function of each baseline 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 removing the ``prep.yaml`` file from the default ``taskgroups`` entry in the ``config.yaml`` file before running the ``generate_FV3LAM_wflow.py`` script: .. code-block:: console @@ -761,138 +781,84 @@ The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``jobs/JREGIONAL_ | get_extrn_lbcs | Cycle-specific task to obtain external data for the | | | lateral boundary conditions (LBCs) | +----------------------+------------------------------------------------------------+ - | make_ics | Generate initial conditions from the external data | + | make_ics* | Generate ICs from the external data | +----------------------+------------------------------------------------------------+ - | make_lbcs | Generate LBCs from the external data | + | make_lbcs* | Generate LBCs from the external data | +----------------------+------------------------------------------------------------+ - | run_fcst | Run the forecast model (UFS Weather Model) | + | run_fcst* | Run the forecast model (UFS Weather Model) | +----------------------+------------------------------------------------------------+ - | run_post | Run the post-processing tool (UPP) | + | run_post* | Run the post-processing tool (UPP) | +----------------------+------------------------------------------------------------+ -In addition to the baseline tasks described in :numref:`Table %s ` above, users may choose to run some or all of the METplus verification tasks. These tasks are described in :numref:`Table %s ` below. +In addition to the baseline tasks described in :numref:`Table %s ` above, users may choose to run a variety of optional tasks, including plotting and verification tasks. + +.. _PlottingTaskTable: + +.. table:: Plotting Task in the SRW App + + +----------------------+------------------------------------------------------------+ + | **Workflow Task** | **Task Description** | + +======================+============================================================+ + | plot_allvars | Run the plotting task and, optionally, the difference | + | | plotting task | + +----------------------+------------------------------------------------------------+ + +METplus verification tasks are described in :numref:`Table %s ` below. For each task, ``mem###`` refers to either ``mem000`` (if running a deterministic forecast) or a specific forecast member number (if running an ensemble forecast). .. _VXWorkflowTasksTable: -.. table:: Verification (VX) Workflow Tasks in the SRW App - - +-----------------------+------------------------------------------------------------+ - | **Workflow Task** | **Task Description** | - +=======================+============================================================+ - | GET_OBS_CCPA | Retrieves and organizes hourly :term:`CCPA` data from NOAA | - | | HPSS. Can only be run if ``verify.yaml`` is included in a | - | | ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | GET_OBS_NDAS | Retrieves and organizes hourly :term:`NDAS` data from NOAA | - | | HPSS. Can only be run if ``verify.yaml`` is included in a | - | | ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | GET_OBS_MRMS | Retrieves and organizes hourly :term:`MRMS` composite | - | | reflectivity and :term:`echo top` data from NOAA HPSS. Can | - | | only be run if ``verify.yaml`` is included in a | - | | ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT | Runs METplus grid-to-grid verification for 1-h accumulated | - | | precipitation | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_REFC | Runs METplus grid-to-grid verification for composite | - | | reflectivity | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_RETOP | Runs METplus grid-to-grid verification for :term:`echo top`| - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_##h | Runs METplus grid-to-grid verification for 3-h, 6-h, and | - | | 24-h (i.e., daily) accumulated precipitation. Valid values | - | | for ``##`` are ``03``, ``06``, and ``24``. | - +-----------------------+------------------------------------------------------------+ - | VX_POINTSTAT | Runs METplus grid-to-point verification for surface and | - | | upper-air variables | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID | Runs METplus grid-to-grid ensemble verification for 1-h | - | | accumulated precipitation. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_REFC | Runs METplus grid-to-grid ensemble verification for | - | | composite reflectivity. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_RETOP | Runs METplus grid-to-grid ensemble verification for | - | | :term:`echo top`. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_##h | Runs METplus grid-to-grid ensemble verification for 3-h, | - | | 6-h, and 24-h (i.e., daily) accumulated precipitation. | - | | Valid values for ``##`` are ``03``, ``06``, and ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | 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 | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | 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 | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_MEAN_##h | Runs METplus grid-to-grid verification for ensemble mean | - | | 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation. | - | | Valid values for ``##`` are ``03``, ``06``, and ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_##h | Runs METplus grid-to-grid verification for 3-h, 6-h, and | - | | 24h (i.e., daily) accumulated precipitation probabilistic | - | | output. Valid values for ``##`` are ``03``, ``06``, and | - | | ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_REFC | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for composite reflectivity. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_RETOP | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for :term:`echo top`. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT | Runs METplus grid-to-point ensemble verification for | - | | surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT_MEAN | Runs METplus grid-to-point verification for ensemble mean | - | | surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT_PROB | Runs METplus grid-to-point verification for ensemble | - | | probabilities for surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ +.. list-table:: Verification (VX) Workflow Tasks in the SRW App + :widths: 20 50 + :header-rows: 1 + * - Workflow Task + - Task Description + * - task_get_obs_ccpa + - Retrieves and organizes hourly :term:`CCPA` data from NOAA HPSS. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list *and* user has access to NOAA :term:`HPSS` data. + * - task_get_obs_ndas + - Retrieves and organizes hourly :term:`NDAS` data from NOAA HPSS. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list *and* user has access to NOAA :term:`HPSS` data. + * - task_get_obs_mrms + - Retrieves and organizes hourly :term:`MRMS` composite reflectivity and :term:`echo top` data from NOAA HPSS. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list *and* user has access to NOAA :term:`HPSS` data. + * - task_run_MET_Pb2nc_obs + - Convert files from prepbufr to NetCDF format. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list. + * - metatask_PcpCombine_obs + - Derive 3-hr, 6-hr, and 24-hr accumulated precipitation observations from the 1-hr observation files. In log files, task will be named like ``MET_PcpCombine_obs_APCP##h`` where ##h is 03h, 06h, or 24h. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list. + * - metatask_check_post_output_all_mems + - Ensure that required post-processing tasks have completed and that the output exists in the correct form and location for each forecast member. In log files, task will be named like ``check_post_output_mem###``. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list. + * - metatask_PcpCombine_fcst_all_accums_all_mems + - Derive accumulated precipitation forecast for 3-hr, 6-hr, and 24-hr windows for all forecast members based on 1-hr precipitation forecast values. In log files, task will be named like ``MET_PcpCombine_fcst_APCP##h_mem###`` where ##h is 03h, 06h, or 24h. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list. + * - metatask_GridStat_CCPA_all_accums_all_mems + - Runs METplus grid-to-grid verification for 1- h, 3-h, 6-h, and 24-h (i.e., daily) accumulated precipitation. In log files, task will be named like ``run_MET_GridStat_vx_APCP##h_mem###``. Valid values for ``##h`` are ``01h``, ``03h``, ``06h``, and ``24h``. + * - metatask_GridStat_MRMS_all_mems + - Runs METplus grid-to-grid verification for composite reflectivity and :term:`echo top`. In log files, task will be named like ``run_MET_GridStat_vx_REFC_mem###`` or ``run_MET_GridStat_vx_RETOP_mem###``. + * - metatask_PointStat_NDAS_all_mems + - Runs METplus grid-to-point verification for surface and upper-air variables In log files, task will be named like ``run_MET_PointStat_vx_SFC_mem###`` or ``run_MET_PointStat_vx_UPA_mem###``. + * - VX_ENSGRID + - Runs METplus grid-to-grid ensemble verification for 1-h accumulated precipitation. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSGRID_REFC + - Runs METplus grid-to-grid ensemble verification for composite reflectivity. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSGRID_RETOP + - Runs METplus grid-to-grid ensemble verification for :term:`echo top`. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSGRID_##h + - Runs METplus grid-to-grid ensemble verification for 3-h, 6-h, and 24-h (i.e., daily) accumulated precipitation. Valid values for ``##`` are ``03``, ``06``, and ``24``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - 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 ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - 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 ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSGRID_MEAN_##h + - Runs METplus grid-to-grid verification for ensemble mean 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation. Valid values for ``##`` are ``03``, ``06``, and ``24``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSGRID_PROB_##h + - Runs METplus grid-to-grid verification for 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation probabilistic output. Valid values for ``##`` are ``03``, ``06``, and ``24``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSGRID_PROB_REFC + - Runs METplus grid-to-grid verification for ensemble probabilities for composite reflectivity. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSGRID_PROB_RETOP + - Runs METplus grid-to-grid verification for ensemble probabilities for :term:`echo top`. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSPOINT + - Runs METplus grid-to-point ensemble verification for surface and upper-air variables. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSPOINT_MEAN + - Runs METplus grid-to-point verification for ensemble mean surface and upper-air variables. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - VX_ENSPOINT_PROB + - Runs METplus grid-to-point verification for ensemble probabilities for surface and upper-air variables. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. .. _Run: From db20aa9dbd82b9bfef328ed6692879a6650447a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 17 Jul 2023 15:47:16 -0400 Subject: [PATCH 026/116] update VX task table w/ensemble info --- .../source/BuildingRunningTesting/RunSRW.rst | 88 +++++++++---------- 1 file changed, 41 insertions(+), 47 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index cd4cdf9a37..9eb165d3df 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -1,3 +1,9 @@ +.. role:: bolditalic + :class: bolditalic + +.. role:: raw-html(raw) + :format: html + .. _RunSRW: =========================== @@ -662,11 +668,7 @@ To turn on verification (VX) tasks in the workflow, include the desired ``parm/w * - verify_ens.yaml - Perform ensemble vx -The ``verify_*.yaml`` files include the definitions of several common verification tasks by default. The tasks in each file are independent of each other, so users may want to turn some off depending on the needs of their experiment. Note that the ENSGRID and ENSPOINT tasks apply only to ensemble model verification. Individual verification tasks appear in :numref:`Table %s `. - -.. COMMENT: Check task names (still ENSGRID and ENSPOINT?) - -To turn off a task, simply include its entry from ``verify_*.yaml`` as an empty YAML entry in ``config.yaml``. For example, to turn off PointStat tasks: +The ``verify_*.yaml`` files include the definitions of several common verification tasks by default. Individual verification tasks appear in :numref:`Table %s `. The tasks in the ``verify_*.yaml`` files are independent of each other, so users may want to turn some off depending on the needs of their experiment. To turn off a task, simply include its entry from ``verify_*.yaml`` as an empty YAML entry in ``config.yaml``. For example, to turn off PointStat tasks: .. code-block:: console @@ -813,52 +815,44 @@ METplus verification tasks are described in :numref:`Table %s
    ` + (formerly *VX_ENSGRID_##h*) + - Runs METplus grid-to-grid ensemble verification for 1-h, 3-h, 6-h, and 24-h (i.e., daily) accumulated precipitation. In log files, tasks will be named like ``run_MET_EnsembleStat_vx_APCP##h`` or ``run_MET_GenEnsProd_vx_APCP##h``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - :bolditalic:`metatask_GenEnsProd_EnsembleStat_MRMS` :raw-html:`

    ` + (formerly *VX_ENSGRID_[REFC|RETOP]*) + - Runs METplus grid-to-grid ensemble verification for composite reflectivity and :term:`echo top`. In log files, tasks will be named like ``run_MET_GenEnsProd_vx_[REFC|RETOP]`` or ``run_MET_EnsembleStat_vx_[REFC|RETOP]``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - :bolditalic:`metatask_GridStat_CCPA_ensmeanprob_all_accums` :raw-html:`

    ` + (formerly *VX_ENSGRID_MEAN_##h* and *VX_ENSGRID_PROB_##h*) + - Runs METplus grid-to-grid verification for (1) ensemble mean 1-h, 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation and (2) 1-h, 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation probabilistic output. In log files, the ensemble mean subtask will be named like ``run_MET_GridStat_vx_ensmean_APCP##h`` and the ensemble probabilistic output subtask will be named like ``run_MET_GridStat_vx_ensprob_APCP##h``, where ``##h`` is 01h, 03h, 06h, or 24h. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - :bolditalic:`metatask_GridStat_MRMS_ensprob` :raw-html:`

    ` + (formerly *VX_ENSGRID_PROB_[REFC|RETOP]*) + - Runs METplus grid-to-grid verification for ensemble probabilities for composite reflectivity and :term:`echo top`. In log files, tasks will be named like ``run_MET_GridStat_vx_ensprob_[REFC|RETOP]``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - :bolditalic:`metatask_GenEnsProd_EnsembleStat_NDAS` :raw-html:`

    ` + (formerly *VX_ENSPOINT*) + - Runs METplus grid-to-point ensemble verification for surface and upper-air variables. In log files, tasks will be named like ``run_MET_GenEnsProd_vx_[SFC|UPA]`` or ``run_MET_EnsembleStat_vx_[SFC|UPA]``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + * - :bolditalic:`metatask_PointStat_NDAS_ensmeanprob` :raw-html:`

    ` + (formerly *VX_ENSPOINT_[MEAN|PROB]*) + - Runs METplus grid-to-point verification for (1) ensemble mean surface and upper-air variables and (2) ensemble probabilities for surface and upper-air variables. In log files, tasks will be named like ``run_MET_PointStat_vx_ensmean_[SFC|UPA]`` or ``run_MET_PointStat_vx_ensprob_[SFC|UPA]``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. .. _Run: From 2adb67b7ec7e5b360778881205f0e28d760e0aa9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 17 Jul 2023 15:47:47 -0400 Subject: [PATCH 027/116] add slides for Purser ESG grid --- docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst | 2 +- docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst index fc7b5e1391..ff89e0ffca 100644 --- a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst @@ -323,7 +323,7 @@ Grid Generation Parameters ``GRID_GEN_METHOD``: (Default: "") This variable specifies which method to use to generate a regional grid in the horizontal plane. The values that it can take on are: - * ``"ESGgrid"``: The "ESGgrid" method will generate a regional version of the Extended Schmidt Gnomonic (ESG) grid using the map projection developed by Jim Purser of EMC (:cite:t:`Purser_2020`). "ESGgrid" is the preferred grid option. + * ``"ESGgrid"``: The "ESGgrid" method will generate a regional version of the Extended Schmidt Gnomonic (ESG) grid using the map projection developed by Jim Purser of EMC (:cite:t:`Purser_2020`). "ESGgrid" is the preferred grid option. More information on the ESG grid is available at https://github.com/ufs-community/ufs-srweather-app/wiki/Purser_UIFCW_2023.pdf. * ``"GFDLgrid"``: The "GFDLgrid" method first generates a "parent" global cubed-sphere grid. Then a portion from tile 6 of the global grid is used as the regional grid. This regional grid is referred to in the grid generation scripts as "tile 7," even though it does not correspond to a complete tile. The forecast is run only on the regional grid (i.e., on tile 7, not on tiles 1 through 6). Note that the "GFDLgrid" method is the legacy grid generation method. It is not supported in *all* predefined domains. diff --git a/docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst b/docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst index 1c97b4e0bc..e4ddaa29b1 100644 --- a/docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst +++ b/docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst @@ -121,7 +121,7 @@ scripts that handle the workflow and experiment generation (see :numref:`Figure With those caveats in mind, this section provides instructions for adding a new predefined 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. More information on the ESG grid is available `here `__. 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: From 552d57b18e0bc375cd5106c7e6b83f280d68f90c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 17 Jul 2023 16:43:18 -0400 Subject: [PATCH 028/116] RunSRW edits --- .../source/BuildingRunningTesting/RunSRW.rst | 45 +++++++++++-------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 9eb165d3df..1c965414f2 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -371,6 +371,10 @@ On platforms where Rocoto and :term:`cron` are available, users can automate res USE_CRON_TO_RELAUNCH: true CRON_RELAUNCH_INTVL_MNTS: 3 +.. note:: + + 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. + When running with GNU compilers (i.e., if the modulefile used to set up the build environment in :numref:`Section %s ` uses a GNU compiler), users must also set ``COMPILER: "gnu"`` in the ``workflow:`` section of the ``config.yaml`` file. .. note:: @@ -863,7 +867,7 @@ The workflow can be run using the Rocoto workflow manager (see :numref:`Section .. attention:: - If users are running the SRW App on a system that does not have Rocoto installed (e.g., `Level 3 & 4 `__ systems, such as MacOS or generic Linux systems), they should follow the process outlined in :numref:`Section %s ` instead of the instructions in this section. + If users are running the SRW App on a system that does not have Rocoto installed (e.g., `Level 3 & 4 `__ systems, such as many MacOS or generic Linux systems), they should follow the process outlined in :numref:`Section %s `. .. _UseRocoto: @@ -871,14 +875,14 @@ The workflow can be run using the Rocoto workflow manager (see :numref:`Section Run the Workflow Using Rocoto -------------------------------- -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, 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 `. +The information in this section assumes that Rocoto is available on the desired platform. All official HPC platforms for the UFS SRW App make use of the Rocoto workflow management software for running experiments. However, 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 three ways to run the workflow with Rocoto: (1) automation via crontab (2) by calling the ``launch_FV3LAM_wflow.sh`` script, and (3) by manually issuing the ``rocotorun`` command. .. 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. + Users may find it helpful to review :numref:`Section %s: Rocoto Introductory Information ` 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: +Optionally, an environment variable can be set to navigate to the experiment directory (``$EXPTDIR``) more easily. If the login shell is bash, it can be set as follows: .. code-block:: console @@ -896,7 +900,7 @@ If the login shell is csh/tcsh, it can be set using: Automated Option ^^^^^^^^^^^^^^^^^^^ -The simplest way to run the Rocoto workflow is to automate the process using a job scheduler such as :term:`Cron`. For automatic resubmission of the workflow at regular intervals (e.g., every 3 minutes), the user can add the following commands to their ``config.yaml`` file *before* generating the experiment: +The simplest way to run the Rocoto workflow is to automate the process using a job scheduler such as :term:`Cron`. For automatic resubmission of the workflow at regular intervals (e.g., every 3 minutes), the user can add the following commands to their ``config.yaml`` file *before* generating the experiment (as outlined in :numref:`Section %s `): .. code-block:: console @@ -909,12 +913,12 @@ This will automatically add an appropriate entry to the user's :term:`cron table */3 * * * * cd && ./launch_FV3LAM_wflow.sh called_from_cron="TRUE" -where ```` is changed to correspond to the user's ``$EXPTDIR``. 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``. The number ``3`` can be changed to a different positive integer; it simply means that the workflow will be resubmitted every three minutes. .. hint:: * On NOAA Cloud instances, ``*/1 * * * *`` (or ``CRON_RELAUNCH_INTVL_MNTS: 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 * * * *`` (or ``CRON_RELAUNCH_INTVL_MNTS: 3``) is the preferred option for cron jobs on non-NOAA Cloud systems. + * On other NOAA HPC systems, administrators discourage using ``*/1 * * * *`` due to load problems. ``*/3 * * * *`` (or ``CRON_RELAUNCH_INTVL_MNTS: 3``) is the preferred option for cron jobs on non-NOAA Cloud systems. To check the experiment progress: @@ -925,10 +929,6 @@ To check the experiment progress: After finishing the experiment, open the crontab using ``crontab -e`` and delete the crontab entry. -.. note:: - - 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. - .. _Success: 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: @@ -950,7 +950,7 @@ The workflow run is complete when all tasks have "SUCCEEDED". If everything goes ... 201906151800 run_post_mem000_f012 4953381 SUCCEEDED 0 1 7.0 -If users choose to run METplus verification tasks as part of their experiment, the output above will include additional lines after ``run_post_f012``. The output will resemble the following but may be significantly longer when using ensemble verification: +If users choose to run METplus verification tasks as part of their experiment, the output above will include additional lines after ``run_post_mem000_f012``. The output will resemble the following but may be significantly longer when using ensemble verification: .. code-block:: console @@ -1001,7 +1001,7 @@ In order to launch additional tasks in the workflow, call the launch script agai ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow -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 similar to this: +This will output the last 40 lines of the log file, which lists 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 similar to this: .. code-block:: console @@ -1012,9 +1012,9 @@ This will output the last 40 lines of the log file, which list the status of the 201906151800 make_sfc_climo - - - - - 201906151800 get_extrn_ics druby://hfe01:33728 SUBMITTING - 0 0.0 201906151800 get_extrn_lbcs druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 make_ics - - - - - - 201906151800 make_lbcs - - - - - - 201906151800 run_fcst - - - - - + 201906151800 make_ics_mem000 - - - - - + 201906151800 make_lbcs_mem000 - - - - - + 201906151800 run_fcst_mem000 - - - - - 201906151800 run_post_mem000_f000 - - - - - 201906151800 run_post_mem000_f001 - - - - - 201906151800 run_post_mem000_f002 - - - - - @@ -1029,7 +1029,14 @@ This will output the last 40 lines of the log file, which list the status of the 0 out of 1 cycles completed. 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 task can be found in the task log files located in ``$EXPTDIR/log``. +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 task can be found in the task log files located in ``$EXPTDIR/log``. Users can look at the log file for a 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 + + cd $EXPTDIR/log + vi make_grid.log + +After making any required changes, users can restart a DEAD or failed task as described in :numref:`Section %s of the FAQ `. The workflow run is complete when all tasks have "SUCCEEDED", and the ``rocotostat`` command outputs a table similar to the one :ref:`above `. @@ -1083,7 +1090,7 @@ The SRW App workflow can be run using standalone shell scripts in cases where th .. attention:: - When working on an HPC system, users should allocate a compute node prior to running their experiment. The proper command will depend on the system's resource manager, but some guidance is offered in :numref:`Section %s `. It may be necessay to reload the workflow environment (see :numref:`Section %s `). It may also be necessary to load the ``build__`` scripts as described in :numref:`Section %s `. + When working on an HPC system, users should allocate a compute node prior to running their experiment. The proper command will depend on the system's resource manager, but some guidance is offered in :numref:`Section %s `. It may be necessary to reload the ``build__`` scripts (see :numref:`Section %s `) and the workflow environment (see :numref:`Section %s `). #. ``cd`` into the experiment directory. For example, from ``ush``, presuming default directory settings: @@ -1184,3 +1191,5 @@ Users can access log files for specific tasks in the ``$EXPTDIR/log`` directory. .. 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). + +.. COMMENT: Test manual run section. \ No newline at end of file From 8f976cfeb1d2f203951e679642e00b7961ab361c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 17 Jul 2023 17:35:20 -0400 Subject: [PATCH 029/116] some QS updates --- .../source/BuildingRunningTesting/Quickstart.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst index 23357e4814..b7eb9d5fc4 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst @@ -4,7 +4,7 @@ Quick Start Guide ==================== -This chapter provides a brief summary of how to build and run the SRW Application. The steps will run most smoothly on `Level 1 `__ systems. Users should expect to reference other chapters of this User's Guide, particularly :numref:`Chapter %s: Building the SRW App ` and :numref:`Chapter %s: Running the SRW App `, for additional explanations regarding each step. +This chapter provides a brief summary of how to build and run the SRW Application. The steps will run most smoothly on `Level 1 `__ systems. Users should expect to reference other chapters of this User's Guide, particularly :numref:`Section %s: Building the SRW App ` and :numref:`Section %s: Running the SRW App `, for additional explanations regarding each step. Install the HPC-Stack @@ -13,12 +13,15 @@ SRW App users who are not working on a `Level 1 `__ to prepare for the upcoming shift in support from HPC-Stack to spack-stack. + .. _QuickBuildRun: Building and Running 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: Building the SRW App ` and :numref:`Chapter %s: Running the SRW App `. :numref:`Figure %s ` outlines the steps of the build process. 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. +For a detailed explanation of how to build and run the SRW App on any supported system, see :numref:`Section %s: Building the SRW App ` and :numref:`Section %s: Running the SRW App `. :numref:`Figure %s ` outlines the steps of the build process. 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: @@ -49,8 +52,7 @@ For a detailed explanation of how to build and run the SRW App on any supported .. code-block:: console - source - module use + module use module load wflow_ where ```` refers to a valid machine name (see :numref:`Section %s `). After loading the workflow, users should follow the instructions printed to the console. For example, if the output says: @@ -62,11 +64,10 @@ For a detailed explanation of how to build and run the SRW App on any supported then the user should run ``conda activate workflow_tools`` to activate the workflow environment. - .. note:: - If users source the *lmod-setup* file on a system that doesn't need it, it will not cause any problems (it will simply do a ``module purge``). - #. Configure the experiment: + Copy the contents of the sample experiment from ``config.community.yaml`` to ``config.yaml``: + .. code-block:: console cd ush From 43fa96641ba8a4aac4328c020fa5b997274aa7c5 Mon Sep 17 00:00:00 2001 From: "Michael J. Kavulich, Jr" Date: Wed, 19 Jul 2023 04:44:45 +0000 Subject: [PATCH 030/116] First set of updates in RunSRW.rst --- .../source/BuildingRunningTesting/RunSRW.rst | 63 +++++++++++-------- 1 file changed, 37 insertions(+), 26 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 1c965414f2..8a3a301ad4 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -689,7 +689,7 @@ If users have access to NOAA :term:`HPSS` but have not pre-staged the data, the 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 `__. -Users who have already staged the observation data needed for METplus (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data in ``config.yaml`` and turn off the corresponding task by including them with no entry in the ``rocoto:`` section of ``config.yaml``. +Users who have already staged the observation data needed for METplus (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data in ``config.yaml``. .. code-block:: console @@ -697,12 +697,6 @@ Users who have already staged the observation data needed for METplus (i.e., the 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 - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify_pre.yaml", "parm/wflow/verify_det.yaml"]|include }}' - task_get_obs_ccpa: - task_get_obs_mrms: - task_get_obs_ndas: .. _GenerateWorkflow: @@ -809,54 +803,71 @@ In addition to the baseline tasks described in :numref:`Table %s ` below. For each task, ``mem###`` refers to either ``mem000`` (if running a deterministic forecast) or a specific forecast member number (if running an ensemble forecast). +METplus verification tasks are described in :numref:`Table %s ` below. The column "taskgroup" indicates the taskgroup file that must be included in the user's ``config.yaml`` file under ``rocoto: tasks: taskgroups:`` (see section SECTION for more details). For each task, ``mem###`` refers to either ``mem000`` (if running a deterministic forecast) or a specific forecast member number (if running an ensemble forecast). "Metatasks" indicate task definitions that will become more than one workflow task based on different variables, number of hours, etc., as described in the Task Description column. See :numref:`Section %s ` for more details about Metatasks. .. _VXWorkflowTasksTable: .. list-table:: Verification (VX) Workflow Tasks in the SRW App - :widths: 20 50 + :widths: 20 20 50 :header-rows: 1 * - Workflow Task + - ``taskgroup`` - Task Description * - :bolditalic:`task_get_obs_ccpa` - - Retrieves and organizes hourly :term:`CCPA` data from NOAA HPSS. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list *and* user has access to NOAA :term:`HPSS` data. + - ``verify_pre.yaml`` + - If user has staged :term:`CCPA` data for verification, checks to ensure that data exists in the specified location (CCPA_OBS_DIR). If data does not exist, attempts to retrieve that data from NOAA HPSS. * - :bolditalic:`task_get_obs_ndas` - - Retrieves and organizes hourly :term:`NDAS` data from NOAA HPSS. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list *and* user has access to NOAA :term:`HPSS` data. + - ``verify_pre.yaml`` + - If user has staged :term:`NDAS` data for verification, checks to ensure that data exists in the specified location (NDAS_OBS_DIR). If data does not exist, attempts to retrieve that data from NOAA HPSS. * - :bolditalic:`task_get_obs_mrms` - - Retrieves and organizes hourly :term:`MRMS` composite reflectivity and :term:`echo top` data from NOAA HPSS. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list *and* user has access to NOAA :term:`HPSS` data. + - ``verify_pre.yaml`` + - If user has staged :term:`MRMS` data for verification, checks to ensure that data exists in the specified location (MRMS_OBS_DIR). If data does not exist, attempts to retrieve that data from NOAA HPSS. * - :bolditalic:`task_run_MET_Pb2nc_obs` - - Convert files from prepbufr to NetCDF format. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list. + - ``verify_pre.yaml`` + - Convert files from prepbufr to NetCDF format. * - :bolditalic:`metatask_PcpCombine_obs` - - Derive 3-hr, 6-hr, and 24-hr accumulated precipitation observations from the 1-hr observation files. In log files, tasks will be named like ``MET_PcpCombine_obs_APCP##h``, where ``##h`` is 03h, 06h, or 24h. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list. + - ``verify_pre.yaml`` + - Derive 3-hr, 6-hr, and 24-hr accumulated precipitation observations from the 1-hr observation files. In log files, tasks will be named like ``MET_PcpCombine_obs_APCP##h``, where ``##h`` is 03h, 06h, or 24h. * - :bolditalic:`metatask_check_post_output_all_mems` - - Ensure that required post-processing tasks have completed and that the output exists in the correct form and location for each forecast member. In log files, tasks will be named like ``check_post_output_mem###``. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list. + - ``verify_pre.yaml`` + - Ensure that required post-processing tasks have completed and that the output exists in the correct form and location for each forecast member. In log files, tasks will be named like ``check_post_output_mem###``. * - :bolditalic:`metatask_PcpCombine_fcst_all_accums_all_mems` - - Derive accumulated precipitation forecast for 3-hr, 6-hr, and 24-hr windows for all forecast members based on 1-hr precipitation forecast values. In log files, tasks will be named like ``MET_PcpCombine_fcst_APCP##h_mem###``, where ``##h`` is 03h, 06h, or 24h. Can only be run if ``verify_pre.yaml`` is included in a ``tasksgroups`` list. + - ``verify_pre.yaml`` + - Derive accumulated precipitation forecast for 3-hr, 6-hr, and 24-hr windows for all forecast members based on 1-hr precipitation forecast values. In log files, tasks will be named like ``MET_PcpCombine_fcst_APCP##h_mem###``, where ``##h`` is 03h, 06h, or 24h. * - :bolditalic:`metatask_GridStat_CCPA_all_accums_all_mems` - - Runs METplus grid-to-grid verification for 1-h, 3-h, 6-h, and 24-h (i.e., daily) accumulated precipitation. In log files, tasks will be named like ``run_MET_GridStat_vx_APCP##h_mem###``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_det.yaml`` is included in a ``taskgroups`` list. + - ``verify_det.yaml`` + - Runs METplus grid-to-grid verification for 1-h, 3-h, 6-h, and 24-h (i.e., daily) accumulated precipitation. In log files, tasks will be named like ``run_MET_GridStat_vx_APCP##h_mem###``. * - :bolditalic:`metatask_GridStat_MRMS_all_mems` - - Runs METplus grid-to-grid verification for composite reflectivity and :term:`echo top`. In log files, tasks will be named like ``run_MET_GridStat_vx_REFC_mem###`` or ``run_MET_GridStat_vx_RETOP_mem###``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_det.yaml`` is included in a ``taskgroups`` list. + - ``verify_det.yaml`` + - Runs METplus grid-to-grid verification for composite reflectivity and :term:`echo top`. In log files, tasks will be named like ``run_MET_GridStat_vx_REFC_mem###`` or ``run_MET_GridStat_vx_RETOP_mem###``. * - :bolditalic:`metatask_PointStat_NDAS_all_mems` - - Runs METplus grid-to-point verification for surface and upper-air variables. In log files, tasks will be named like ``run_MET_PointStat_vx_SFC_mem###`` or ``run_MET_PointStat_vx_UPA_mem###``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_det.yaml`` is included in a ``taskgroups`` list. + - ``verify_det.yaml`` + - Runs METplus grid-to-point verification for surface and upper-air variables. In log files, tasks will be named like ``run_MET_PointStat_vx_SFC_mem###`` or ``run_MET_PointStat_vx_UPA_mem###``. * - :bolditalic:`metatask_GenEnsProd_EnsembleStat_CCPA` :raw-html:`

    ` (formerly *VX_ENSGRID_##h*) - - Runs METplus grid-to-grid ensemble verification for 1-h, 3-h, 6-h, and 24-h (i.e., daily) accumulated precipitation. In log files, tasks will be named like ``run_MET_EnsembleStat_vx_APCP##h`` or ``run_MET_GenEnsProd_vx_APCP##h``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + - ``verify_ens.yaml`` + - Runs METplus grid-to-grid ensemble verification for 1-h, 3-h, 6-h, and 24-h (i.e., daily) accumulated precipitation. In log files, tasks will be named like ``run_MET_EnsembleStat_vx_APCP##h`` or ``run_MET_GenEnsProd_vx_APCP##h``. Can only be run if ``DO_ENSEMBLE: true`` in ``config.yaml``. * - :bolditalic:`metatask_GenEnsProd_EnsembleStat_MRMS` :raw-html:`

    ` (formerly *VX_ENSGRID_[REFC|RETOP]*) - - Runs METplus grid-to-grid ensemble verification for composite reflectivity and :term:`echo top`. In log files, tasks will be named like ``run_MET_GenEnsProd_vx_[REFC|RETOP]`` or ``run_MET_EnsembleStat_vx_[REFC|RETOP]``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + - ``verify_ens.yaml`` + - Runs METplus grid-to-grid ensemble verification for composite reflectivity and :term:`echo top`. In log files, tasks will be named like ``run_MET_GenEnsProd_vx_[REFC|RETOP]`` or ``run_MET_EnsembleStat_vx_[REFC|RETOP]``. Can only be run if ``DO_ENSEMBLE: true`` in ``config.yaml``. * - :bolditalic:`metatask_GridStat_CCPA_ensmeanprob_all_accums` :raw-html:`

    ` (formerly *VX_ENSGRID_MEAN_##h* and *VX_ENSGRID_PROB_##h*) - - Runs METplus grid-to-grid verification for (1) ensemble mean 1-h, 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation and (2) 1-h, 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation probabilistic output. In log files, the ensemble mean subtask will be named like ``run_MET_GridStat_vx_ensmean_APCP##h`` and the ensemble probabilistic output subtask will be named like ``run_MET_GridStat_vx_ensprob_APCP##h``, where ``##h`` is 01h, 03h, 06h, or 24h. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + - ``verify_ens.yaml`` + - Runs METplus grid-to-grid verification for (1) ensemble mean 1-h, 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation and (2) 1-h, 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation probabilistic output. In log files, the ensemble mean subtask will be named like ``run_MET_GridStat_vx_ensmean_APCP##h`` and the ensemble probabilistic output subtask will be named like ``run_MET_GridStat_vx_ensprob_APCP##h``, where ``##h`` is 01h, 03h, 06h, or 24h. Can only be run if ``DO_ENSEMBLE: true`` in ``config.yaml``. * - :bolditalic:`metatask_GridStat_MRMS_ensprob` :raw-html:`

    ` (formerly *VX_ENSGRID_PROB_[REFC|RETOP]*) - - Runs METplus grid-to-grid verification for ensemble probabilities for composite reflectivity and :term:`echo top`. In log files, tasks will be named like ``run_MET_GridStat_vx_ensprob_[REFC|RETOP]``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + - ``verify_ens.yaml`` + - Runs METplus grid-to-grid verification for ensemble probabilities for composite reflectivity and :term:`echo top`. In log files, tasks will be named like ``run_MET_GridStat_vx_ensprob_[REFC|RETOP]``. Can only be run if ``DO_ENSEMBLE: true`` in ``config.yaml``. * - :bolditalic:`metatask_GenEnsProd_EnsembleStat_NDAS` :raw-html:`

    ` (formerly *VX_ENSPOINT*) - - Runs METplus grid-to-point ensemble verification for surface and upper-air variables. In log files, tasks will be named like ``run_MET_GenEnsProd_vx_[SFC|UPA]`` or ``run_MET_EnsembleStat_vx_[SFC|UPA]``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + - ``verify_ens.yaml`` + - Runs METplus grid-to-point ensemble verification for surface and upper-air variables. In log files, tasks will be named like ``run_MET_GenEnsProd_vx_[SFC|UPA]`` or ``run_MET_EnsembleStat_vx_[SFC|UPA]``. Can only be run if ``DO_ENSEMBLE: true`` in ``config.yaml``. * - :bolditalic:`metatask_PointStat_NDAS_ensmeanprob` :raw-html:`

    ` (formerly *VX_ENSPOINT_[MEAN|PROB]*) - - Runs METplus grid-to-point verification for (1) ensemble mean surface and upper-air variables and (2) ensemble probabilities for surface and upper-air variables. In log files, tasks will be named like ``run_MET_PointStat_vx_ensmean_[SFC|UPA]`` or ``run_MET_PointStat_vx_ensprob_[SFC|UPA]``. Can only be run if ``DO_ENSEMBLE: true`` and ``verify_ens.yaml`` is included in a ``taskgroups`` list. + - ``verify_ens.yaml`` + - Runs METplus grid-to-point verification for (1) ensemble mean surface and upper-air variables and (2) ensemble probabilities for surface and upper-air variables. In log files, tasks will be named like ``run_MET_PointStat_vx_ensmean_[SFC|UPA]`` or ``run_MET_PointStat_vx_ensprob_[SFC|UPA]``. Can only be run if ``DO_ENSEMBLE: true`` in ``config.yaml``. .. _Run: @@ -1192,4 +1203,4 @@ Users can access log files for specific tasks in the ``$EXPTDIR/log`` directory. .. 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). -.. COMMENT: Test manual run section. \ No newline at end of file +.. COMMENT: Test manual run section. From e6fca92286364c74884bf654f3ea588499cf61a7 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 18 Jul 2023 23:25:43 -0600 Subject: [PATCH 031/116] More updates for PR 864 --- .../source/TechnicalDetails/ConfigWorkflow.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst index ff89e0ffca..9aee82bb29 100644 --- a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst @@ -151,25 +151,25 @@ METplus Parameters * ``SS`` refers to the two-digit valid seconds of the hour ``CCPA_OBS_DIR``: (Default: "") - 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_CCPA`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify.yaml``). + 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_CCPA`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). - METplus configuration files require the use of a 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. + METplus configuration files require the use of a 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. 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 (``scripts/exregional_get_obs_ccpa.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_obs_ccpa.sh`` script. + 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) for dates up until 2021-05-04. The script to pull the CCPA data from the NOAA HPSS (``scripts/exregional_get_verif_obs.sh``) has an example of how to account for this and organize the data into a more intuitive format. ``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 :term:`HPSS` (if the user has access) via the ``GET_OBS_MRMS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify.yaml``). 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 `. + 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_MRMS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. + + 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}0000.grib2``, where YYYYMMDD and {HH} 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 that retrieves 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: ``scripts/exregional_get_obs_mrms.sh``. This script calls the script used to identify the MRMS file closest to the valid time: ``ush/mrms_pull_topofhour.py``. + 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 that retrieves 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: ``scripts/exregional_get_verif_obs.sh``. This script calls the script used to identify the MRMS file closest to the valid time: ``ush/mrms_pull_topofhour.py``. ``NDAS_OBS_DIR``: (Default: "") - User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_NDAS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. Please note, this path must be defined as ``//ndas/proc``. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. + User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_NDAS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. - METplus configuration files require the use of predetermined file names. Therefore, if the NDAS files are user-provided, they need to follow the anticipated naming structure: ``prepbufr.ndas.{YYYYMMDDHH}``, where YYYYMMDDHH is as described in the note :ref:`above `. The script to pull the NDAS data from the NOAA HPSS (``scripts/exregional_get_obs_ndas.sh``) has an example of how to rename the NDAS data into a more intuitive format with the valid time listed in the file name. + METplus configuration files require the use of predetermined file names. Therefore, if the NDAS files are user-provided, they need to follow the anticipated naming structure: ``prepbufr.ndas.{YYYYMMDDHH}``, where YYYYMMDDHH is as described in the note :ref:`above `. The script to pull the NDAS data from the NOAA HPSS (``scripts/exregional_get_verif_obs.sh``) has an example of how to rename the NDAS data into a more intuitive format with the valid time listed in the file name. Test Directories ---------------------- From 07ee7a5683abf61b3cb5844356fe2442cddb2d8e Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 18 Jul 2023 23:34:25 -0600 Subject: [PATCH 032/116] 'GET_OBS' isn't a valid config.yaml variable --- docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst index 9aee82bb29..362976eff6 100644 --- a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst @@ -376,12 +376,6 @@ Compiler ``COMPILER``: (Default: "intel") Type of compiler invoked during the build step. Currently, this must be set manually; it is not inherited from the build system in the ``ufs-srweather-app`` directory. Valid values: ``"intel"`` | ``"gnu"`` -Verification Parameters ---------------------------- - -``GET_OBS``: (Default: "get_obs") - Set the name of the Rocoto workflow task used to load proper module files for ``GET_OBS_*`` tasks. Users typically do not need to change this value. - .. _NCOModeParms: From 27095ed4c0dc08d5fe49e59254b83fcd9fed95ed Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 18 Jul 2023 23:46:33 -0600 Subject: [PATCH 033/116] Add section links for more information --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 8a3a301ad4..1d10cbab5d 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -803,7 +803,7 @@ In addition to the baseline tasks described in :numref:`Table %s ` below. The column "taskgroup" indicates the taskgroup file that must be included in the user's ``config.yaml`` file under ``rocoto: tasks: taskgroups:`` (see section SECTION for more details). For each task, ``mem###`` refers to either ``mem000`` (if running a deterministic forecast) or a specific forecast member number (if running an ensemble forecast). "Metatasks" indicate task definitions that will become more than one workflow task based on different variables, number of hours, etc., as described in the Task Description column. See :numref:`Section %s ` for more details about Metatasks. +METplus verification tasks are described in :numref:`Table %s ` below. The column "taskgroup" indicates the taskgroup file that must be included in the user's ``config.yaml`` file under ``rocoto: tasks: taskgroups:`` (see :numref:`Section %s ` for more details). For each task, ``mem###`` refers to either ``mem000`` (if running a deterministic forecast) or a specific forecast member number (if running an ensemble forecast). "Metatasks" indicate task definitions that will become more than one workflow task based on different variables, number of hours, etc., as described in the Task Description column. See :numref:`Section %s ` for more details about Metatasks. .. _VXWorkflowTasksTable: From f13fec5ed9e27ab62be16bf6b08142b6a0cd97e4 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 19 Jul 2023 08:13:55 -0600 Subject: [PATCH 034/116] Better description of MRMS data staging script --- docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst index 362976eff6..f778641f04 100644 --- a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst @@ -164,7 +164,7 @@ METplus Parameters 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}0000.grib2``, where YYYYMMDD and {HH} 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 that retrieves 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: ``scripts/exregional_get_verif_obs.sh``. This script calls the script used to identify the MRMS file closest to the valid time: ``ush/mrms_pull_topofhour.py``. + METplus is configured to look for a MRMS composite reflectivity file for the valid time of the forecast being verified, which is why the minutes and seconds of the filename are hard-coded as "0000". Because MRMS composite reflectivity files do not typically match the valid time exactly, a script (``ush/mrms_pull_topofhour.py``) is called from within the MRMS task that identifies and renames the MRMS file nearest to the valid time to match the valid time of the forecast. This script can also be called separately for staging data independently of the workflow. ``NDAS_OBS_DIR``: (Default: "") User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``GET_OBS_NDAS`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. From f0656eb80ceb52e19f459531333a377a53adbc10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 20 Jul 2023 22:25:14 -0400 Subject: [PATCH 035/116] minor formatting --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 1d10cbab5d..a7174fb738 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -670,7 +670,7 @@ To turn on verification (VX) tasks in the workflow, include the desired ``parm/w * - verify_det.yaml - Perform deterministic vx * - verify_ens.yaml - - Perform ensemble vx + - Perform ensemble vx (must set ``DO_ENSEMBLE: true`` in ``config.yaml``) The ``verify_*.yaml`` files include the definitions of several common verification tasks by default. Individual verification tasks appear in :numref:`Table %s `. The tasks in the ``verify_*.yaml`` files are independent of each other, so users may want to turn some off depending on the needs of their experiment. To turn off a task, simply include its entry from ``verify_*.yaml`` as an empty YAML entry in ``config.yaml``. For example, to turn off PointStat tasks: @@ -816,13 +816,13 @@ METplus verification tasks are described in :numref:`Table %s Date: Sat, 29 Jul 2023 04:35:41 -0600 Subject: [PATCH 036/116] add details on AQM executables & tasks --- .../source/BuildingRunningTesting/AQM.rst | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst index 4c810f0d69..834e4a9241 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst @@ -51,6 +51,25 @@ where ```` is ``hera``, or ``wcoss2``. The ``-a`` argument indicates th Building the SRW App with AQM on other machines, including other `Level 1 `__ platforms, is not currently guaranteed to work, and users may have to make adjustments to the modulefiles for their system. +If the SRW-AQM build correctly, users should see the standard executables listed in :numref:`Table %s `. Additionally, users should see the AQM-utils executables described in :numref:`Table %s <>` in the ``ufs-srweather-app/exec`` directory. + +.. _AQM-exec: + +.. list-table:: *Names and descriptions of additional executables produced when the ATMAQ option is enabled* + :widths: 20 50 + :header-rows: 1 + + * - Executable + - Description + * - decomp-ptemis-mpi + - Splits the point-source emission file into subdomain based on runtime configure setting. + * - gefs2lbc_para + - Interpolates GOCART concentration to be lateral boundary condition for regional air quality model and outputs a layer result for checking purpose. + * - nexus + - + +.. COMMENT: Add NEXUS definition + Load the ``workflow_tools`` Environment -------------------------------------------- @@ -133,6 +152,115 @@ Users may check experiment status from the experiment directory with either of t ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow +Description of Workflow Tasks +------------------------------- + +The default workflow contains the workflow tasks described in :numref:`Table %s `. The SRW-AQM workflow contains these tasks along with additional tasks described in :numref:`Table %s `. + + +.. _AQM-Wflow-Tasks: + +.. list-table:: *Workflow Tasks for the ATMAQ Configuration* + :widths: 20 50 + :header-rows: 1 + + * - Task + - Description + * - nexus_gfs_sfc + - + * - nexus_emission_## + - + * - nexus_post_split + - + * - fire_emission + - This executable is used to convert both satellite-retrieved gas and aerosol species emissions (RAVE) from mass (kg) to emission rates (kg/m2/s) and create 3-day hourly model-ready fire emission input files. + * - point_source + - + * - aqm_ics + - It creates a chemical initial condition file by using the previous cycle restart files + * - aqm_lbcs + - + * - + - + * - + - + * - pre_post_stat + - It creates surface (i.e., the model 1st level) meteorological and chemical files to support air quality product generation and generate training data to support bias correction tasks. + * - post_stat_o3 + - It generates air quality forecast products including hourly-average and statistical products for O3 (e.g., daily 8-hour average maximum O3). + * - post_stat_pm25 + - It generates air quality forecast products including hourly-average and statistical products for PM2.5 (e.g., 24-hour average PM2.5). + * - bias_correction_o3: + - It applies a bias-correction technique (e.g., analog ensemble) to improve model raw forecast for O3 and generates the bias-corrected O3 products. + * - bias_correction_pm25: + - It applies a bias-correction technique (e.g., analog ensemble) to improve model raw forecast for PM2.5 and generates the bias-corrected PM2.5 products. + + + +:numref:`Figure %s <>` illustrates the overall AQM workflow. Individual tasks that make up the workflow are detailed in the ``FV3LAM_wflow.xml`` file. :numref:`Table %s ` describes the function of each baseline 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 removing the prep.yaml file from the default taskgroups entry in the config.yaml file before running the generate_FV3LAM_wflow.py script: + +.. COMMENT: AQM wflow figure here + +The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (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 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. + + + + +.. _Success: + +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: + +(workflow_tools) [Gillian.Petro@hfe03 aqm_community]$ rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION +========================================================================================== +202302170000 make_grid 47411619 QUEUED - 0 0.0 +202302170000 make_orog - - - - - +202302170000 make_sfc_climo - - - - - +202302170000 nexus_gfs_sfc 47411620 QUEUED - 0 0.0 +202302170000 nexus_emission_00 - - - - - +202302170000 nexus_emission_01 - - - - - +202302170000 nexus_emission_02 - - - - - +202302170000 nexus_post_split - - - - - +202302170000 fire_emission 47411621 QUEUED - 0 0.0 +202302170000 point_source - - - - - +202302170000 aqm_lbcs - - - - - +202302170000 get_extrn_ics 47411622 QUEUED - 0 0.0 +202302170000 get_extrn_lbcs 47411623 QUEUED - 0 0.0 +202302170000 make_ics_mem000 - - - - - +202302170000 make_lbcs_mem000 - - - - - +202302170000 run_fcst_mem000 - - - - - +202302170000 run_post_mem000_f000 - - - - - +202302170000 run_post_mem000_f001 - - - - - +202302170000 run_post_mem000_f002 - - - - - +... +202302170000 run_post_mem000_f006 - - - - - +========================================================================================== +202302170600 nexus_gfs_sfc 47411624 QUEUED - 0 0.0 +202302170600 nexus_emission_00 - - - - - +202302170600 nexus_emission_01 - - - - - +202302170600 nexus_emission_02 - - - - - +202302170600 nexus_post_split - - - - - +202302170600 fire_emission 47411625 QUEUED - 0 0.0 +202302170600 point_source - - - - - +202302170600 aqm_ics - - - - - +202302170600 aqm_lbcs - - - - - +202302170600 get_extrn_ics 47411626 QUEUED - 0 0.0 +202302170600 get_extrn_lbcs 47411627 QUEUED - 0 0.0 +202302170600 make_ics_mem000 - - - - - +202302170600 make_lbcs_mem000 - - - - - +202302170600 run_fcst_mem000 - - - - - +202302170600 run_post_mem000_f000 - - - - - +202302170600 run_post_mem000_f001 - - - - - +202302170600 run_post_mem000_f002 - - - - - +... +202302170600 run_post_mem000_f012 - - - - - + + + + + + + WE2E Test for AQM ======================= From 78d7c6d6951e7011fc6f4d92bc47514e9cdc98c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Sat, 29 Jul 2023 04:36:02 -0600 Subject: [PATCH 037/116] minor Tutorial & QS updates --- .../source/BuildingRunningTesting/ContainerQuickstart.rst | 1 + .../UsersGuide/source/BuildingRunningTesting/Tutorial.rst | 8 ++++++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index 60b9113cd1..728dfa008b 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -241,6 +241,7 @@ To activate the workflow, run the following commands: .. code-block:: console + source etc/lmod-setup.sh module use module load wflow_ diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst index 270782861d..e71e33e838 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst @@ -142,7 +142,7 @@ In the ``workflow:`` section of ``config.yaml``, update ``EXPT_SUBDIR`` and ``PR Users may also want to set ``USE_CRON_TO_RELAUNCH: true`` and add ``CRON_RELAUNCH_INTVL_MNTS: 3``. This will automate submission of workflow tasks when running the experiment. However, not all systems have :term:`cron`. -``EXPT_SUBDIR:`` This variable can be changed to any name the user wants. This tutorial uses ``control`` to establish a baseline, or "control", forecast. Users can choose any name they want, from "gfsv16_physics_fcst" to "forecast1" to "a;skdfj". However, the best names will indicate useful information about the experiment. For example, this tutorial helps users to compare the output from two different forecasts: one that uses the FV3_GFS_v16 physics suite and one that uses the FV3_RRFS_v1beta physics suite. Therefore, "gfsv16_physics_fcst" could be a good alternative directory name. +``EXPT_SUBDIR:`` This variable can be changed to any name the user wants from "gfsv16_physics_fcst" to "forecast1" to "a;skdfj". However, the best names will indicate useful information about the experiment. This tutorial uses ``control`` to establish a baseline, or "control", forecast. Since this tutorial helps users to compare the output from two different forecasts --- one that uses the FV3_GFS_v16 physics suite and one that uses the FV3_RRFS_v1beta physics suite --- "gfsv16_physics_fcst" could be a good alternative directory name. ``PREDEF_GRID_NAME:`` This experiment uses the SUBCONUS_Ind_3km grid, rather than the default RRFS_CONUS_25km grid. The SUBCONUS_Ind_3km grid is a high-resolution grid (with grid cell size of approximately 3km) that covers a small area of the U.S. centered over Indianapolis, IN. For more information on this grid, see :numref:`Section %s `. @@ -248,6 +248,8 @@ Once the control case is running, users can return to the ``config.yaml`` file ( Later, users may want to conduct additional experiments using the FV3_HRRR and FV3_WoFS_v0 physics suites. Like FV3_RRFS_v1beta, these physics suites were designed for use with high-resolution grids for storm-scale predictions. +.. COMMENT: Maybe also FV3_RAP? + Next, users will need to modify the data parameters in ``task_get_extrn_ics:`` and ``task_get_extrn_lbcs:`` to use HRRR and RAP data rather than FV3GFS data. Users will need to change the following lines in each section: .. code-block:: console @@ -271,6 +273,8 @@ Add a section to ``config.yaml`` to increase the maximum wall time (``WTIME_RUN_ task_run_post: WTIME_RUN_POST: 00:20:00 +.. COMMENT: Fix above! Maybe add to rocoto section? Otherwise tell them to modify parm/wflow yamls + Lastly, users must set the ``COMOUT_REF`` variable in the ``task_plot_allvars:`` section to create difference plots that compare output from the two experiments. ``COMOUT_REF`` is a template variable, so it references other workflow variables within it (see :numref:`Section %s ` for details on template variables). ``COMOUT_REF`` should provide the path to the ``control`` experiment forecast output using single quotes as shown below: .. code-block:: console @@ -356,7 +360,7 @@ The plots generated by the experiment cover a variety of variables. After downlo | Max/Min 2 - 5 km updraft helicity | uh25_diff_regional_fhhh.png | +-----------------------------------------+-----------------------------------+ -Each difference plotting ``.png`` file contains three subplots. The plot for the second experiment (``test_expt``) appears in the top left corner, and the plot for the first experiment (``control``) appears in the top right corner. The difference plot that compares both experiments appear at the bottom. Areas of white signify no difference between the plots. Therefore, if the forecast output from both experiments is exactly the same, the difference plot will show a white square (see :ref:`Sea Level Pressure ` for an example). If the forecast output from both experiments is extremely different, the plot will show lots of color. +Each difference plotting ``.png`` file contains three subplots. The plot for the second experiment (``test_expt``) appears in the top left corner, and the plot for the first experiment (``control``) appears in the top right corner. The difference plot that compares both experiments appears at the bottom. Areas of white signify no difference between the plots. Therefore, if the forecast output from both experiments is exactly the same, the difference plot will show a white square (see :ref:`Sea Level Pressure ` for an example). If the forecast output from both experiments is extremely different, the plot will show lots of color. In general, it is expected that the results for ``test_expt`` (using FV3_RRFS_v1beta physics and HRRR/RAP data) will be more accurate than the results for ``control`` (using FV3_GFS_v16 physics and FV3GFS data) because the physics in ``test_expt`` is designed for high-resolution, storm-scale prediction over a short period of time. The ``control`` experiment physics is better for predicting the evolution of larger scale weather phenomena, like jet stream movement and cyclone development, since the cumulus physics in the FV3_GFS_v16 suite is not configured to run at 3-km resolution. From 2bbc3ac9c603f0aa426f3bd7c9cc3358ed76aac9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 1 Aug 2023 18:47:41 -0400 Subject: [PATCH 038/116] update AQM section --- .../source/BackgroundInfo/Components.rst | 2 + .../source/BuildingRunningTesting/AQM.rst | 311 +++++++----------- docs/UsersGuide/source/Reference/Glossary.rst | 6 + 3 files changed, 125 insertions(+), 194 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Components.rst b/docs/UsersGuide/source/BackgroundInfo/Components.rst index c7e71d3425..890270198a 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Components.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Components.rst @@ -74,6 +74,8 @@ Air Quality Modeling (AQM) Utilities AQM Utilities (AQM-utils) includes the utility executables and python scripts to run SRW-AQM (Online-CMAQ). For more information on AQM-utils, visit the GitHub repository at https://github.com/NOAA-EMC/AQM-utils. +.. _nexus: + NOAA Emission and eXchange Unified System (NEXUS) =================================================== diff --git a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst index 834e4a9241..5bb86427ad 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst @@ -51,7 +51,7 @@ where ```` is ``hera``, or ``wcoss2``. The ``-a`` argument indicates th Building the SRW App with AQM on other machines, including other `Level 1 `__ platforms, is not currently guaranteed to work, and users may have to make adjustments to the modulefiles for their system. -If the SRW-AQM build correctly, users should see the standard executables listed in :numref:`Table %s `. Additionally, users should see the AQM-utils executables described in :numref:`Table %s <>` in the ``ufs-srweather-app/exec`` directory. +If the SRW-AQM builds correctly, users should see the standard executables listed in :numref:`Table %s `. Additionally, users should see the AQM-specific executables described in :numref:`Table %s ` in the ``ufs-srweather-app/exec`` directory. .. _AQM-exec: @@ -64,11 +64,9 @@ If the SRW-AQM build correctly, users should see the standard executables listed * - decomp-ptemis-mpi - Splits the point-source emission file into subdomain based on runtime configure setting. * - gefs2lbc_para - - Interpolates GOCART concentration to be lateral boundary condition for regional air quality model and outputs a layer result for checking purpose. + - Interpolates :term:`GOCART` concentration to be lateral boundary condition for regional air quality model and outputs a layer result for checking purpose. * - nexus - - - -.. COMMENT: Add NEXUS definition + - Runs the NOAA Emission and eXchange Unified System (:ref:`NEXUS `) emissions processing system Load the ``workflow_tools`` Environment -------------------------------------------- @@ -108,7 +106,10 @@ Users will need to configure their experiment by setting parameters in the ``con Users may prefer to copy the ``config.aqm.nco.realtime.yaml`` for a default "nco" mode experiment instead. -Users will need to change the ``MACHINE`` and ``ACCOUNT`` variables in ``config.yaml`` to match their system. They may also wish to adjust other experiment settings. For more information on each task and variable, see :numref:`Chapter %s `. +Users will need to change the ``MACHINE`` and ``ACCOUNT`` variables in ``config.yaml`` to match their system. They may also wish to adjust other experiment settings. For more information on each task and variable, see :numref:`Section %s `. + +.. COMMENT: Get data locations!!! The NODD bucket below is empty. + Users can find the data required for the community experiment in the `NOAA Global Forecast System Data Bucket `__. Users may also wish to change :term:`cron`-related parameters in ``config.yaml``. In the ``config.aqm.community.yaml`` file, which was copied into ``config.yaml``, cron is used for automatic submission and resubmission of the workflow: @@ -120,6 +121,12 @@ Users may also wish to change :term:`cron`-related parameters in ``config.yaml`` This means that cron will submit the launch script every 3 minutes. Users may choose not to submit using cron or to submit at a different frequency. Note that users should create a crontab by running ``crontab -e`` the first time they use cron. +When using the basic ``config.aqm.community.yaml`` experiment, the AQM pre-processing tasks are automatically turned on by adding ``"parm/wflow/aqm_prep.yaml"`` to the list of workflow files in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml`` (see :numref:`Section %s ` for task descriptions). To turn on AQM post-processing tasks in the workflow, include ``"parm/wflow/aqm_post.yaml"`` in the ``rocoto: tasks: taskgroups:`` section, too (see :numref:`Section %s ` for task descriptions). + +.. attention:: + + The module required to run the post-processing tasks is available only on WCOSS2. Therefore, ``aqm_post.yaml`` should not be added to the ``rocoto: tasks: taskgroups:`` section of ``config.yaml`` on any other platforms. + Generate the Workflow ------------------------ @@ -145,121 +152,137 @@ Users may check experiment status from the experiment directory with either of t .. code-block:: console - # Check the experiment status (best for cron jobs) + # Check the experiment status (for cron jobs) rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 # Check the experiment status and relaunch the workflow (for manual jobs) ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow +To see a description of each of the AQM workflow tasks, see :numref:`Section %s `. -Description of Workflow Tasks -------------------------------- +.. _Success: -The default workflow contains the workflow tasks described in :numref:`Table %s `. The SRW-AQM workflow contains these tasks along with additional tasks described in :numref:`Table %s `. +Experiment Output +-------------------- +The workflow run is complete when all tasks display a "SUCCEEDED" message. If everything goes smoothly, users will eventually see a workflow status table similar to the following: -.. _AQM-Wflow-Tasks: +.. code-block:: console + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION +============================================================================================ +202302170000 make_grid 47411619 SUCCEEDED 0 1 36.0 +202302170000 make_orog 47411728 SUCCEEDED 0 1 151.0 +202302170000 make_sfc_climo 47411801 SUCCEEDED 0 1 58.0 +202302170000 nexus_gfs_sfc 47411620 SUCCEEDED 0 1 37.0 +202302170000 nexus_emission_00 47411729 SUCCEEDED 0 1 251.0 +202302170000 nexus_emission_01 47411730 SUCCEEDED 0 1 250.0 +202302170000 nexus_emission_02 47411731 SUCCEEDED 0 1 250.0 +202302170000 nexus_post_split 47412034 SUCCEEDED 0 1 44.0 +202302170000 fire_emission 47411621 SUCCEEDED 0 1 19.0 +202302170000 point_source 47411732 SUCCEEDED 0 1 82.0 +202302170000 aqm_lbcs 47412961 SUCCEEDED 0 1 - +202302170000 get_extrn_ics 47411622 SUCCEEDED 0 1 314.0 +202302170000 get_extrn_lbcs 47411623 SUCCEEDED 0 1 0.0 +202302170000 make_ics_mem000 - SUCCEEDED 0 1 109.0 +202302170000 make_lbcs_mem000 47412035 SUCCEEDED 0 1 - +202302170000 run_fcst_mem000 - SUCCEEDED 0 1 - +202302170000 run_post_mem000_f000 - SUCCEEDED 0 1 - +202302170000 run_post_mem000_f001 - SUCCEEDED 0 1 - +202302170000 run_post_mem000_f002 - SUCCEEDED 0 1 - +... +202302170000 run_post_mem000_f006 - SUCCEEDED 0 1 - +============================================================================================ +202302170600 nexus_gfs_sfc 47411624 SUCCEEDED 0 1 44.0 +202302170600 nexus_emission_00 47411733 SUCCEEDED 0 1 323.0 +202302170600 nexus_emission_01 47411734 SUCCEEDED 0 1 323.0 +202302170600 nexus_emission_02 47411735 SUCCEEDED 0 1 329.0 +202302170600 nexus_post_split 47411736 SUCCEEDED 0 1 60.0 +202302170600 fire_emission 47411625 SUCCEEDED 0 1 18.0 +202302170600 point_source 47411736 SUCCEEDED 0 1 128.0 +202302170600 aqm_ics - SUCCEEDED 0 1 - +202302170600 aqm_lbcs - SUCCEEDED 0 1 - +202302170600 get_extrn_ics 47411626 SUCCEEDED 0 1 493.0 +202302170600 get_extrn_lbcs 47411627 SUCCEEDED 0 1 0.0 +202302170600 make_ics_mem000 47412037 SUCCEEDED 0 1 134.0 +202302170600 make_lbcs_mem000 - SUCCEEDED 0 1 - +202302170600 run_fcst_mem000 - SUCCEEDED 0 1 - +202302170600 run_post_mem000_f000 - SUCCEEDED 0 1 - +202302170600 run_post_mem000_f001 - SUCCEEDED 0 1 - +202302170600 run_post_mem000_f002 - SUCCEEDED 0 1 - +... +202302170600 run_post_mem000_f012 - SUCCEEDED 0 1 - -.. list-table:: *Workflow Tasks for the ATMAQ Configuration* - :widths: 20 50 - :header-rows: 1 +.. COMMENT: Fix table above by adding job numbers and duration!!! - * - Task - - Description - * - nexus_gfs_sfc - - - * - nexus_emission_## - - - * - nexus_post_split - - - * - fire_emission - - This executable is used to convert both satellite-retrieved gas and aerosol species emissions (RAVE) from mass (kg) to emission rates (kg/m2/s) and create 3-day hourly model-ready fire emission input files. - * - point_source - - - * - aqm_ics - - It creates a chemical initial condition file by using the previous cycle restart files - * - aqm_lbcs - - - * - - - - * - - - - * - pre_post_stat - - It creates surface (i.e., the model 1st level) meteorological and chemical files to support air quality product generation and generate training data to support bias correction tasks. - * - post_stat_o3 - - It generates air quality forecast products including hourly-average and statistical products for O3 (e.g., daily 8-hour average maximum O3). - * - post_stat_pm25 - - It generates air quality forecast products including hourly-average and statistical products for PM2.5 (e.g., 24-hour average PM2.5). - * - bias_correction_o3: - - It applies a bias-correction technique (e.g., analog ensemble) to improve model raw forecast for O3 and generates the bias-corrected O3 products. - * - bias_correction_pm25: - - It applies a bias-correction technique (e.g., analog ensemble) to improve model raw forecast for PM2.5 and generates the bias-corrected PM2.5 products. +.. _AQM-more-tasks: +Additional Tasks for AQM +=============================== +Structure of SRW-AQM Workflow +-------------------------------- -:numref:`Figure %s <>` illustrates the overall AQM workflow. Individual tasks that make up the workflow are detailed in the ``FV3LAM_wflow.xml`` file. :numref:`Table %s ` describes the function of each baseline 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 removing the prep.yaml file from the default taskgroups entry in the config.yaml file before running the generate_FV3LAM_wflow.py script: +:numref:`Figure %s ` illustrates the full non-:term:`DA` SRW-AQM workflow using a flowchart. Compared to the uncoupled (atmosphere-only) workflow (see :numref:`Table %s `), SRW-AQM has additional tasks for pre- and post-processing. For pre-processing, multiple emissions data such as NEXUS, fire, and point-source emissions are retrieved or created for air quality modeling. Moreover, the chemical initial conditions (ICs) are extracted from the restart files of the previous cycle and added to the existing IC files. The chemical lateral boundary conditions (LBCs) and the GEFS aerosol data are also added to the existing LBC files. For post-processing, air quality forecast products for ozone (O3) and 2.5-micron particulate matter (PM2.5) are generated, and the bias-correction technique is applied to improve the accuracy of the results. -.. COMMENT: AQM wflow figure here +.. _FlowProcAQM: -The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (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 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. +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW-AQM_workflow.png + :alt: Flowchart of the SRW-AQM tasks. + *Workflow structure of SRW-AQM (non-DA)* +Pre-processing Tasks of SRW-AQM +------------------------------------ -.. _Success: +The pre-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. -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: - -(workflow_tools) [Gillian.Petro@hfe03 aqm_community]$ rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION -========================================================================================== -202302170000 make_grid 47411619 QUEUED - 0 0.0 -202302170000 make_orog - - - - - -202302170000 make_sfc_climo - - - - - -202302170000 nexus_gfs_sfc 47411620 QUEUED - 0 0.0 -202302170000 nexus_emission_00 - - - - - -202302170000 nexus_emission_01 - - - - - -202302170000 nexus_emission_02 - - - - - -202302170000 nexus_post_split - - - - - -202302170000 fire_emission 47411621 QUEUED - 0 0.0 -202302170000 point_source - - - - - -202302170000 aqm_lbcs - - - - - -202302170000 get_extrn_ics 47411622 QUEUED - 0 0.0 -202302170000 get_extrn_lbcs 47411623 QUEUED - 0 0.0 -202302170000 make_ics_mem000 - - - - - -202302170000 make_lbcs_mem000 - - - - - -202302170000 run_fcst_mem000 - - - - - -202302170000 run_post_mem000_f000 - - - - - -202302170000 run_post_mem000_f001 - - - - - -202302170000 run_post_mem000_f002 - - - - - -... -202302170000 run_post_mem000_f006 - - - - - -========================================================================================== -202302170600 nexus_gfs_sfc 47411624 QUEUED - 0 0.0 -202302170600 nexus_emission_00 - - - - - -202302170600 nexus_emission_01 - - - - - -202302170600 nexus_emission_02 - - - - - -202302170600 nexus_post_split - - - - - -202302170600 fire_emission 47411625 QUEUED - 0 0.0 -202302170600 point_source - - - - - -202302170600 aqm_ics - - - - - -202302170600 aqm_lbcs - - - - - -202302170600 get_extrn_ics 47411626 QUEUED - 0 0.0 -202302170600 get_extrn_lbcs 47411627 QUEUED - 0 0.0 -202302170600 make_ics_mem000 - - - - - -202302170600 make_lbcs_mem000 - - - - - -202302170600 run_fcst_mem000 - - - - - -202302170600 run_post_mem000_f000 - - - - - -202302170600 run_post_mem000_f001 - - - - - -202302170600 run_post_mem000_f002 - - - - - -... -202302170600 run_post_mem000_f012 - - - - - +.. _TasksPrepAQM: +.. list-table:: *Tasks for Pre-Processing of AQM* + :widths: 20 50 + :header-rows: 1 + + * - Task Name + - Description + * - nexus_gfs_sfc + - Retrieves the GFS surface files from the previous cycle in near real-time (NRT) or from the current cycle in retrospective cases. The surface radiation, soil moisture, and temperature fields are needed to predict the :term:`MEGAN` biogenics emissions within the ``nexus_emission_##`` task. + * - nexus_emission_## + - Prepares the run directory with gridded emission inputs, runs :ref:`NEXUS` to create model-ready emissions for the given simulation day, and post processes NEXUS output to make it more readable. The task will also split the task into ``##`` jobs set by the user in ``config.yaml`` using ``NUM_SPLIT_NEXUS`` variable. + * - nexus_post_split + - Concatenates the NEXUS emission information into a single netCDF file (needed for the forecast) if NEXUS was split into multiple jobs. + * - fire_emission + - Converts both satellite-retrieved gas and aerosol species emissions (RAVE) from mass (kg) to emissions rates (kg/m2/s) and creates 3-day hourly model-ready fire emissions input files. + * - point_source + - Aggregates the anthropogenic point source sectors of the National Emission Inventory (NEI) into a ready-to-input point-source emission file based on the weekday/weekend/holiday patterns of each sector and the date/time of the simulation. + * - aqm_ics + - Creates a chemical initial conditions file by using the previous cycle restart files. + * - aqm_lbcs + - Adds the chemical lateral boundary conditions (LBC) to the meteorological lateral boundary conditions to form the full set of ready-to-input LBCs for the simulation. ``aqm_lbcs`` includes two sub-tasks: addition of the gaseous species LBCs and addition of dynamic aerosol LBCs. The former adds static gaseous LBCs using monthly mean global data. The latter is the parallel job, which extracts the GEFS-Aerosol Model's output along the regional domain and performs the species conversion from GOCART aerosols to CMAQ aerosols. +Post-processing Tasks of SRW-AQM +------------------------------------ +The post-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. Since the module required to run these tasks is available only on WCOSS2, these tasks should not be defined in the configuration file ``config.yaml`` on other platforms. +.. _TasksPostAQM: +.. list-table:: Tasks for Post-processing of AQM + :widths: 20 50 + :header-rows: 1 + * - Task name + - Description + * - pre_post_stat + - Creates surface (i.e., model first level) meteorological and chemical files to support air quality product generation and generate training data to support bias correction tasks. + * - post_stat_o3 + - Generates air quality forecast products, including hourly average and statistical products, for O3 (e.g., daily 8-hour average maximum O3). + * - post_stat_pm25 + - This task generates air quality forecast products, including hourly average and statistical products, for PM2.5 (e.g., 24-hour average PM2.5). + * - bias_correction_o3 + - Applies a bias-correction technique (e.g., analog ensemble) to improve the raw model forecast for O3 and generates the bias-corrected O3 products. + * - bias_correction_pm25 + - Applies a bias-correction technique (e.g., analog ensemble) to improve the raw model forecast for PM2.5 and generates the bias-corrected PM2.5 products. WE2E Test for AQM ======================= @@ -285,103 +308,3 @@ Run the WE2E test: $ ./run_WE2E_tests.py -t my_tests.txt -m hera -a gsd-fv3 -q - - -Additional Tasks for AQM -=============================== - -Structure of SRW-AQM -------------------------- - -The flowchart of the non-DA (data assimilation) SRW-AQM (Air Quality Modeling) is illustrated in :numref:`Figure %s `. Compared to the non-coupled (ATM stand-alone) FV3-LAM, SRW-AQM has additional tasks for pre- and post-processing. For pre-processing, multiple emission data such as NEXUS, fire, and point-source emission are retrieved or created for air quality modeling. Moreover, the chemical initial conditions (ICs) are extracted from the restart files of the previous cycle and added to the existing IC files. The chemical lateral boundary conditions (LBCs) and the GEFS aerosol data are also adeded to the existing LBC files. For post-processing, air quality forecast products for O3 and PM2.5 are generated and the bias-correction technique is applied to improve the accuracy of the results. - -.. _FlowProcAQM: - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW-AQM_workflow.png - :alt: Flowchart of the SRW-AQM tasks. - - *Workflow structure of SRW-AQM (non-DA)* - - - -Pre-processing Tasks of SRW-AQM ------------------------------------- - -The pre-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. - -.. _TasksPrepAQM: - -.. table:: Tasks for pre-processing of AQM - - +-----------------------+--------------------------------------------------------------------+ - | **Task name** | **Description** | - +=======================+====================================================================+ - | nexus_gfs_sfc | This task retrieves the GFS surface files from the previous cycle | - | | in NRT (Near-Real-Time) or current cycle in retrospective cases. | - | | The surface radiation, soil moisture and temperature fields are | - | | needed for the MEGAN biogenics emissions within nexus_emission. | - +-----------------------+--------------------------------------------------------------------+ - | nexus_emission | This task prepares the run directory with gridded emission inputs, | - | | run nexus to create model ready emission for the given simulation | - | | day, and post processes nexus output to make it more readable. The | - | | task will also split the task into multiple jobs set by the user. | - +-----------------------+--------------------------------------------------------------------+ - | nexus_post_split | This task combines the nexus_emission outputs into a single job. | - +-----------------------+--------------------------------------------------------------------+ - | fire_emission | This tasks is used to convert both satellite-retrieved gas and | - | | aerosol species emissions (RAVE) from mass (kg) to emission rates | - | | (kg/m2/s) and create 3-day hourly model-ready fire emission input | - | | files. | - +-----------------------+--------------------------------------------------------------------+ - | point_source | This task aggregates the anthropogenic point source sectors of the | - | | National Emission Inventory(NEI) into a ready-to-input point-source| - | | emission file based on the weekday/weekend/holiday patterns of each| - | | sector and date/time of the simulation. | - +-----------------------+--------------------------------------------------------------------+ - | aqm_ics | This task creates a chemical initial condition file by using the | - | | previous cycle restart files. | - +-----------------------+--------------------------------------------------------------------+ - | aqm_lbcs | This task adds the chemical lateral boundary condition (LBC) upon | - | | the meteorological lateral boundary condition to form the full-set | - | | ready-to-input LBC for the simulation. It includes two sub-tasks: | - | | the gaseous species LBC and dynamic aerosol LBC. The former adds | - | | static gaseous LBC using monthly mean global data. The latter is | - | | the parallel job, which extracts the GEFS-Aerosol Model's output | - | | along the regional domain, and performs the species conversion | - | | from GOCART aerosols to CMAQ aerosols. | - +-----------------------+--------------------------------------------------------------------+ - - -Post-processing Tasks of SRW-AQM ------------------------------------- - -The post-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. Since the module required to run these tasks is available only on WCOSS2, these tasks should not be defined in the configuration file ``config.yaml`` on other platforms. - -.. _TasksPostAQM: - -.. table:: Tasks for post-processing of AQM - - +-----------------------+--------------------------------------------------------------------+ - | **Task name** | **Description** | - +=======================+====================================================================+ - | pre_post_stat | This task creates surface (i.e., model 1st level) meteorological | - | | and chemical files to support air quality product generation and | - | | generate training data to support bias correction tasks. | - +-----------------------+--------------------------------------------------------------------+ - | post_stat_o3 | This task generates air quality forecast products including hourly | - | | -average and statistical products for O3 (e.g., daily 8-hour | - | | average maximum O3). | - +-----------------------+--------------------------------------------------------------------+ - | post_stat_pm25 | This task generates air quality forecast products including hourly | - | | -average and statistical products for PM2.5 (e.g., 24-hour average | - | | PM2.5). | - +-----------------------+--------------------------------------------------------------------+ - | bias_correction_o3 | This task applies a bias-correction technique (e.g., analog | - | | ensemble) to improve model raw forecast for O3 and generates the | - | | bias-corrected O3 products. | - +-----------------------+--------------------------------------------------------------------+ - | bias_correction_pm25 | This task applies a bias-correction technique (e.g., analog | - | | ensemble) to improve model raw forecast for PM2.5 and generates the| - | | bias-corrected PM2.5 products. | - +-----------------------+--------------------------------------------------------------------+ - diff --git a/docs/UsersGuide/source/Reference/Glossary.rst b/docs/UsersGuide/source/Reference/Glossary.rst index 13e1af277e..dc2010202a 100644 --- a/docs/UsersGuide/source/Reference/Glossary.rst +++ b/docs/UsersGuide/source/Reference/Glossary.rst @@ -102,6 +102,9 @@ Glossary GFS `Global Forecast System `_. The GFS is a National Centers for Environmental Prediction (:term:`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, land/soil, and sea ice) that work together to accurately depict weather conditions. + GOCART + NASA's Goddard Chemistry Aerosol Radiation and Transport (GOCART) model simulates the distribution of major tropospheric aerosol types, including sulfate, dust, organic carbon (OC), black carbon (BC), and sea salt aerosols. The UFS Weather Model integrates a prognostic aerosol component using GOCART. The code is publicly available on GitHub at https://github.com/GEOS-ESM/GOCART. + GRIB2 The second version of the World Meterological Organization's (WMO) standard for distributing gridded data. @@ -146,6 +149,9 @@ Glossary LBCs Lateral boundary conditions + MEGAN + The Model of Emissions of Gases and Aerosols from Nature (`MEGAN `) is a modeling system for estimating the emission of gases and aerosols from terrestrial ecosystems into the atmosphere. It has been integrated into a number of chemistry and transport models, including :ref:`NEXUS `. + MERRA2 The `Modern-Era Retrospective analysis for Research and Applications, Version 2 `__ provides satellite observation data back to 1980. According to NASA, "It was introduced to replace the original MERRA dataset because of the advances made in the assimilation system that enable assimilation of modern hyperspectral radiance and microwave observations, along with GPS-Radio Occultation datasets. It also uses NASA's ozone profile observations that began in late 2004. Additional advances in both the GEOS model and the GSI assimilation system are included in MERRA-2. Spatial resolution remains about the same (about 50 km in the latitudinal direction) as in MERRA." From 79e9dbd36c6f8d9c90a5b54ff403b7d084b423f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 1 Aug 2023 18:50:22 -0400 Subject: [PATCH 039/116] formatting fixes --- .../source/BuildingRunningTesting/AQM.rst | 91 ++++++++++--------- 1 file changed, 46 insertions(+), 45 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst index 5bb86427ad..9cd47983ac 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst @@ -160,7 +160,7 @@ Users may check experiment status from the experiment directory with either of t To see a description of each of the AQM workflow tasks, see :numref:`Section %s `. -.. _Success: +.. _AQMSuccess: Experiment Output -------------------- @@ -168,49 +168,50 @@ Experiment Output The workflow run is complete when all tasks display a "SUCCEEDED" message. If everything goes smoothly, users will eventually see a workflow status table similar to the following: .. code-block:: console - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION -============================================================================================ -202302170000 make_grid 47411619 SUCCEEDED 0 1 36.0 -202302170000 make_orog 47411728 SUCCEEDED 0 1 151.0 -202302170000 make_sfc_climo 47411801 SUCCEEDED 0 1 58.0 -202302170000 nexus_gfs_sfc 47411620 SUCCEEDED 0 1 37.0 -202302170000 nexus_emission_00 47411729 SUCCEEDED 0 1 251.0 -202302170000 nexus_emission_01 47411730 SUCCEEDED 0 1 250.0 -202302170000 nexus_emission_02 47411731 SUCCEEDED 0 1 250.0 -202302170000 nexus_post_split 47412034 SUCCEEDED 0 1 44.0 -202302170000 fire_emission 47411621 SUCCEEDED 0 1 19.0 -202302170000 point_source 47411732 SUCCEEDED 0 1 82.0 -202302170000 aqm_lbcs 47412961 SUCCEEDED 0 1 - -202302170000 get_extrn_ics 47411622 SUCCEEDED 0 1 314.0 -202302170000 get_extrn_lbcs 47411623 SUCCEEDED 0 1 0.0 -202302170000 make_ics_mem000 - SUCCEEDED 0 1 109.0 -202302170000 make_lbcs_mem000 47412035 SUCCEEDED 0 1 - -202302170000 run_fcst_mem000 - SUCCEEDED 0 1 - -202302170000 run_post_mem000_f000 - SUCCEEDED 0 1 - -202302170000 run_post_mem000_f001 - SUCCEEDED 0 1 - -202302170000 run_post_mem000_f002 - SUCCEEDED 0 1 - -... -202302170000 run_post_mem000_f006 - SUCCEEDED 0 1 - -============================================================================================ -202302170600 nexus_gfs_sfc 47411624 SUCCEEDED 0 1 44.0 -202302170600 nexus_emission_00 47411733 SUCCEEDED 0 1 323.0 -202302170600 nexus_emission_01 47411734 SUCCEEDED 0 1 323.0 -202302170600 nexus_emission_02 47411735 SUCCEEDED 0 1 329.0 -202302170600 nexus_post_split 47411736 SUCCEEDED 0 1 60.0 -202302170600 fire_emission 47411625 SUCCEEDED 0 1 18.0 -202302170600 point_source 47411736 SUCCEEDED 0 1 128.0 -202302170600 aqm_ics - SUCCEEDED 0 1 - -202302170600 aqm_lbcs - SUCCEEDED 0 1 - -202302170600 get_extrn_ics 47411626 SUCCEEDED 0 1 493.0 -202302170600 get_extrn_lbcs 47411627 SUCCEEDED 0 1 0.0 -202302170600 make_ics_mem000 47412037 SUCCEEDED 0 1 134.0 -202302170600 make_lbcs_mem000 - SUCCEEDED 0 1 - -202302170600 run_fcst_mem000 - SUCCEEDED 0 1 - -202302170600 run_post_mem000_f000 - SUCCEEDED 0 1 - -202302170600 run_post_mem000_f001 - SUCCEEDED 0 1 - -202302170600 run_post_mem000_f002 - SUCCEEDED 0 1 - -... -202302170600 run_post_mem000_f012 - SUCCEEDED 0 1 - + + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + ============================================================================================ + 202302170000 make_grid 47411619 SUCCEEDED 0 1 36.0 + 202302170000 make_orog 47411728 SUCCEEDED 0 1 151.0 + 202302170000 make_sfc_climo 47411801 SUCCEEDED 0 1 58.0 + 202302170000 nexus_gfs_sfc 47411620 SUCCEEDED 0 1 37.0 + 202302170000 nexus_emission_00 47411729 SUCCEEDED 0 1 251.0 + 202302170000 nexus_emission_01 47411730 SUCCEEDED 0 1 250.0 + 202302170000 nexus_emission_02 47411731 SUCCEEDED 0 1 250.0 + 202302170000 nexus_post_split 47412034 SUCCEEDED 0 1 44.0 + 202302170000 fire_emission 47411621 SUCCEEDED 0 1 19.0 + 202302170000 point_source 47411732 SUCCEEDED 0 1 82.0 + 202302170000 aqm_lbcs 47412961 SUCCEEDED 0 1 - + 202302170000 get_extrn_ics 47411622 SUCCEEDED 0 1 314.0 + 202302170000 get_extrn_lbcs 47411623 SUCCEEDED 0 1 0.0 + 202302170000 make_ics_mem000 - SUCCEEDED 0 1 109.0 + 202302170000 make_lbcs_mem000 47412035 SUCCEEDED 0 1 - + 202302170000 run_fcst_mem000 - SUCCEEDED 0 1 - + 202302170000 run_post_mem000_f000 - SUCCEEDED 0 1 - + 202302170000 run_post_mem000_f001 - SUCCEEDED 0 1 - + 202302170000 run_post_mem000_f002 - SUCCEEDED 0 1 - + ... + 202302170000 run_post_mem000_f006 - SUCCEEDED 0 1 - + ============================================================================================ + 202302170600 nexus_gfs_sfc 47411624 SUCCEEDED 0 1 44.0 + 202302170600 nexus_emission_00 47411733 SUCCEEDED 0 1 323.0 + 202302170600 nexus_emission_01 47411734 SUCCEEDED 0 1 323.0 + 202302170600 nexus_emission_02 47411735 SUCCEEDED 0 1 329.0 + 202302170600 nexus_post_split 47411736 SUCCEEDED 0 1 60.0 + 202302170600 fire_emission 47411625 SUCCEEDED 0 1 18.0 + 202302170600 point_source 47411736 SUCCEEDED 0 1 128.0 + 202302170600 aqm_ics - SUCCEEDED 0 1 - + 202302170600 aqm_lbcs - SUCCEEDED 0 1 - + 202302170600 get_extrn_ics 47411626 SUCCEEDED 0 1 493.0 + 202302170600 get_extrn_lbcs 47411627 SUCCEEDED 0 1 0.0 + 202302170600 make_ics_mem000 47412037 SUCCEEDED 0 1 134.0 + 202302170600 make_lbcs_mem000 - SUCCEEDED 0 1 - + 202302170600 run_fcst_mem000 - SUCCEEDED 0 1 - + 202302170600 run_post_mem000_f000 - SUCCEEDED 0 1 - + 202302170600 run_post_mem000_f001 - SUCCEEDED 0 1 - + 202302170600 run_post_mem000_f002 - SUCCEEDED 0 1 - + ... + 202302170600 run_post_mem000_f012 - SUCCEEDED 0 1 - .. COMMENT: Fix table above by adding job numbers and duration!!! @@ -222,7 +223,7 @@ Additional Tasks for AQM Structure of SRW-AQM Workflow -------------------------------- -:numref:`Figure %s ` illustrates the full non-:term:`DA` SRW-AQM workflow using a flowchart. Compared to the uncoupled (atmosphere-only) workflow (see :numref:`Table %s `), SRW-AQM has additional tasks for pre- and post-processing. For pre-processing, multiple emissions data such as NEXUS, fire, and point-source emissions are retrieved or created for air quality modeling. Moreover, the chemical initial conditions (ICs) are extracted from the restart files of the previous cycle and added to the existing IC files. The chemical lateral boundary conditions (LBCs) and the GEFS aerosol data are also added to the existing LBC files. For post-processing, air quality forecast products for ozone (O3) and 2.5-micron particulate matter (PM2.5) are generated, and the bias-correction technique is applied to improve the accuracy of the results. +:numref:`Figure %s ` illustrates the full non-:term:`DA ` SRW-AQM workflow using a flowchart. Compared to the uncoupled (atmosphere-only) workflow (see :numref:`Table %s `), SRW-AQM has additional tasks for pre- and post-processing. For pre-processing, multiple emissions data such as NEXUS, fire, and point-source emissions are retrieved or created for air quality modeling. Moreover, the chemical initial conditions (ICs) are extracted from the restart files of the previous cycle and added to the existing IC files. The chemical lateral boundary conditions (LBCs) and the GEFS aerosol data are also added to the existing LBC files. For post-processing, air quality forecast products for ozone (O3) and 2.5-micron particulate matter (PM2.5) are generated, and the bias-correction technique is applied to improve the accuracy of the results. .. _FlowProcAQM: From 0b9547a90ba486d5ec4d3e768f4e01d54abcc42e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 1 Aug 2023 19:58:15 -0400 Subject: [PATCH 040/116] minor fixes --- .../source/BuildingRunningTesting/AQM.rst | 18 +++++++++--------- docs/UsersGuide/source/Reference/Glossary.rst | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst index 9cd47983ac..5be6e9922d 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst @@ -62,9 +62,9 @@ If the SRW-AQM builds correctly, users should see the standard executables liste * - Executable - Description * - decomp-ptemis-mpi - - Splits the point-source emission file into subdomain based on runtime configure setting. + - Splits the point-source emission file into subdomain based on runtime configure setting * - gefs2lbc_para - - Interpolates :term:`GOCART` concentration to be lateral boundary condition for regional air quality model and outputs a layer result for checking purpose. + - Interpolates :term:`GOCART` concentration to be lateral boundary condition for regional air quality model and outputs a layer result for checking purpose * - nexus - Runs the NOAA Emission and eXchange Unified System (:ref:`NEXUS `) emissions processing system @@ -121,7 +121,7 @@ Users may also wish to change :term:`cron`-related parameters in ``config.yaml`` This means that cron will submit the launch script every 3 minutes. Users may choose not to submit using cron or to submit at a different frequency. Note that users should create a crontab by running ``crontab -e`` the first time they use cron. -When using the basic ``config.aqm.community.yaml`` experiment, the AQM pre-processing tasks are automatically turned on by adding ``"parm/wflow/aqm_prep.yaml"`` to the list of workflow files in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml`` (see :numref:`Section %s ` for task descriptions). To turn on AQM post-processing tasks in the workflow, include ``"parm/wflow/aqm_post.yaml"`` in the ``rocoto: tasks: taskgroups:`` section, too (see :numref:`Section %s ` for task descriptions). +When using the basic ``config.aqm.community.yaml`` experiment, the AQM pre-processing tasks are automatically turned because ``"parm/wflow/aqm_prep.yaml"`` appears in the list of workflow files in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml`` (see :numref:`Section %s ` for task descriptions). To turn on AQM post-processing tasks in the workflow, include ``"parm/wflow/aqm_post.yaml"`` in the ``rocoto: tasks: taskgroups:`` section, too (see :numref:`Section %s ` for task descriptions). .. attention:: @@ -230,13 +230,13 @@ Structure of SRW-AQM Workflow .. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW-AQM_workflow.png :alt: Flowchart of the SRW-AQM tasks. - *Workflow structure of SRW-AQM (non-DA)* + *Workflow Structure of SRW-AQM (non-DA)* Pre-processing Tasks of SRW-AQM ------------------------------------ -The pre-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. +The pre-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. They are defined in the ``parm/wflow/aqm_prep.yaml`` file. .. _TasksPrepAQM: @@ -249,9 +249,9 @@ The pre-processing tasks for air quality modeling (AQM) are shown in :numref:`Ta * - nexus_gfs_sfc - Retrieves the GFS surface files from the previous cycle in near real-time (NRT) or from the current cycle in retrospective cases. The surface radiation, soil moisture, and temperature fields are needed to predict the :term:`MEGAN` biogenics emissions within the ``nexus_emission_##`` task. * - nexus_emission_## - - Prepares the run directory with gridded emission inputs, runs :ref:`NEXUS` to create model-ready emissions for the given simulation day, and post processes NEXUS output to make it more readable. The task will also split the task into ``##`` jobs set by the user in ``config.yaml`` using ``NUM_SPLIT_NEXUS`` variable. + - Prepares the run directory with gridded emissions inputs, runs the :ref:`NEXUS` to create model-ready emissions for the given simulation day, and post processes NEXUS output to make it more readable. The task will also split the task into ``##`` jobs set by the user in ``config.yaml`` using the ``NUM_SPLIT_NEXUS`` variable. * - nexus_post_split - - Concatenates the NEXUS emission information into a single netCDF file (needed for the forecast) if NEXUS was split into multiple jobs. + - Concatenates the NEXUS emissions information into a single netCDF file (needed for the forecast) if NEXUS was split into multiple jobs using the ``NUM_SPLIT_NEXUS`` variable. * - fire_emission - Converts both satellite-retrieved gas and aerosol species emissions (RAVE) from mass (kg) to emissions rates (kg/m2/s) and creates 3-day hourly model-ready fire emissions input files. * - point_source @@ -259,12 +259,12 @@ The pre-processing tasks for air quality modeling (AQM) are shown in :numref:`Ta * - aqm_ics - Creates a chemical initial conditions file by using the previous cycle restart files. * - aqm_lbcs - - Adds the chemical lateral boundary conditions (LBC) to the meteorological lateral boundary conditions to form the full set of ready-to-input LBCs for the simulation. ``aqm_lbcs`` includes two sub-tasks: addition of the gaseous species LBCs and addition of dynamic aerosol LBCs. The former adds static gaseous LBCs using monthly mean global data. The latter is the parallel job, which extracts the GEFS-Aerosol Model's output along the regional domain and performs the species conversion from GOCART aerosols to CMAQ aerosols. + - Adds the chemical lateral boundary conditions (LBCs) to the meteorological LBCs to form the full set of ready-to-input LBCs for the simulation. This task includes two sub-tasks: (1) addition of the gaseous species LBCs and (2) addition of dynamic aerosol LBCs. The former adds static gaseous LBCs using monthly mean global data. The latter is the parallel job, which extracts the GEFS-Aerosol Model's output along the regional domain and performs the species conversion from :term:`GOCART` aerosols to CMAQ aerosols. Post-processing Tasks of SRW-AQM ------------------------------------ -The post-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. Since the module required to run these tasks is available only on WCOSS2, these tasks should not be defined in the configuration file ``config.yaml`` on other platforms. +The post-processing tasks for air quality modeling (AQM) are shown in :numref:`Table %s `. They are defined in the ``parm/wflow/aqm_post.yaml`` file. Since the module required to run these tasks is available only on WCOSS2, ``aqm_post.yaml`` should not be added to the ``rocoto: tasks: taskgroups:`` section of the configuration file ``config.yaml`` on other platforms. .. _TasksPostAQM: diff --git a/docs/UsersGuide/source/Reference/Glossary.rst b/docs/UsersGuide/source/Reference/Glossary.rst index dc2010202a..9d25a9b1cb 100644 --- a/docs/UsersGuide/source/Reference/Glossary.rst +++ b/docs/UsersGuide/source/Reference/Glossary.rst @@ -150,7 +150,7 @@ Glossary Lateral boundary conditions MEGAN - The Model of Emissions of Gases and Aerosols from Nature (`MEGAN `) is a modeling system for estimating the emission of gases and aerosols from terrestrial ecosystems into the atmosphere. It has been integrated into a number of chemistry and transport models, including :ref:`NEXUS `. + The Model of Emissions of Gases and Aerosols from Nature (`MEGAN `__) is a modeling system for estimating the emission of gases and aerosols from terrestrial ecosystems into the atmosphere. It has been integrated into a number of chemistry and transport models, including :ref:`NEXUS `. MERRA2 The `Modern-Era Retrospective analysis for Research and Applications, Version 2 `__ provides satellite observation data back to 1980. According to NASA, "It was introduced to replace the original MERRA dataset because of the advances made in the assimilation system that enable assimilation of modern hyperspectral radiance and microwave observations, along with GPS-Radio Occultation datasets. It also uses NASA's ozone profile observations that began in late 2004. Additional advances in both the GEOS model and the GSI assimilation system are included in MERRA-2. Spatial resolution remains about the same (about 50 km in the latitudinal direction) as in MERRA." From 4b323def149ea124cbb4266950402e569d03a13a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 2 Aug 2023 17:34:16 -0400 Subject: [PATCH 041/116] add AQM expt data info & wflow SUCCESS info --- .../source/BuildingRunningTesting/AQM.rst | 71 +++++++++++-------- docs/UsersGuide/source/Reference/Glossary.rst | 2 +- 2 files changed, 42 insertions(+), 31 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst index 5be6e9922d..846f112474 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst @@ -108,8 +108,21 @@ Users may prefer to copy the ``config.aqm.nco.realtime.yaml`` for a default "nco Users will need to change the ``MACHINE`` and ``ACCOUNT`` variables in ``config.yaml`` to match their system. They may also wish to adjust other experiment settings. For more information on each task and variable, see :numref:`Section %s `. -.. COMMENT: Get data locations!!! The NODD bucket below is empty. - Users can find the data required for the community experiment in the `NOAA Global Forecast System Data Bucket `__. +The community AQM configuration assumes that users have :term:`HPSS` access and attempts to download the data from HPSS. However, if users have the data on their system already, they may prefer to add the following lines to the ``task_get_extrn_*:`` to their ``config.yaml`` file, adjusting the file path to point to the data location: + +.. code-block:: console + + task_get_extrn_ics: + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/data + task_get_extrn_lbcs: + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_SOURCE_BASEDIR_LBCS: "/path/to/UFS_SRW_App/develop/input_model_data///" + +On Hera, users can find :term:`ICs/LBCs` at ``/scratch2/NCEPDEV/naqfc/RRFS_CMAQ/GFS_DATA/gfs.20230217/{hh}/atmos``. + +.. COMMENT: Get data locations!!! Add data to the SRW NODD bucket. + Users can find the data required for the community experiment in the `NOAA Global Forecast System Data Bucket `__. --> bucket is empty. Users may also wish to change :term:`cron`-related parameters in ``config.yaml``. In the ``config.aqm.community.yaml`` file, which was copied into ``config.yaml``, cron is used for automatic submission and resubmission of the workflow: @@ -181,39 +194,37 @@ The workflow run is complete when all tasks display a "SUCCEEDED" message. If ev 202302170000 nexus_post_split 47412034 SUCCEEDED 0 1 44.0 202302170000 fire_emission 47411621 SUCCEEDED 0 1 19.0 202302170000 point_source 47411732 SUCCEEDED 0 1 82.0 - 202302170000 aqm_lbcs 47412961 SUCCEEDED 0 1 - + 202302170000 aqm_lbcs 47412961 SUCCEEDED 0 1 159.0 202302170000 get_extrn_ics 47411622 SUCCEEDED 0 1 314.0 202302170000 get_extrn_lbcs 47411623 SUCCEEDED 0 1 0.0 - 202302170000 make_ics_mem000 - SUCCEEDED 0 1 109.0 - 202302170000 make_lbcs_mem000 47412035 SUCCEEDED 0 1 - - 202302170000 run_fcst_mem000 - SUCCEEDED 0 1 - - 202302170000 run_post_mem000_f000 - SUCCEEDED 0 1 - - 202302170000 run_post_mem000_f001 - SUCCEEDED 0 1 - - 202302170000 run_post_mem000_f002 - SUCCEEDED 0 1 - + 202302170000 make_ics_mem000 47659593 SUCCEEDED 0 1 126.0 + 202302170000 make_lbcs_mem000 47659594 SUCCEEDED 0 1 113.0 + 202302170000 run_fcst_mem000 47659742 SUCCEEDED 0 1 763.0 + 202302170000 run_post_mem000_f000 47659910 SUCCEEDED 0 1 30.0 + 202302170000 run_post_mem000_f001 47660029 SUCCEEDED 0 1 30.0 + 202302170000 run_post_mem000_f002 47660030 SUCCEEDED 0 1 31.0 ... - 202302170000 run_post_mem000_f006 - SUCCEEDED 0 1 - + 202302170000 run_post_mem000_f006 47660110 SUCCEEDED 0 1 29.0 ============================================================================================ - 202302170600 nexus_gfs_sfc 47411624 SUCCEEDED 0 1 44.0 - 202302170600 nexus_emission_00 47411733 SUCCEEDED 0 1 323.0 - 202302170600 nexus_emission_01 47411734 SUCCEEDED 0 1 323.0 - 202302170600 nexus_emission_02 47411735 SUCCEEDED 0 1 329.0 - 202302170600 nexus_post_split 47411736 SUCCEEDED 0 1 60.0 - 202302170600 fire_emission 47411625 SUCCEEDED 0 1 18.0 - 202302170600 point_source 47411736 SUCCEEDED 0 1 128.0 - 202302170600 aqm_ics - SUCCEEDED 0 1 - - 202302170600 aqm_lbcs - SUCCEEDED 0 1 - - 202302170600 get_extrn_ics 47411626 SUCCEEDED 0 1 493.0 - 202302170600 get_extrn_lbcs 47411627 SUCCEEDED 0 1 0.0 - 202302170600 make_ics_mem000 47412037 SUCCEEDED 0 1 134.0 - 202302170600 make_lbcs_mem000 - SUCCEEDED 0 1 - - 202302170600 run_fcst_mem000 - SUCCEEDED 0 1 - - 202302170600 run_post_mem000_f000 - SUCCEEDED 0 1 - - 202302170600 run_post_mem000_f001 - SUCCEEDED 0 1 - - 202302170600 run_post_mem000_f002 - SUCCEEDED 0 1 - + 202302170600 nexus_gfs_sfc 47659421 SUCCEEDED 0 1 44.0 + 202302170600 nexus_emission_00 47659475 SUCCEEDED 0 1 323.0 + 202302170600 nexus_emission_01 47659476 SUCCEEDED 0 1 323.0 + 202302170600 nexus_emission_02 47659477 SUCCEEDED 0 1 329.0 + 202302170600 nexus_post_split 47659595 SUCCEEDED 0 1 60.0 + 202302170600 fire_emission 47659422 SUCCEEDED 0 1 18.0 + 202302170600 point_source 47659478 SUCCEEDED 0 1 128.0 + 202302170600 aqm_ics 47659597 SUCCEEDED 0 1 159.0 + 202302170600 aqm_lbcs 47659598 SUCCEEDED 0 1 158.0 + 202302170600 get_extrn_ics 47659423 SUCCEEDED 0 1 493.0 + 202302170600 get_extrn_lbcs 47659424 SUCCEEDED 0 1 536.0 + 202302170600 make_ics_mem000 47659594 SUCCEEDED 0 1 134.0 + 202302170600 make_lbcs_mem000 47659596 SUCCEEDED 0 1 112.0 + 202302170600 run_fcst_mem000 47659812 SUCCEEDED 0 1 1429.0 + 202302170600 run_post_mem000_f000 47659998 SUCCEEDED 0 1 30.0 + 202302170600 run_post_mem000_f001 47660042 SUCCEEDED 0 1 31.0 + 202302170600 run_post_mem000_f002 47660043 SUCCEEDED 0 1 29.0 ... - 202302170600 run_post_mem000_f012 - SUCCEEDED 0 1 - - -.. COMMENT: Fix table above by adding job numbers and duration!!! + 202302170600 run_post_mem000_f012 47660134 SUCCEEDED 0 1 30.0 .. _AQM-more-tasks: diff --git a/docs/UsersGuide/source/Reference/Glossary.rst b/docs/UsersGuide/source/Reference/Glossary.rst index 9d25a9b1cb..48215b2eef 100644 --- a/docs/UsersGuide/source/Reference/Glossary.rst +++ b/docs/UsersGuide/source/Reference/Glossary.rst @@ -129,7 +129,7 @@ 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/LBCs + ICs/LBCs Initial conditions/lateral boundary conditions ICs From f004d1f2539177276ff932eff52f450d878ccff9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 2 Aug 2023 17:34:38 -0400 Subject: [PATCH 042/116] minor WE2E updates --- .../BuildingRunningTesting/WE2Etests.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst index 8455e3d0ae..22b0fe8ff9 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst @@ -3,7 +3,7 @@ ======================= Testing the SRW App ======================= -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 from start to finish. The purpose of these tests is to ensure that new changes to the App do not break existing functionality and capabilities. +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 from start to finish. The purpose of these tests is to ensure that new changes to the App do not break existing functionality and capabilities. However, these WE2E tests also provide users with additional sample cases and data beyond the basic ``config.community.yaml`` case. 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 @@ -11,11 +11,9 @@ not test the scientific integrity of the results (e.g., they do not check that v 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 (:term:`J-jobs`, :term:`ex-scripts`), and other auxiliary scripts to ensure that these scripts function correctly. Tested 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. Currently, it is up to the external repositories that the App clones (:numref:`Section %s `) to check that changes to those repositories 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.) - -WE2E tests are grouped into two categories that are of interest to code developers: ``fundamental`` and ``comprehensive`` tests. "Fundamental" tests are a lightweight but wide-reaching set of tests designed to function as a cheap "`smoke test `__ for changes to the UFS SRW App. The fundamental suite of test runs common combinations of workflow tasks, physical domains, input data, physics suites, etc. -The comprehensive suite of tests covers a broader range of combinations of capabilities, configurations, and components, ideally including all capabilities that *can* be run on a given platform. Because some capabilities are not available on all platforms (*e.g.*, retrieving data directly from NOAA HPSS), the suite of comprehensive tests varies from machine to machine. -The list of fundamental and comprehensive tests can be viewed in the ``ufs-srweather-app/tests/WE2E/machine_suites/`` directory, and are described in more detail in :doc:`this table `. +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 repositories 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.) WE2E tests are grouped into two categories that are of interest to code developers: ``fundamental`` and ``comprehensive`` tests. "Fundamental" tests are a lightweight but wide-reaching set of tests designed to function as a cheap "`smoke test `__" for changes to the UFS SRW App. The fundamental suite of tests runs common combinations of workflow tasks, physical domains, input data, physics suites, etc. +The comprehensive suite of tests covers a broader range of combinations of capabilities, configurations, and components, ideally including all capabilities that *can* be run on a given platform. Because some capabilities are not available on all platforms (e.g., retrieving data directly from NOAA HPSS), the suite of comprehensive tests varies from machine to machine. +The list of fundamental and comprehensive tests can be viewed in the ``ufs-srweather-app/tests/WE2E/machine_suites/`` directory and are described in more detail in :doc:`this table <../tables/Tests>`. .. note:: @@ -41,11 +39,11 @@ For convenience, the WE2E tests are currently grouped into the following categor * ``wflow_features`` This category of tests ensures that the workflow completes successfully with particular features/capabilities activated. -Some tests are duplicated among the above categories via symbolic links, both for legacy reasons (when tests for different capabilities were consolidated) and for convenience when a user would like to run all tests for a specific category (*e.g.* verification tests). +Some tests are duplicated among the above categories via symbolic links, both for legacy reasons (when tests for different capabilities were consolidated) and for convenience when a user would like to run all tests for a specific category (e.g., verification tests). -The script to run the WE2E tests is named ``run_WE2E_tests.py`` and is located in the directory ``ufs-srweather-app/tests/WE2E``. Each WE2E test has an associated configuration file named ``config.${test_name}.yaml``, where ``${test_name}`` is the name of the corresponding test. These configuration files are subsets of the full range of ``config.yaml`` experiment configuration options. (See :numref:`Chapter %s ` for all configurable options and :numref:`Section %s ` for information on configuring ``config.yaml``.) For each test, the ``run_WE2E_tests.py`` script reads in the test configuration file and generates from it a complete ``config.yaml`` file. It then calls the ``generate_FV3LAM_wflow()`` function, which in turn reads in ``config.yaml`` 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.yaml`` for each test is placed in its experiment directory. +The script to run the WE2E tests is named ``run_WE2E_tests.py`` and is located in the directory ``ufs-srweather-app/tests/WE2E``. Each WE2E test has an associated configuration file named ``config.${test_name}.yaml``, where ``${test_name}`` is the name of the corresponding test. These configuration files are subsets of the full range of ``config.yaml`` experiment configuration options. (See :numref:`Section %s ` for all configurable options and :numref:`Section %s ` for information on configuring ``config.yaml``.) For each test, the ``run_WE2E_tests.py`` script reads in the test configuration file and generates from it a complete ``config.yaml`` file. It then calls the ``generate_FV3LAM_wflow()`` function, which in turn reads in ``config.yaml`` 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.yaml`` for each test is placed in its experiment directory. -As with any other experiment within the App, the +As with any other experiment within the SRW App, the Python modules required for experiment generation must be loaded before ``run_WE2E_tests.py`` can be called. See :numref:`Section %s ` for information on loading the Python environment on supported platforms. Note also that ``run_WE2E_tests.py`` assumes that all of @@ -53,7 +51,7 @@ the executables have been built (see :numref:`Section %s `). I .. note:: - The full list of WE2E tests is extensive and some larger, high-resolution tests are computationally expensive. Estimates of walltime and core-hour cost for each test are provided in :doc:`this table `. + The full list of WE2E tests is extensive and some larger, high-resolution tests are computationally expensive. Estimates of walltime and core-hour cost for each test are provided in :doc:`this table <../tables/Tests>`. Running the WE2E Tests ================================ From 2fe0f990d12659ea3582a7c2016b4f21fed45d2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 3 Aug 2023 17:37:20 -0400 Subject: [PATCH 043/116] update testing ch --- .../BuildingRunningTesting/WE2Etests.rst | 148 ++++++++++-------- 1 file changed, 84 insertions(+), 64 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst index 22b0fe8ff9..f50c154a6b 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst @@ -11,7 +11,12 @@ not test the scientific integrity of the results (e.g., they do not check that v 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 (:term:`J-jobs`, :term:`ex-scripts`), and other auxiliary scripts to ensure that these scripts function correctly. Tested 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. Currently, it is up to the external repositories that the App clones (:numref:`Section %s `) to check that changes to those repositories 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.) WE2E tests are grouped into two categories that are of interest to code developers: ``fundamental`` and ``comprehensive`` tests. "Fundamental" tests are a lightweight but wide-reaching set of tests designed to function as a cheap "`smoke test `__" for changes to the UFS SRW App. The fundamental suite of tests runs common combinations of workflow tasks, physical domains, input data, physics suites, etc. +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 repositories 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.) + +WE2E Test Categories +====================== + +WE2E tests are grouped into two categories that are of interest to code developers: ``fundamental`` and ``comprehensive`` tests. "Fundamental" tests are a lightweight but wide-reaching set of tests designed to function as a cheap "`smoke test `__" for changes to the UFS SRW App. The fundamental suite of tests runs common combinations of workflow tasks, physical domains, input data, physics suites, etc. The comprehensive suite of tests covers a broader range of combinations of capabilities, configurations, and components, ideally including all capabilities that *can* be run on a given platform. Because some capabilities are not available on all platforms (e.g., retrieving data directly from NOAA HPSS), the suite of comprehensive tests varies from machine to machine. The list of fundamental and comprehensive tests can be viewed in the ``ufs-srweather-app/tests/WE2E/machine_suites/`` directory and are described in more detail in :doc:`this table <../tables/Tests>`. @@ -41,29 +46,69 @@ For convenience, the WE2E tests are currently grouped into the following categor Some tests are duplicated among the above categories via symbolic links, both for legacy reasons (when tests for different capabilities were consolidated) and for convenience when a user would like to run all tests for a specific category (e.g., verification tests). -The script to run the WE2E tests is named ``run_WE2E_tests.py`` and is located in the directory ``ufs-srweather-app/tests/WE2E``. Each WE2E test has an associated configuration file named ``config.${test_name}.yaml``, where ``${test_name}`` is the name of the corresponding test. These configuration files are subsets of the full range of ``config.yaml`` experiment configuration options. (See :numref:`Section %s ` for all configurable options and :numref:`Section %s ` for information on configuring ``config.yaml``.) For each test, the ``run_WE2E_tests.py`` script reads in the test configuration file and generates from it a complete ``config.yaml`` file. It then calls the ``generate_FV3LAM_wflow()`` function, which in turn reads in ``config.yaml`` 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.yaml`` for each test is placed in its experiment directory. +Running the WE2E Tests +================================ + +The Test Script (``run_WE2E_tests.py``) +----------------------------------------- -As with any other experiment within the SRW App, the -Python modules required for experiment generation must be loaded before ``run_WE2E_tests.py`` -can be called. See :numref:`Section %s ` for information on loading the Python -environment on supported platforms. Note also that ``run_WE2E_tests.py`` assumes that all of -the executables have been built (see :numref:`Section %s `). If they have not, then ``run_WE2E_tests.py`` will still generate the experiment directories, but the workflows will fail. +The script to run the WE2E tests is named ``run_WE2E_tests.py`` and is located in the directory ``ufs-srweather-app/tests/WE2E``. Each WE2E test has an associated configuration file named ``config.${test_name}.yaml``, where ``${test_name}`` is the name of the corresponding test. These configuration files are subsets of the full range of ``config.yaml`` experiment configuration options. (See :numref:`Section %s ` for all configurable options and :numref:`Section %s ` for information on configuring ``config.yaml``.) For each test, the ``run_WE2E_tests.py`` script reads in the test configuration file and generates from it a complete ``config.yaml`` file. It then calls the ``generate_FV3LAM_wflow()`` function, which in turn reads in ``config.yaml`` 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.yaml`` for each test is placed in its experiment directory. .. note:: - The full list of WE2E tests is extensive and some larger, high-resolution tests are computationally expensive. Estimates of walltime and core-hour cost for each test are provided in :doc:`this table <../tables/Tests>`. + The full list of WE2E tests is extensive, and some larger, high-resolution tests are computationally expensive. Estimates of walltime and core-hour cost for each test are provided in :doc:`this table <../tables/Tests>`. -Running the WE2E Tests -================================ +Using the Test Script +---------------------- + +.. attention:: + + These instructions assume that the user has already built the SRW App (as described in :numref:`Section %s `) and loaded the appropriate python environment (as described in :numref:`Section %s `). + +The test script has three required arguments: machine, account, and tests. + + * Users must indicate which machine they are on using the ``--machine`` or ``-m`` option. See ``ush/machine`` or :numref:`Section %s ` for valid values. + * Users must submit a valid account name using the ``--account`` or ``-a`` option to run submitted jobs. On systems where an account name is not required, users may simply use ``-a none``. + * Users must specify the set of tests to run using the ``--tests`` or ``-t`` option. Users may pass (in order of priority): + + #. The name of a single test or list of tests to the test script. + #. A test suite name (e.g., "fundamental", "comprehensive", "coverage", or "all"). + #. The name of a text file (full or relative path), such as ``my_tests.txt``, which contains a list of the WE2E tests to run (one per line). + +Users may run ``./run_WE2E_tests.py -h`` for additional (optional) usage instructions. :numref:`Section %s ` provides examples using some of the most common optional arguments. + +Simple Examples +^^^^^^^^^^^^^^^^^ + +.. attention:: + + * Users will need to adjust the machine name and account in these examples to run tests successfully. + * These commands assume that the user is working from the ``WE2E`` directory (``ufs-srweather-app/tests/WE2E/``). + +To run the ``custom_ESGgrid`` and ``pregen_grid_orog_sfc_climo`` tests on Jet, users could run: + +.. code-block:: console + + ./run_WE2E_tests.py -t custom_ESGgrid pregen_grid_orog_sfc_climo -m jet -a hfv3gfs + +Alternatively, to run the entire suite of fundamental tests on Hera, users might run: -Users may specify the set of tests to run in one of three ways. First, users can pass the name of a single test or list of tests to the script. Secondly, they can pass an option to run the ``fundamental`` or ``comprehensive`` suite of tests. Finally, users can create a text file, such as ``my_tests.txt``, which contains a list of the WE2E tests to run (one per line). Any one of these options can be passed to the ``run_WE2E_tests.py`` script via the ``--tests`` or ``-t`` option. +.. code-block:: console + + ./run_WE2E_tests.py -t fundamental -m hera -a nems -For example, to run the tests ``custom_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 commands from the ``WE2E`` working directory (``ufs-srweather-app/tests/WE2E/``): +To run the tests ``custom_ESGgrid`` and ``grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16`` on NOAA Cloud, users would enter the following commands: .. code-block:: console echo "custom_ESGgrid" > my_tests.txt echo "grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16" >> my_tests.txt + ./run_WE2E_tests.py -t my_tests.txt -m noaacloud -a none + +By default, the experiment directory for a WE2E test has the same name as the test itself, and it is created in ``${HOMEdir}/../expt_dirs``, where ``HOMEdir`` is the top-level directory for the ``ufs-srweather-app`` repository (usually set to something like ``/path/to/ufs-srweather-app``). Thus, the ``custom_ESGgrid`` experiment directory would be located in ``${HOMEdir}/../expt_dirs/custom_ESGgrid``. + +Workflow Information +^^^^^^^^^^^^^^^^^^^^^^ For each specified test, ``run_WE2E_tests.py`` will generate a new experiment directory and, by default, launch a second function ``monitor_jobs()`` that will continuously monitor active jobs, submit new jobs, and track the success or failure status of the experiment in a ``.yaml`` file. Finally, when all jobs have finished running (successfully or not), the function ``print_WE2E_summary()`` will print a summary of the jobs to screen, including the job's success or failure, timing information, and (if on an appropriately configured platform) the number of core hours used. An example run would look like this: @@ -75,12 +120,12 @@ For each specified test, ``run_WE2E_tests.py`` will generate a new experiment di /user/home/ufs-srweather-app/tests/WE2E/test_configs/wflow_features/config.custom_ESGgrid.yaml /user/home/ufs-srweather-app/tests/WE2E/test_configs/grids_extrn_mdls_suites_community/config.grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16.yaml Calling workflow generation function for test custom_ESGgrid - + ... Workflow for test custom_ESGgrid successfully generated in /user/home/expt_dirs/custom_ESGgrid Calling workflow generation function for test grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - + ... Workflow for test grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 successfully generated in /user/home/expt_dirs/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 @@ -111,14 +156,10 @@ For each specified test, ``run_WE2E_tests.py`` will generate a new experiment di All experiments are complete Summary of results available in WE2E_tests_20230418174042.yaml - -.. note:: - - These examples assume that the user has already built the SRW App and loaded the appropriate python environment as described in :numref:`Section %s `. -As the script runs, detailed debug output is written to the file ``log.run_WE2E_tests``. This can be useful for debugging if something goes wrong. You can also use the ``-d`` flag to print all this output to screen during the run, but this can get quite cluttered. +As the script runs, detailed debug output is written to the file ``log.run_WE2E_tests``. This can be useful for debugging if something goes wrong. Adding the ``-d`` flag will print all this output to the screen during the run, but this can get quite cluttered. -The final job summary is written by the ``print_WE2E_summary()``; this prints a short summary of experiments to screen, and prints a more detailed summary of all jobs for all experiments in the indicated ``.txt`` file. +The progress of ``monitor_jobs()`` is tracked in a file ``WE2E_tests_{datetime}.yaml``, where {datetime} is the date and time (in ``yyyymmddhhmmss`` format) that the file was created. The final job summary is written by the ``print_WE2E_summary()``; this prints a short summary of experiments to the screen and prints a more detailed summary of all jobs for all experiments in the indicated ``.txt`` file. .. code-block:: console @@ -180,7 +221,7 @@ The final job summary is written by the ``print_WE2E_summary()``; this prints a Total COMPLETE 15.52 -One might have noticed the line during the experiment run that reads "Use ctrl-c to pause job submission/monitoring". The ``monitor_jobs()`` function (called automatically after all experiments are generated) is designed to be easily paused and re-started if necessary. If you wish to stop actively submitting jobs, simply quitting the script using "ctrl-c" will stop the function, and give a short message on how to continue the experiment. +One might have noticed the line during the experiment run that reads "Use ctrl-c to pause job submission/monitoring". The ``monitor_jobs()`` function (called automatically after all experiments are generated) is designed to be easily paused and re-started if necessary. To stop actively submitting jobs, simply quit the script using "ctrl-c" to stop the function, and a short message will appear explaining how to continue the experiment: .. code-block:: console @@ -193,73 +234,52 @@ One might have noticed the line during the experiment run that reads "Use ctrl-c ./monitor_jobs.py -y=WE2E_tests_20230418174042.yaml -p=1 -The full list of options for any of these scripts can be found by using the ``-h`` flag. The examples below demonstrate several of the more common options for ``run_WE2E_tests.py``. +.. _Opt-Args: -#. To run the tests listed in ``my_tests.txt`` on Hera and charge the computational - resources used to the "rtrr" account: +Additional Sample Cases With Optional Arguments +-------------------------------------------------- - .. code-block:: +The full list of options for ``run_WE2E_tests.py`` can be found using the ``-h`` flag. The examples below demonstrate several of the more common options for ``run_WE2E_tests.py``. - ./run_WE2E_tests.py --tests=my_tests.txt --machine=hera --account=rtrr - This will create the experiment subdirectories for the two sample WE2E tests in the directory ``${HOMEdir}/../expt_dirs``, where ``HOMEdir`` is the top-level directory for the ufs-srweather-app repository (usually set to something like ``/path/to/ufs-srweather-app``). Thus, the following two experiment directories will be created: +#. This first example will run the fundamental suite of tests on Orion, charging computational resources to the "gsd-fv3" account, and placing all the experiment directories into a directory named ``test_set_01``: .. code-block:: - ${HOMEdir}/../expt_dirs/custom_ESGgrid - ${HOMEdir}/../expt_dirs/grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16 - - Once these experiment directories are created, the script will call the ``monitor_jobs()`` function. This function runs ``rocotorun`` in the background to monitor the status of jobs in each experiment directory, tracking the status of jobs as they run and complete, and submitting new jobs when they are ready. The progress of ``monitor_jobs()`` is tracked in a file ``WE2E_tests_{datetime}.yaml``, where {datetime} is the date and time (in ``yyyymmddhhmmss`` format) that the file was created. + ./run_WE2E_tests.py -t fundamental -m orion -a gsd-fv3 --expt_basedir "test_set_01" -q -#. Our second example will run the fundamental suite of tests on Orion, charging computational resources to the "gsd-fv3" account, and placing the experiment subdirectories in a subdirectory named ``test_set_01``: + This will place all of the fundamental tests into ``${HOMEdir}/../expt_dirs/test_set_01/``. - .. code-block:: + The ``--expt_basedir`` option is useful for grouping various sets of tests. It can also take a full path as an argument, which will place experiments in the given location. - ./run_WE2E_tests.py -t fundamental -m hera -a gsd-fv3 --expt_basedir "test_set_01" -q + The ``-q`` flag will suppress the output from ``generate_FV3LAM_wflow()`` and print only important messages (warnings and errors) to the screen. As always, this output will still be available in the ``log.run_WE2E_tests`` file. - In this case, the full paths to the experiment directories will be: +#. By default, the job monitoring and submission process is serial, using a single task. Therefore, the script may take a long time to return to a given experiment and submit the next job when running large test suites. To speed up this process, users can run the job monitoring processes in parallel using the ``-p`` option to indicate the number of parallel processes (provided they have access to a node with the appropriate availability): .. code-block:: - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta - ${HOMEdir}/../expt_dirs/test_set_01/nco_grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_timeoffset_suite_GFS_v16 - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v15p2 - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v17_p8 - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_HRRR_suite_HRRR - ${HOMEdir}/../expt_dirs/test_set_01/grid_SUBCONUS_Ind_3km_ics_HRRR_lbcs_RAP_suite_WoFS_v0 - ${HOMEdir}/../expt_dirs/test_set_01/grid_RRFS_CONUS_25km_ics_NAM_lbcs_NAM_suite_GFS_v16 + ./run_WE2E_tests.py -t=all -m=jet -a=gsd-fv3-dev -q -p 6 - - The ``--expt_basedir`` option is useful for grouping various sets of tests. It can also be given a full path as an argument, which will place experiments in the given location. - - The ``-q`` flag (as used in the first example shown above), is helpful for keeping the screen less cluttered; this will suppress the output from ``generate_FV3LAM_wflow()``, only printing important messages (warnings and errors) to screen. As always, this output will still be available in the ``log.run_WE2E_tests`` file. - -#. By default, the job monitoring and submission process is serial, using a single task. For test suites that contain many experiments, this means that the script may take a long time to return to a given experiment and submit the next job, due to the amount of time it takes for the ``rocotorun`` command to complete. In order to speed this process up, provided you have access to a node with the appropriate availability (e.g., submitting from a compute node), you can run the job monitoring processes in parallel using the ``-p`` option: - - .. code-block:: - - ./run_WE2E_tests.py -m=jet -a=gsd-fv3-dev -t=all -q -p 6 - - Depending on your machine settings, this can reduce the time it takes to run all experiments substantially. However, it should be used with caution on shared resources (such as HPC login nodes) due to the potential to overwhelm machine resources. + Depending on the machine settings, this can substantially reduce the time it takes to run all experiments. However, it should be used with caution on shared resources (such as HPC login nodes) due to the potential to overwhelm machine resources. #. This example will run the single experiment "custom_ESGgrid" on Hera, charging computational resources to the "fv3lam" account. For this example, we submit the suite of tests using the legacy :term:`cron`-based system: -.. note:: + .. note:: - This option is not recommended, as it does not work on some machines and can cause system bottlenecks on others. + This option is not recommended, as it does not work on some machines and can cause system bottlenecks on others. .. code-block:: ./run_WE2E_tests.py -t=custom_ESGgrid -m=hera -a=fv3lam --use_cron_to_relaunch --cron_relaunch_intvl_mnts=1 -The option ``--use_cron_to_relaunch`` means that, rather than calling the ``monitor_jobs()`` function, the ``generate_FV3LAM_wflow()`` function will create a new :term:`cron` job in the user's cron table that will launch the experiment with the workflow launch script (``launch_FV3LAM_wflow.sh``). By default this script is run every 2 minutes, but we have changed that to 1 minute with the ``--cron_relaunch_intvl_mnts=1`` argument. This script will run until the workflow either completes successfully (i.e., all tasks SUCCEEDED) or fails (i.e., at least one task fails). The cron job is then removed from the user's cron table. + The option ``--use_cron_to_relaunch`` means that, rather than calling the ``monitor_jobs()`` function, the ``generate_FV3LAM_wflow()`` function will create a new :term:`cron` job in the user's cron table that will launch the experiment with the workflow launch script (``launch_FV3LAM_wflow.sh``). By default this script is run every 2 minutes, but we have changed that to 1 minute with the ``--cron_relaunch_intvl_mnts=1`` argument. This script will run until the workflow either completes successfully (i.e., all tasks SUCCEEDED) or fails (i.e., at least one task fails). The cron job is then removed from the user's cron table. -Checking test status and summary +Checking Test Status and Summary ================================= By default, ``./run_WE2E_tests.py`` will actively monitor jobs, printing to screen when jobs are complete (either successfully or with a failure), and print a summary file ``WE2E_summary_{datetime.now().strftime("%Y%m%d%H%M%S")}.txt``. -However, if the user is using the legacy crontab option, or would like to summarize one or more experiments that are either not complete or were not handled by the WE2E test scripts, this status/summary file can be generated manually using ``WE2E_summary.py``. -In this example, an experiment was generated using the crontab option, and has not yet finished running. +However, if the user is using the legacy crontab option or would like to summarize one or more experiments that are either not complete or were not handled by the WE2E test scripts, this status/summary file can be generated manually using ``WE2E_summary.py``. +In this example, an experiment was generated using the crontab option and has not yet finished running. We use the ``-e`` option to point to the experiment directory and get the current status of the experiment: .. code-block:: @@ -307,7 +327,7 @@ As with all python scripts in the App, additional options for this script can be WE2E Test Information File ================================== -If the user wants to see consolidated test information, they can generate a file that can be imported into a spreadsheet program (Google Sheets, Microsoft Excel, etc.) that summarizes each test. This file, named ``WE2E_test_info.txt`` by default, is delimited by the ``|`` character, and can be created either by running the ``./print_test_info.py`` script, or by generating an experiment using ``./run_WE2E_tests.py`` with the ``--print_test_info`` flag. +If the user wants to see consolidated test information, they can generate a file that can be imported into a spreadsheet program (Google Sheets, Microsoft Excel, etc.) that summarizes each test. This file, named ``WE2E_test_info.txt`` by default, is delimited by the ``|`` character and can be created either by running the ``./print_test_info.py`` script, or by generating an experiment using ``./run_WE2E_tests.py`` with the ``--print_test_info`` flag. The rows of the file/sheet represent the full set of available tests (not just the ones to be run). The columns contain the following information (column titles are included in the CSV file): @@ -401,10 +421,10 @@ Adding a New Test --------------------- To add a new test named, e.g., ``new_test01``, to one of the existing test categories, such as ``wflow_features``: -#. 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.yaml`` 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.yaml`` and, if necessary, move it to the ``wflow_features`` category directory. #. Edit the header comments in ``config.new_test01.yaml`` so that they properly describe the new test. #. Edit the contents of ``config.new_test01.yaml`` by modifying existing experiment variable values and/or adding new variables such that the test runs with the intended configuration. - - From c52ee610585319897f17be46255befff0382c884 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 4 Aug 2023 13:19:50 -0400 Subject: [PATCH 044/116] reorganize WE2E, condense --- .../BuildingRunningTesting/WE2Etests.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst index f50c154a6b..471f37f7ab 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst @@ -75,7 +75,7 @@ The test script has three required arguments: machine, account, and tests. #. A test suite name (e.g., "fundamental", "comprehensive", "coverage", or "all"). #. The name of a text file (full or relative path), such as ``my_tests.txt``, which contains a list of the WE2E tests to run (one per line). -Users may run ``./run_WE2E_tests.py -h`` for additional (optional) usage instructions. :numref:`Section %s ` provides examples using some of the most common optional arguments. +Users may run ``./run_WE2E_tests.py -h`` for additional (optional) usage instructions. :numref:`Section %s ` provides additional examples using some of the most common optional arguments. Simple Examples ^^^^^^^^^^^^^^^^^ @@ -246,15 +246,12 @@ The full list of options for ``run_WE2E_tests.py`` can be found using the ``-h`` .. code-block:: - ./run_WE2E_tests.py -t fundamental -m orion -a gsd-fv3 --expt_basedir "test_set_01" -q + ./run_WE2E_tests.py -t fundamental -m orion -a gsd-fv3 --expt_basedir "test_set_01" -q - This will place all of the fundamental tests into ``${HOMEdir}/../expt_dirs/test_set_01/``. + * ``--expt_basedir``: Useful for grouping sets of tests. If set to a relative path, the provided path will be appended to the default path. In this case, all of the fundamental tests will reside in ``${HOMEdir}/../expt_dirs/test_set_01/``. It can also take a full path as an argument, which will place experiments in the given location. + * ``-q``: Suppresses the output from ``generate_FV3LAM_wflow()`` and prints only important messages (warnings and errors) to the screen. The suppressed output will still be available in the ``log.run_WE2E_tests`` file. - The ``--expt_basedir`` option is useful for grouping various sets of tests. It can also take a full path as an argument, which will place experiments in the given location. - - The ``-q`` flag will suppress the output from ``generate_FV3LAM_wflow()`` and print only important messages (warnings and errors) to the screen. As always, this output will still be available in the ``log.run_WE2E_tests`` file. - -#. By default, the job monitoring and submission process is serial, using a single task. Therefore, the script may take a long time to return to a given experiment and submit the next job when running large test suites. To speed up this process, users can run the job monitoring processes in parallel using the ``-p`` option to indicate the number of parallel processes (provided they have access to a node with the appropriate availability): +#. By default, the job monitoring and submission process is serial, using a single task. Therefore, the script may take a long time to return to a given experiment and submit the next job when running large test suites. To speed up this process, users can run the job monitoring processes in parallel using the ``-p`` option to indicate the number of parallel processes (provided the user has access to a node with the appropriate availability): .. code-block:: @@ -262,7 +259,7 @@ The full list of options for ``run_WE2E_tests.py`` can be found using the ``-h`` Depending on the machine settings, this can substantially reduce the time it takes to run all experiments. However, it should be used with caution on shared resources (such as HPC login nodes) due to the potential to overwhelm machine resources. -#. This example will run the single experiment "custom_ESGgrid" on Hera, charging computational resources to the "fv3lam" account. For this example, we submit the suite of tests using the legacy :term:`cron`-based system: +#. This example will run the single experiment ``custom_ESGgrid`` test on Hera, charging computational resources to the "fv3lam" account. For this example, we submit the suite of tests using the legacy :term:`cron`-based system: .. note:: @@ -272,7 +269,8 @@ The full list of options for ``run_WE2E_tests.py`` can be found using the ``-h`` ./run_WE2E_tests.py -t=custom_ESGgrid -m=hera -a=fv3lam --use_cron_to_relaunch --cron_relaunch_intvl_mnts=1 - The option ``--use_cron_to_relaunch`` means that, rather than calling the ``monitor_jobs()`` function, the ``generate_FV3LAM_wflow()`` function will create a new :term:`cron` job in the user's cron table that will launch the experiment with the workflow launch script (``launch_FV3LAM_wflow.sh``). By default this script is run every 2 minutes, but we have changed that to 1 minute with the ``--cron_relaunch_intvl_mnts=1`` argument. This script will run until the workflow either completes successfully (i.e., all tasks SUCCEEDED) or fails (i.e., at least one task fails). The cron job is then removed from the user's cron table. + * ``--use_cron_to_relaunch``: Instead of calling the ``monitor_jobs()`` function, the ``generate_FV3LAM_wflow()`` function will create a new :term:`cron` job in the user's cron table that will launch the experiment with the workflow launch script (``launch_FV3LAM_wflow.sh``). + * ``--cron_relaunch_intvl_mnts=1``: By default, the launch script is run every 2 minutes, but users can set this parameter to a longer or shorter integer number of minutes (here, it is set to 1 minute). This script will run until the workflow either completes successfully (i.e., all tasks SUCCEEDED) or fails (i.e., at least one task fails). The cron job is then removed from the user's cron table. Checking Test Status and Summary From 911ffdce281582e953de9e06b36e50d9ac25a96d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 4 Aug 2023 15:33:36 -0400 Subject: [PATCH 045/116] WE2E edits --- .../BuildingRunningTesting/WE2Etests.rst | 75 ++++++------------- 1 file changed, 23 insertions(+), 52 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst index 471f37f7ab..4d6131a49f 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst @@ -75,10 +75,10 @@ The test script has three required arguments: machine, account, and tests. #. A test suite name (e.g., "fundamental", "comprehensive", "coverage", or "all"). #. The name of a text file (full or relative path), such as ``my_tests.txt``, which contains a list of the WE2E tests to run (one per line). -Users may run ``./run_WE2E_tests.py -h`` for additional (optional) usage instructions. :numref:`Section %s ` provides additional examples using some of the most common optional arguments. +Users may run ``./run_WE2E_tests.py -h`` for additional (optional) usage instructions. -Simple Examples -^^^^^^^^^^^^^^^^^ +Examples +^^^^^^^^^^^ .. attention:: @@ -107,6 +107,16 @@ To run the tests ``custom_ESGgrid`` and ``grid_RRFS_CONUScompact_25km_ics_FV3GFS By default, the experiment directory for a WE2E test has the same name as the test itself, and it is created in ``${HOMEdir}/../expt_dirs``, where ``HOMEdir`` is the top-level directory for the ``ufs-srweather-app`` repository (usually set to something like ``/path/to/ufs-srweather-app``). Thus, the ``custom_ESGgrid`` experiment directory would be located in ``${HOMEdir}/../expt_dirs/custom_ESGgrid``. +**A More Complex Example:** To run the fundamental suite of tests on Orion in parallel, charging computational resources to the "gsd-fv3" account, and placing all the experiment directories into a directory named ``test_set_01``, run: + + .. code-block:: + + ./run_WE2E_tests.py -t fundamental -m orion -a gsd-fv3 --expt_basedir "test_set_01" -q -p 2 + + * ``--expt_basedir``: Useful for grouping sets of tests. If set to a relative path, the provided path will be appended to the default path. In this case, all of the fundamental tests will reside in ``${HOMEdir}/../expt_dirs/test_set_01/``. It can also take a full path as an argument, which will place experiments in the given location. + * ``-q``: Suppresses the output from ``generate_FV3LAM_wflow()`` and prints only important messages (warnings and errors) to the screen. The suppressed output will still be available in the ``log.run_WE2E_tests`` file. + * ``-p 2``: Indicates the number of parallel proceeses to run. By default, job monitoring and submission is serial, using a single task. Therefore, the script may take a long time to return to a given experiment and submit the next job when running large test suites. Depending on the machine settings, running in parallel can substantially reduce the time it takes to run all experiments. However, it should be used with caution on shared resources (such as HPC login nodes) due to the potential to overwhelm machine resources. + Workflow Information ^^^^^^^^^^^^^^^^^^^^^^ @@ -234,49 +244,10 @@ One might have noticed the line during the experiment run that reads "Use ctrl-c ./monitor_jobs.py -y=WE2E_tests_20230418174042.yaml -p=1 -.. _Opt-Args: - -Additional Sample Cases With Optional Arguments --------------------------------------------------- - -The full list of options for ``run_WE2E_tests.py`` can be found using the ``-h`` flag. The examples below demonstrate several of the more common options for ``run_WE2E_tests.py``. - - -#. This first example will run the fundamental suite of tests on Orion, charging computational resources to the "gsd-fv3" account, and placing all the experiment directories into a directory named ``test_set_01``: - - .. code-block:: - - ./run_WE2E_tests.py -t fundamental -m orion -a gsd-fv3 --expt_basedir "test_set_01" -q - - * ``--expt_basedir``: Useful for grouping sets of tests. If set to a relative path, the provided path will be appended to the default path. In this case, all of the fundamental tests will reside in ``${HOMEdir}/../expt_dirs/test_set_01/``. It can also take a full path as an argument, which will place experiments in the given location. - * ``-q``: Suppresses the output from ``generate_FV3LAM_wflow()`` and prints only important messages (warnings and errors) to the screen. The suppressed output will still be available in the ``log.run_WE2E_tests`` file. - -#. By default, the job monitoring and submission process is serial, using a single task. Therefore, the script may take a long time to return to a given experiment and submit the next job when running large test suites. To speed up this process, users can run the job monitoring processes in parallel using the ``-p`` option to indicate the number of parallel processes (provided the user has access to a node with the appropriate availability): - - .. code-block:: - - ./run_WE2E_tests.py -t=all -m=jet -a=gsd-fv3-dev -q -p 6 - - Depending on the machine settings, this can substantially reduce the time it takes to run all experiments. However, it should be used with caution on shared resources (such as HPC login nodes) due to the potential to overwhelm machine resources. - -#. This example will run the single experiment ``custom_ESGgrid`` test on Hera, charging computational resources to the "fv3lam" account. For this example, we submit the suite of tests using the legacy :term:`cron`-based system: - - .. note:: - - This option is not recommended, as it does not work on some machines and can cause system bottlenecks on others. - - .. code-block:: - - ./run_WE2E_tests.py -t=custom_ESGgrid -m=hera -a=fv3lam --use_cron_to_relaunch --cron_relaunch_intvl_mnts=1 - - * ``--use_cron_to_relaunch``: Instead of calling the ``monitor_jobs()`` function, the ``generate_FV3LAM_wflow()`` function will create a new :term:`cron` job in the user's cron table that will launch the experiment with the workflow launch script (``launch_FV3LAM_wflow.sh``). - * ``--cron_relaunch_intvl_mnts=1``: By default, the launch script is run every 2 minutes, but users can set this parameter to a longer or shorter integer number of minutes (here, it is set to 1 minute). This script will run until the workflow either completes successfully (i.e., all tasks SUCCEEDED) or fails (i.e., at least one task fails). The cron job is then removed from the user's cron table. - - Checking Test Status and Summary ================================= -By default, ``./run_WE2E_tests.py`` will actively monitor jobs, printing to screen when jobs are complete (either successfully or with a failure), and print a summary file ``WE2E_summary_{datetime.now().strftime("%Y%m%d%H%M%S")}.txt``. -However, if the user is using the legacy crontab option or would like to summarize one or more experiments that are either not complete or were not handled by the WE2E test scripts, this status/summary file can be generated manually using ``WE2E_summary.py``. +By default, ``./run_WE2E_tests.py`` will actively monitor jobs, printing to console when jobs are complete (either successfully or with a failure), and printing a summary file ``WE2E_summary_{datetime.now().strftime("%Y%m%d%H%M%S")}.txt``. +However, if the user is using the legacy crontab option (by submitting ``./run_WE2E_tests.py`` with the ``--use_cron_to_relaunch`` flag), or if the user would like to summarize one or more experiments that either are not complete or were not handled by the WE2E test scripts, this status/summary file can be generated manually using ``WE2E_summary.py``. In this example, an experiment was generated using the crontab option and has not yet finished running. We use the ``-e`` option to point to the experiment directory and get the current status of the experiment: @@ -317,7 +288,7 @@ We use the ``-e`` option to point to the experiment directory and get the curren Detailed summary written to WE2E_summary_20230306173013.txt -As with all python scripts in the App, additional options for this script can be viewed by calling with the ``-h`` argument. +As with all python scripts in the SRW App, additional options for this script can be viewed by calling with the ``-h`` argument. .. _WE2ETestInfoFile: @@ -353,9 +324,9 @@ The rows of the file/sheet represent the full set of available tests (not just t | Here, ``nx`` and ``ny`` are the number of grid points in the horizontal (``x`` and ``y``) directions, ``num_time_steps`` is the number of time steps in one forecast, and ``num_fcsts`` is the number of forecasts the - test runs (see Column 5 below). [Note that this cost calculation does - not (yet) differentiate between different physics suites.] The relative - cost ``rel_cost`` is then calculated using + test runs (see Column 5 below). (Note that this cost calculation does + not (yet) differentiate between different physics suites.) The relative + cost ``rel_cost`` is then calculated using: .. code-block:: @@ -364,7 +335,7 @@ The rows of the file/sheet represent the full set of available tests (not just t | where ``abs_cost_ref`` is the absolute cost of running the reference forecast described above, i.e., a single (``num_fcsts = 1``) 6-hour forecast (``FCST_LEN_HRS = 6``) on the ``RRFS_CONUS_25km grid`` (which currently has - ``nx = 219``, ``ny = 131``, and ``DT_ATMOS = 40 sec`` (so that ``num_time_steps + ``nx = 219``, ``ny = 131``, and ``DT_ATMOS = 40 sec`` (so that ``num_time_steps = FCST_LEN_HRS*3600/DT_ATMOS = 6*3600/40 = 540``). Therefore, the absolute cost reference is calculated as: .. code-block:: @@ -399,8 +370,8 @@ The rows of the file/sheet represent the full set of available tests (not just t Modifying the WE2E System ============================ -This section describes various ways in which the WE2E testing system can be modified -to suit specific testing needs. + +Users may wish to modify the WE2E testing system to suit specific testing needs. .. _ModExistingTest: @@ -419,7 +390,7 @@ Adding a New Test --------------------- To add a new test named, e.g., ``new_test01``, to one of the existing test categories, such as ``wflow_features``: -#. Choose an existing test configuration file in any one of the category directories that matches most closely the new test to be added. +#. Choose an existing test configuration file that most closely matches the new test to be added. It could come from any one of the category directories. #. Copy that file to ``config.new_test01.yaml`` and, if necessary, move it to the ``wflow_features`` category directory. From d74a1d1e2303cbefe9bda7cf64c36ecdbf7045d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 4 Aug 2023 16:38:07 -0400 Subject: [PATCH 046/116] update Container QS --- .../ContainerQuickstart.rst | 98 +++++++++++++------ 1 file changed, 69 insertions(+), 29 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index 728dfa008b..02f1e07508 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -4,26 +4,24 @@ Container-Based Quick Start Guide ==================================== -This Container-Based Quick Start Guide will help users build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a `Singularity `__ container. The :term:`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:`MPIs `, and package versions available. Installation via Singularity container reduces this variability and allows for a smoother SRW App build experience. Normally, containers can only run on a single compute node and are not compatible with the `Rocoto workflow manager `__, so users must run each task in the workflow manually. However, the Singularity container described in this chapter has been adapted such that it is able to run across multiple nodes using Rocoto. This makes it an excellent starting point for beginners. The :ref:`non-container build approach ` may still be more appropriate for users who desire additional customizability, particularly if they already have experience running the SRW App. +This Container-Based Quick Start Guide will help users build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a `Singularity `__ container. The :term:`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:`MPIs `, and package versions available. Installation via Singularity container reduces this variability and allows for a smoother SRW App build experience. -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. +The basic "out-of-the-box" 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:: * The SRW Application has `four levels of support `__. 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. - * This chapter of the User's Guide should **only** be used for container builds. For non-container builds, see :numref:`Chapter %s ` for a Quick Start Guide or :numref:`Chapter %s ` for a detailed guide to building the SRW App **without** a container. + * This chapter of the User's Guide should **only** be used for container builds. For non-container builds, see :numref:`Section %s ` for a Quick Start Guide or :numref:`Section %s ` for a detailed guide to building the SRW App **without** a container. .. _DownloadCodeC: Download the Container -=========================================== +========================== -Prerequisites: +Prerequisites ------------------- -Users must have an **Intel** compiler and :term:`MPI` (available for free `here `__) in order to run the SRW App in the container provided using the method described in this chapter. Additionally, it is recommended that users install the `Rocoto workflow manager `__ on their system in order to take advantage of automated workflow options. Although it is possible to run an experiment without Rocoto, and some tips are provided, the only fully-supported and tested container option for the ``develop`` branch assumes that Rocoto is pre-installed. - -.. COMMENT: Remove "for the develop branch"? +Users must have an **Intel** compiler and :term:`MPI` (available for free `here `__) in order to run the SRW App in the container provided using the method described in this chapter. Additionally, it is recommended that users install the `Rocoto workflow manager `__ on their system in order to take advantage of automated workflow options. Although it is possible to run an experiment without Rocoto, and some tips are provided, the only fully-supported and tested container option assumes that Rocoto is pre-installed. Install Singularity ^^^^^^^^^^^^^^^^^^^^^^^ @@ -33,6 +31,8 @@ To build and run the SRW App using a Singularity container, first install the Si .. warning:: Docker containers can only be run with root privileges, and users cannot have root privileges on :term:`HPCs `. Therefore, it is not possible to build the SRW App, which uses the HPC-Stack, inside a Docker container on an HPC system. However, a Singularity image may be built directly from a Docker image for use on the system. +.. COMMENT: Update reference to HPC-Stack --> spack-stack? + Working in the Cloud or on HPC Systems ----------------------------------------- @@ -91,17 +91,19 @@ On most Level 1 systems, a container named ``ubuntu20.04-intel-srwapp-develop.im .. note:: Singularity is not available on Gaea, and therefore container use is not supported on Gaea. -Users can simply copy the container to their local working directory. For example, on Hera: +Users can simply set an environment variable to point to the container: .. code-block:: console - cp /scratch1/NCEPDEV/nems/role.epic/containers/ubuntu20.04-intel-srwapp-develop.img . + export img=/path/to/ubuntu20.04-intel-srwapp-develop.img Users may convert the container ``.img`` file to a writable sandbox. This step is required when running on Cheyenne but is optional on other systems: .. code-block:: console - singularity build --sandbox ubuntu20.04-intel-srwapp ubuntu20.04-intel-srwapp-develop.img + singularity build --sandbox ubuntu20.04-intel-srwapp $img + +.. COMMENT: What about on Derecho? When making a writable sandbox on Level 1 systems, the following warnings commonly appear and can be ignored: @@ -130,6 +132,12 @@ Some users may prefer to issue the command without the ``sudo`` prefix. Whether sudo singularity build --sandbox ubuntu20.04-intel-srwapp docker://noaaepic/ubuntu20.04-intel-srwapp:release-public-v2.1.0 +For easier reference, users can set an environment variable to point to the container: + +.. code-block:: console + + export img=/path/to/ubuntu20.04-intel-srwapp + .. _WorkOnHPC: @@ -170,19 +178,18 @@ Copy ``stage-srw.sh`` from the container to the local working directory: .. code-block:: console - singularity exec -B /:/ ./ cp /opt/ufs-srweather-app/container-scripts/stage-srw.sh . - -where ```` is the name of the sandbox directory (i.e., ``ubuntu20.04-intel-srwapp``) or the name of the ``.img`` container file. + singularity exec -B /:/ $img cp /opt/ufs-srweather-app/container-scripts/stage-srw.sh . -.. hint:: - On Jet, users may need to bind to an ``lfs`` directory (e.g., ``/lfs4``) rather than ``/mnt``. +.. COMMENT: Is this still the case? Seems to work better on mnt than lfs now... + .. hint:: + On Jet, users may need to bind to an ``/lfs`` directory (e.g., ``/lfs4``) rather than ``/mnt``. -If the command worked properly, ``stage-srw.sh`` should appear in the local directory. 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 ``-B /:/`` argument before the name of the container. In general, it is recommended that the local base directory and container directory have the same name. For example, if the host system's top-level directory is ``/user1234``, the user can create a ``user1234`` directory in the container sandbox and then bind it: +If the command worked properly, ``stage-srw.sh`` should appear in the local directory. 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 ``-B /:/`` argument before the name of the container. In general, it is recommended that the local base directory and container directory have the same name. For example, if the host system's top-level directory is ``/user1234``, the user can create a ``user1234`` directory in the writable container sandbox and then bind it: .. code-block:: console mkdir /user1234 - singularity exec -B /user1234:/user1234 ./ubuntu20.04-intel-srwapp cp /opt/ufs-srweather-app/container-scripts/stage-srw.sh . + singularity exec -B /user1234:/user1234 $img cp /opt/ufs-srweather-app/container-scripts/stage-srw.sh . .. attention:: Be sure to bind the directory that contains the experiment data! @@ -191,7 +198,7 @@ To explore the container and view available directories, users can either ``cd`` .. code-block:: console - singularity shell ./ubuntu20.04-intel-srwapp-develop.img + singularity shell $img cd / ls @@ -210,7 +217,16 @@ Users can run ``exit`` to exit the shell. 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 systems, the data required to run SRW App tests are already available as long as the bind argument (starting with ``-B``) in :numref:`Step %s ` included the directory with the input model data. See :numref:`Table %s ` for Level 1 data locations. For Level 2-4 systems, the data must be added manually by the user. Detailed instructions on how to add the data can be found in :numref:`Section %s `. Sections :numref:`%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 systems, the data required to run SRW App tests are already available as long as the bind argument (starting with ``-B``) in :numref:`Step %s ` included the directory with the input model data. See :numref:`Table %s ` for Level 1 data locations. For Level 2-4 systems, the data must be added manually by the user. In general, users can download fix file data and experiment data (:term:`ICs/LBCs`) from the `SRW App Data Bucket `__ and then untar it: + +.. code-block:: console + + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/fix_data.tgz + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/gst_data.tgz + tar -xzf fix_data.tgz + tar -xzf gst_data.tgz + +More detailed information can be found in :numref:`Section %s `. Sections :numref:`%s ` and :numref:`%s ` contain useful background information on the input and output files used in the SRW App. .. _GenerateForecastC: @@ -233,7 +249,7 @@ Copy the container's modulefiles to the local working directory so that the file .. code-block:: console - singularity exec -B /:/ ./ cp -r /opt/ufs-srweather-app/modulefiles . + singularity exec -B /:/ $img cp -r /opt/ufs-srweather-app/modulefiles . After this command runs, the local working directory should contain the ``modulefiles`` directory. @@ -241,7 +257,6 @@ To activate the workflow, run the following commands: .. code-block:: console - source etc/lmod-setup.sh module use module load wflow_ @@ -259,6 +274,8 @@ The ``wflow_`` modulefile will then output instructions to activate th then the user should run ``conda activate workflow_tools``. This will activate the ``workflow_tools`` conda environment. The command(s) will vary from system to system, but the user should see ``(workflow_tools)`` in front of the Terminal prompt at this point. +.. COMMENT: Containers are old and still say regional_workflow... + .. _SetUpConfigFileC: Configure the Workflow @@ -268,14 +285,14 @@ Run ``stage-srw.sh``: .. code-block:: console - ./stage-srw.sh -c= -m= -p= -i= + ./stage-srw.sh -c= -m= -p= -i=$img where: * ``-c`` indicates the compiler on the user's local machine (e.g., ``intel/2022.1.2``) * ``-m`` indicates the :term:`MPI` on the user's local machine (e.g., ``impi/2022.1.2``) * ```` refers to the local machine (e.g., ``hera``, ``jet``, ``noaacloud``, ``mac``). See ``MACHINE`` in :numref:`Section %s ` for a full list of options. - * ``-i`` indicates the name of the container image that was built in :numref:`Step %s ` (``ubuntu20.04-intel-srwapp`` or ``ubuntu20.04-intel-srwapp-develop.img`` by default). + * ``-i`` indicates the container image that was built in :numref:`Step %s ` (``ubuntu20.04-intel-srwapp`` or ``ubuntu20.04-intel-srwapp-develop.img`` by default). For example, on Hera, the command would be: @@ -324,8 +341,6 @@ From here, users can follow the steps below to configure the out-of-the-box SRW USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_ICS: /scratch1/NCEPDEV/nems/role.epic/UFS_SRW_data/develop/input_model_data/FV3GFS/grib2/${yyyymmddhh} - EXTRN_MDL_FILES_ICS: [] - EXTRN_MDL_DATA_STORES: disk On other systems, users will need to change the path for ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_FILES_LBCS`` (below) to reflect the location of the system's data. The location of the machine's global data can be viewed :ref:`here ` for Level 1 systems. Alternatively, the user can add the path to their local data if they downloaded it as described in :numref:`Section %s `. @@ -335,8 +350,6 @@ From here, users can follow the steps below to configure the out-of-the-box SRW USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_LBCS: /scratch1/NCEPDEV/nems/role.epic/UFS_SRW_data/develop/input_model_data/FV3GFS/grib2/${yyyymmddhh} - EXTRN_MDL_FILES_LBCS: [] - EXTRN_MDL_DATA_STORES: disk .. _GenerateWorkflowC: @@ -363,10 +376,37 @@ The generated workflow will be in the experiment directory specified in the ``co cd ../../expt_dirs/test_community rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -Users can track the experiment's progress by reissuing the ``rocotostat`` command above every so often until the experiment runs to completion. For users who do not have Rocoto installed, see :numref:`Section %s ` for information on how to run the workflow without Rocoto. +Users can track the experiment's progress by reissuing the ``rocotostat`` command above every so often until the experiment runs to completion. The following message usually means that the experiment is still getting set up: + +.. code-block:: console + + 08/04/23 17:34:32 UTC :: FV3LAM_wflow.xml :: ERROR: Can not open FV3LAM_wflow.db read-only because it does not exist + +After a few (3-5) minutes, ``rocotostat`` should show a status-monitoring table: + +.. code-block:: console + + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + ================================================================================== + 201906151800 make_grid 53583094 QUEUED - 0 0.0 + 201906151800 make_orog - - - - - + 201906151800 make_sfc_climo - - - - - + 201906151800 get_extrn_ics 53583095 QUEUED - 0 0.0 + 201906151800 get_extrn_lbcs 53583096 QUEUED - 0 0.0 + 201906151800 make_ics - - - - - + 201906151800 make_lbcs - - - - - + 201906151800 run_fcst - - - - - + 201906151800 run_post_f000 - - - - - + ... + 201906151800 run_post_f012 - - - - - + +When all tasks show ``SUCCEEDED``, the experiment has completed successfully. + +For users who do not have Rocoto installed, see :numref:`Section %s ` for guidance on how to run the workflow without Rocoto. Troubleshooting ------------------ + If a task goes DEAD, it will be necessary to restart it according to the instructions in :numref:`Section %s `. To determine what caused the task to go DEAD, users should view the log file for the task in ``$EXPTDIR/log/``, where ```` refers to the name of the task's log file. After fixing the problem and clearing the DEAD task, it is sometimes necessary to reinitialize the crontab. Users can copy-paste the crontab command from the bottom of the ``$EXPTDIR/log.generate_FV3LAM_wflow`` file into the crontab: .. code-block:: console From 68658904a0813dc65d28ab72f4c31607949e31b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 4 Aug 2023 18:20:36 -0400 Subject: [PATCH 047/116] update VX cases ch --- .../source/BuildingRunningTesting/VXCases.rst | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst index 0bf58336f9..752f930c60 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst @@ -9,14 +9,14 @@ Introduction The goal of these sample cases is to provide the UFS community with datasets that they can modify and run to see if their changes can improve the forecast and/or reduce the model biases. Each case covers an interesting weather event. The case that was added with the v2.1.0 release was a severe weather event over Indianapolis on June 15-16, 2019. In the future, additional sample cases will be provided. -Each sample case contains model output from a control run; this output includes ``postprd`` (post-processed) and ``metprd`` (MET verification-processed) directories. Under the ``postprd`` directory, users will find the :term:`UPP` output of the model run along with plots for several forecast variables. These can be used for a visual/qualitative comparison of forecasts. The ``metprd`` directory contains METplus verification statistics files, which can be used for a quantitative comparison of forecast outputs. +Each sample case contains model output from a control run; this output includes ``postprd`` (post-processed) and ``metprd`` (MET verification-processed) directories. Under the ``postprd`` directory, users will find the :term:`UPP` output of the model run along with plots for several forecast variables (when plotting tasks are run). These can be used for a visual/qualitative comparison of forecasts. The ``metprd`` directory contains METplus verification statistics files, which can be used for a quantitative comparison of forecast outputs. Prerequisites ================ This chapter assumes that users have already (1) built the SRW App v2.1.0 successfully and (2) installed MET and METplus on their system. -For instructions on how to build the v2.1.0 release of the SRW App, see the v2.1.0 release documentation on :ref:`Building the SRW App `. The release code is used to provide a consistent point of comparison; the ``develop`` branch code is constantly receiving updates, which makes it unsuited to this purpose. Users will have an easier time if they run through the out-of-the-box case described in :numref:`Chapter %s ` before attempting to run any verification sample cases, but doing so is optional. +For instructions on how to build the v2.1.0 release of the SRW App, see the v2.1.0 release documentation on :ref:`Building the SRW App `. The release code is used to provide a consistent point of comparison; the ``develop`` branch code is constantly receiving updates, which makes it unsuited to this purpose. Users will have an easier time if they run through the out-of-the-box case described in the v2.1.0 release documentation on :ref:`Running the SRW App ` before attempting to run any verification sample cases, but doing so is optional. For information on MET and METplus, see :numref:`Section %s `, which contains information on METplus, links to a list of existing MET/METplus builds on `Level 1 & 2 `__ systems, and links to installation instructions and documentation for users on other systems. @@ -49,19 +49,19 @@ On other systems, users need to download the ``Indy-Severe-Weather.tgz`` file us #. Download directly from the S3 bucket using a browser. The data is available at https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#sample_cases/release-public-v2.1.0/. - #. Download from a terminal using the AWS command line interface (CLI) if installed: + #. Download from a terminal using the AWS command line interface (CLI), if installed: .. code-block:: console aws s3 cp https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#sample_cases/release-public-v2.1.0/Indy-Severe-Weather.tgz Indy-Severe-Weather.tgz - #. Download from a terminal using wget: + #. Download from a terminal using ``wget``: .. code-block:: console wget https://noaa-ufs-srw-pds.s3.amazonaws.com/sample_cases/release-public-v2.1.0/Indy-Severe-Weather.tgz -This tar file contains :term:`IC/LBC ` files, observation data, model/forecast output and MET verification output for the sample forecast. Users who have never run the SRW App on their system before will also need to download the fix files required for SRW App forecasts and the NaturalEarth shapefiles required for plotting. Users can download the fix file data from a browser at https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/fix_data.tgz or visit :numref:`Section %s ` for instructions on how to download the data with wget. NaturalEarth files are available at https://noaa-ufs-srw-pds.s3.amazonaws.com/NaturalEarth/NaturalEarth.tgz. See the :ref:`Graphics ` chapter of the release documentation for more information. +This tar file contains :term:`IC/LBC ` files, observation data, model/forecast output, and MET verification output for the sample forecast. Users who have never run the SRW App on their system before will also need to download (1) the fix files required for SRW App forecasts and (2) the NaturalEarth shapefiles required for plotting. Users can download the fix file data from a browser at https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/fix_data.tgz or visit :numref:`Section %s ` for instructions on how to download the data with ``wget``. NaturalEarth files are available at https://noaa-ufs-srw-pds.s3.amazonaws.com/NaturalEarth/NaturalEarth.tgz. See the :ref:`Graphics ` chapter of the release documentation for more information. After downloading ``Indy-Severe-Weather.tgz`` using one of the three methods above, untar the downloaded compressed archive file: @@ -87,13 +87,13 @@ First, navigate to the ``ufs-srweather-app/ush`` directory. Then, load the workf .. code-block:: console - source + source module use module load wflow_ -Users running a csh/tcsh shell would run ``source `` in place of the first command above. +Users running a csh/tcsh shell would run ``source `` in place of the first command above. -After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate workflow_tools``. +After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate regional_workflow``. Configure the Verification Sample Case ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -110,7 +110,7 @@ where ```` is replaced by the actual path to the Then, edit the configuration file (``config.yaml``) to include the variables and values in the sample configuration excerpt below (variables not listed below do not need to be changed or removed). Users must be sure to substitute values in ``<>`` with values appropriate to their system. .. note:: - Users working on a `Level 1 platform `__ do not need to add or update the following variables: ``MET_INSTALL_DIR``, ``METPLUS_PATH``, ``MET_BIN_EXEC``, ``CCPA_OBS_DIR``, ``MRMS_OBS_DIR``, and ``NDAS_OBS_DIR`` + Users working on a `Level 1 platform `__ do not need to add or update the following variables: ``MET_INSTALL_DIR``, ``METPLUS_PATH``, ``MET_BIN_EXEC``, ``CCPA_OBS_DIR``, ``MRMS_OBS_DIR``, and ``NDAS_OBS_DIR``. .. code-block:: console @@ -154,7 +154,7 @@ Then, edit the configuration file (``config.yaml``) to include the variables and To modify the file, hit the ``i`` key and then make any changes required. To close and save, hit the ``esc`` key and type ``:wq``. Users may opt to use their preferred code editor instead. -For additional configuration guidance, refer to :numref:`Section %s `. +For additional configuration guidance, refer to the v2.1.0 release documentation on :ref:`configuring the SRW App `. Generate the Experiment ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -189,7 +189,7 @@ If a problem occurs and a task goes DEAD, view the task log files in ``$EXPTDIR/ Generate Plots ^^^^^^^^^^^^^^^^^ -The plots are created using the graphics generation script that comes with the SRW App v2.1.0 release. Information on the plots and instructions on how to run the script can be found in :doc:`Chapter 12 ` of the v2.1.0 release documentation. If the python environment is already loaded (i.e., ``(workflow_tools)`` is visible in the command prompt), users can navigate to the directory with the plotting scripts and run ``plot_allvars.py``: +The plots are created using the graphics generation script that comes with the SRW App v2.1.0 release. Information on the plots and instructions on how to run the script can be found in :doc:`Chapter 12 ` of the v2.1.0 release documentation. If the python environment is already loaded (i.e., ``(regional_workflow)`` is visible in the command prompt), users can navigate to the directory with the plotting scripts and run ``plot_allvars.py``: .. code-block:: console @@ -199,7 +199,7 @@ The plots are created using the graphics generation script that comes with the S Compare ---------- -Once the experiment has completed (i.e., all tasks have "SUCCEEDED" and the end of the ``log.launch_FV3LAM_wflow`` file lists "Workflow status: SUCCESS"), users can compare their forecast results against the forecast results provided in the ``Indy-Severe-Weather`` directory downloaded in :numref:`Section %s `. This directory contains the forecast output and plots from NOAA developers under the ``postprd`` directory and METplus verification files under the ``metprd`` directory. +Once the experiment has completed (i.e., all tasks have "SUCCEEDED" and the end of the ``log.launch_FV3LAM_wflow`` file lists "Workflow status: SUCCESS"), users can compare their forecast results against the forecast results provided in the ``Indy-Severe-Weather`` directory downloaded in :numref:`Section %s `. This directory contains the forecast output and plots from NOAA developers under the ``postprd`` subdirectory and METplus verification files under the ``metprd`` subdirectory. Qualitative Comparison of the Plots ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 5f0bcf50c0c8f950a543b816061fc029030267b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 4 Aug 2023 19:46:47 -0400 Subject: [PATCH 048/116] update Tutorial --- .../BuildingRunningTesting/Tutorial.rst | 41 +++++++++++++------ 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst index e71e33e838..b56981d78f 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst @@ -60,7 +60,7 @@ To load the workflow environment, source the lmod-setup file. Then load the work .. code-block:: console source etc/lmod-setup.sh # OR: source etc/lmod-setup.csh when running in a csh/tcsh shell - module use /path/to/ufs-srweather-app/modulefiles + module use modulefiles module load wflow_ where ```` is a valid, lowercased machine name (see ``MACHINE`` in :numref:`Section %s ` for valid values). @@ -118,7 +118,7 @@ Start in the ``user:`` section and change the ``MACHINE`` and ``ACCOUNT`` variab For a detailed description of these variables, see :numref:`Section %s `. -Users do not need to change the ``platform:`` section of the configuration file for this tutorial. The default parameters in the ``platform:`` section pertain to METplus verification, which is not addressed here. For more information on verification, see :numref:`Chapter %s `. +Users do not need to change the ``platform:`` section of the configuration file for this tutorial. The default parameters in the ``platform:`` section pertain to METplus verification, which is not addressed here. For more information on verification, see :numref:`Section %s `. In the ``workflow:`` section of ``config.yaml``, update ``EXPT_SUBDIR`` and ``PREDEF_GRID_NAME``. @@ -149,17 +149,20 @@ In the ``workflow:`` section of ``config.yaml``, update ``EXPT_SUBDIR`` and ``PR For a detailed description of other ``workflow:`` variables, see :numref:`Section %s `. To turn on the plotting for the experiment, the YAML configuration file -should be included in the ``rocoto:taskgroups:`` section, like this: +should be included in the ``rocoto:tasks:taskgroups:`` section, like this: .. code-block:: console rocoto: tasks: + metatask_run_ensemble: + task_run_fcst_mem#mem#: + walltime: 02:00:00 taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' For more information on how to turn on/off tasks in the worklfow, please -see :numref:`Section %s ` +see :numref:`Section %s `. In the ``task_get_extrn_ics:`` section, add ``USE_USER_STAGED_EXTRN_FILES`` and ``EXTRN_MDL_SOURCE_BASEDIR_ICS``. Users will need to adjust the file path to reflect the location of data on their system (see :numref:`Section %s ` for locations on `Level 1 `__ systems). @@ -171,7 +174,7 @@ In the ``task_get_extrn_ics:`` section, add ``USE_USER_STAGED_EXTRN_FILES`` and USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/UFS_SRW_App/develop/input_model_data/FV3GFS/grib2/${yyyymmddhh} -For a detailed description of the ``task_get_extrn_ics:`` variables, see :numref:`Section %s `. +For a detailed description of the ``task_get_extrn_ics:`` variables, see :numref:`Section %s `. Similarly, in the ``task_get_extrn_lbcs:`` section, add ``USE_USER_STAGED_EXTRN_FILES`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS``. Users will need to adjust the file path to reflect the location of data on their system (see :numref:`Section %s ` for locations on Level 1 systems). @@ -264,16 +267,21 @@ Next, users will need to modify the data parameters in ``task_get_extrn_ics:`` a HRRR and RAP data are better than FV3GFS data for use with the FV3_RRFS_v1beta physics scheme because these datasets use the same physics :term:`parameterizations` that are in the FV3_RRFS_v1beta suite. They focus on small-scale weather phenomena involved in storm development, so forecasts tend to be more accurate when HRRR/RAP data are paired with FV3_RRFS_v1beta and a high-resolution (e.g., 3-km) grid. Using HRRR/RAP data with FV3_RRFS_v1beta also limits the "spin-up adjustment" that takes place when initializing with model data coming from different physics. -``EXTRN_MDL_LBCS_OFFSET_HRS:`` This variable allows users to use lateral boundary conditions (LBCs) from a previous forecast run that was started earlier than the start time of the forecast being configured in this experiment. This variable is set to 0 by default except when using RAP data; with RAP data, the default value is 3, so the forecast will look for LBCs from a forecast started 3 hours earlier (i.e., at 2019061515 --- 15z --- instead of 2019061518). To avoid this, users must set ``EXTRN_MDL_LBCS_OFFSET_HRS`` explicitly. +``EXTRN_MDL_LBCS_OFFSET_HRS:`` This variable allows users to use lateral boundary conditions (:term:`LBCs`) from a previous forecast run that was started earlier than the start time of the forecast being configured in this experiment. This variable is set to 0 by default except when using RAP data; with RAP data, the default value is 3, so the forecast will look for LBCs from a forecast started 3 hours earlier (i.e., at 2019061515 --- 15z --- instead of 2019061518). To avoid this, users must set ``EXTRN_MDL_LBCS_OFFSET_HRS`` explicitly. -Add a section to ``config.yaml`` to increase the maximum wall time (``WTIME_RUN_POST``) for the postprocessing tasks. The wall time is the maximum length of time a task is allowed to run. On some systems, the default of 15 minutes may be enough, but on others (e.g., NOAA Cloud), the post-processing time exceeds 15 minutes, so the tasks fail. +Under ``rocoto:tasks:``, add a section to increase the maximum wall time for the postprocessing tasks. The walltime is the maximum length of time a task is allowed to run. On some systems, the default of 15 minutes may be enough, but on others (e.g., NOAA Cloud), the post-processing time exceeds 15 minutes, so the tasks fail. .. code-block:: console - task_run_post: - WTIME_RUN_POST: 00:20:00 - -.. COMMENT: Fix above! Maybe add to rocoto section? Otherwise tell them to modify parm/wflow yamls + rocoto: + tasks: + metatask_run_ensemble: + task_run_fcst_mem#mem#: + walltime: 02:00:00 + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' + metatask_run_ens_post: + run_fcst_mem#mem#: + walltime: 00:20:00 Lastly, users must set the ``COMOUT_REF`` variable in the ``task_plot_allvars:`` section to create difference plots that compare output from the two experiments. ``COMOUT_REF`` is a template variable, so it references other workflow variables within it (see :numref:`Section %s ` for details on template variables). ``COMOUT_REF`` should provide the path to the ``control`` experiment forecast output using single quotes as shown below: @@ -306,6 +314,13 @@ To see experiment progress, users should navigate to their experiment directory. If users have not automated their workflow using cron, they will need to ensure that they continue issuing ``rocotorun`` commands to launch all of the tasks in each experiment. While switching between experiment directories to run ``rocotorun`` and ``rocotostat`` commands in both directories is possible, it may be easier to finish the ``control`` experiment's tasks before starting on ``test_expt``. +As with the ``control`` experiment, users can save the location of the ``test_expt`` directory in an environment variable (e.g., ``$TEST``). This makes it easier to navigate between directories later. For example: + +.. code-block:: console + + export TEST=/path/to/expt_dirs/test_expt + +Users should substitute ``/path/to/expt_dirs/test_expt`` with the actual path on their system. Compare and Analyze Results ----------------------------- @@ -360,7 +375,7 @@ The plots generated by the experiment cover a variety of variables. After downlo | Max/Min 2 - 5 km updraft helicity | uh25_diff_regional_fhhh.png | +-----------------------------------------+-----------------------------------+ -Each difference plotting ``.png`` file contains three subplots. The plot for the second experiment (``test_expt``) appears in the top left corner, and the plot for the first experiment (``control``) appears in the top right corner. The difference plot that compares both experiments appears at the bottom. Areas of white signify no difference between the plots. Therefore, if the forecast output from both experiments is exactly the same, the difference plot will show a white square (see :ref:`Sea Level Pressure ` for an example). If the forecast output from both experiments is extremely different, the plot will show lots of color. +Each difference plotting ``.png`` file contains three subplots. The plot for the second experiment (``test_expt``) appears in the top left corner, and the plot for the first experiment (``control``) appears in the top right corner. The difference plot that compares both experiments appears at the bottom. Areas of white signify no difference between the plots. Therefore, if the forecast output from both experiments is exactly the same, the difference plot will show a white square (see :ref:`Sea Level Pressure ` as an example). If the forecast output from both experiments is extremely different, the plot will show lots of color. In general, it is expected that the results for ``test_expt`` (using FV3_RRFS_v1beta physics and HRRR/RAP data) will be more accurate than the results for ``control`` (using FV3_GFS_v16 physics and FV3GFS data) because the physics in ``test_expt`` is designed for high-resolution, storm-scale prediction over a short period of time. The ``control`` experiment physics is better for predicting the evolution of larger scale weather phenomena, like jet stream movement and cyclone development, since the cumulus physics in the FV3_GFS_v16 suite is not configured to run at 3-km resolution. @@ -397,7 +412,7 @@ The predictions diverge further by f012, where a solid section of light blue in Composite Reflectivity `````````````````````````` -Reflectivity images visually represent the weather based on the energy (measured in decibels [dBZ]) reflected back from radar. Composite reflectivity generates an image based on reflectivity scans at multiple elevation angles, or "tilts", of the antenna. See https://www.weather.gov/jetstream/refl for a more detailed explanation of composite reflectivity. +Reflectivity images visually represent the weather based on the energy (measured in decibels [dBZ]) reflected back from radar. Composite reflectivity generates an image based on reflectivity scans at multiple elevation angles, or "tilts", of the antenna. See https://www.noaa.gov/jetstream/reflectivity for a more detailed explanation of composite reflectivity. At f000, the ``test_expt`` plot (top left) is showing more severe weather than the ``control`` plot (top right). The ``test_expt`` plot shows a vast swathe of the Indianapolis region covered in yellow with spots of orange, corresponding to composite reflectivity values of 35+ dBZ. The ``control`` plot radar image covers a smaller area of the grid, and with the exception of a few yellow spots, composite reflectivity values are <35 dBZ. The difference plot (bottom) shows areas where the ``test_expt`` plot (red) and the ``control`` plot (blue) have reflectivity values greater than 20 dBZ. The ``test_expt`` plot has significantly more areas with high composite reflectivity values. From 9374a3e3475fd09ddae69ac95287befaf7840fff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 4 Aug 2023 19:54:56 -0400 Subject: [PATCH 049/116] update 1st half of FAQ --- docs/UsersGuide/source/Reference/FAQ.rst | 95 ++++++++++++++++++++---- 1 file changed, 80 insertions(+), 15 deletions(-) diff --git a/docs/UsersGuide/source/Reference/FAQ.rst b/docs/UsersGuide/source/Reference/FAQ.rst index ac981081b2..98c7ebfb18 100644 --- a/docs/UsersGuide/source/Reference/FAQ.rst +++ b/docs/UsersGuide/source/Reference/FAQ.rst @@ -7,6 +7,7 @@ FAQ * :ref:`How do I define an experiment name? ` * :ref:`How do I change the Physics Suite Definition File (SDF)? ` * :ref:`How do I change the grid? ` +* :ref:`How can I select which workflow tasks to run? ` * :ref:`How do I turn on/off the cycle-independent workflow tasks? ` * :ref:`How do I restart a DEAD task? ` * :ref:`How can I clean up the SRW App code if something went wrong? ` @@ -29,7 +30,7 @@ See :numref:`Section %s ` and/or :numref:`Section %s `. @@ -57,7 +57,70 @@ To change the predefined grid, modify the ``PREDEF_GRID_NAME`` variable in the ` RRFS_CONUS_25km SUBCONUS_Ind_3km -However, users can choose from a variety of predefined grids listed in :numref:`Section %s `. An option also exists to create a user-defined grid, with information available in :numref:`Chapter %s `. However, the user-defined grid option is not fully supported as of the v2.1.0 release and is provided for informational purposes only. +However, users can choose from a variety of predefined grids listed in :numref:`Section %s `. An option also exists to create a user-defined grid, with information available in :numref:`Section %s `. However, the user-defined grid option is not fully supported as of the v2.1.0 release and is provided for informational purposes only. + +.. _SetTasks: + +=============================================== +How can I select which workflow tasks to run? +=============================================== + +The ``/parm/wflow`` directory contains several ``YAML`` files that configure various workflow task groups. Each task group file contains a number of tasks that are typically run together. :numref:`Table %s ` describes each of the task groups. + +.. _task-group-files: + +.. list-table:: Task group files + :widths: 20 50 + :header-rows: 1 + + * - File + - Function + * - aqm_post.yaml + - SRW-AQM post-processing tasks + * - aqm_prep.yaml + - SRW-AQM pre-processing tasks + * - coldstart.yaml + - + * - da_data_preproc.yaml + - + * - plot.yaml + - Plotting tasks + * - post.yaml + - Post-processing tasks + * - prdgen.yaml + - + * - prep.yaml + - Pre-processing tasks + * - verify_det.yaml + - Deterministic verification tasks + * - verify_ens.yaml + - Ensemble verification tasks + * - verify_pre.yaml + - Verification pre-processing tasks + +.. COMMENT: What does prdgen.yaml do? da_data_preproc.yaml? coldstart.yaml? + +The default workflow task groups are set in ``parm/wflow/default_workflow.yaml`` and include ``prep.yaml``, ``coldstart.yaml``, and ``post.yaml``. Changing this list of task groups in ``config.yaml`` will override the default and run only the task groups listed. For example, to omit :term:`cycle-independent` tasks and run plotting tasks, users would delete ``prep.yaml`` from the list of tasks and add ``plot.yaml``: + +.. code-block:: console + + rocoto: + tasks: + taskgroups: '{{ ["parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' + +Users may need to make additional adjustments to ``config.yaml`` depending on which task groups they add or remove. For example, when plotting, the user should add the plotting increment (``PLOT_FCST_INC``) for the plotting tasks in ``task_plot_allvars:``. + +Users can omit specific tasks from a task group by including them under the list of tasks as an empty entry. For example, if a user wanted to run only ``task_pre_post_stat`` from ``aqm_post.yaml``, the taskgroups list would include ``aqm_post.yaml``, and the tasks that the user wanted to omit would be listed with no value: + +.. code-block:: console + + rocoto: + tasks: + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/aqm_post.yaml"]|include }}' + task_post_stat_o3: + task_post_stat_pm25: + task_bias_correction_o3: + task_bias_correction_pm25: .. _CycleInd: @@ -66,18 +129,24 @@ 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 :term:`cycle-independent`, meaning that they only need to be run once per experiment. If the +are :term:`cycle-independent`, meaning that they only need to be run once per experiment. +By default, the the workflow will run these tasks. However, 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 experiment), then -these tasks can be skipped, and the workflow can use those pre-generated files. This -can be done by adding the following parameters to the appropriate sections of the ``config.yaml`` script before running ``generate_FV3LAM_wflow.py``: +these tasks can be skipped, and the workflow can use those pre-generated files. + +To skip these tasks, remove ``parm/wflow/prep.yaml`` from the list of task groups in the Rocoto section of the configuration file (``config.yaml``): + +.. code-block:: console + + rocoto: + tasks: + taskgroups: '{{ ["parm/wflow/coldstart.yaml", "parm/wflow/post.yaml"]|include }}' + +Then, add the paths to the previously generated grid, orography, and surface climatology files under the appropariate tasks in ``config.yaml``: .. code-block:: console - workflow_switches: - RUN_TASK_MAKE_GRID: false - RUN_TASK_MAKE_OROG: false - RUN_TASK_MAKE_SFC_CLIMO: false task_make_grid: GRID_DIR: /path/to/directory/containing/grid/files task_make_orog: @@ -85,11 +154,7 @@ can be done by adding the following parameters to the appropriate sections of th task_make_sfc_climo: SFC_CLIMO_DIR: /path/to/directory/containing/surface/climatology/files -The ``RUN_TASK_MAKE_GRID``, ``RUN_TASK_MAKE_OROG``, and ``RUN_TASK_MAKE_SFC_CLIMO`` flags disable their respective tasks. ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` -specify the directories where pre-generated grid, orography, and surface climatology files are located (all -three sets of files *may* be placed in the same directory location). By default, the ``RUN_TASK_MAKE_*`` -flags are set to true in ``config_defaults.yaml``. This means that the workflow will -run the ``make_grid``, ``make_orog``, and ``make_sfc_climo`` tasks by default. +All three sets of files *may* be placed in the same directory location (and would therefore have the same path). .. _RestartTask: From b3e1c5f289fe1d15298fd24a908f86e9783eb13e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 7 Aug 2023 11:56:15 -0400 Subject: [PATCH 050/116] update FAQ --- docs/UsersGuide/source/Reference/FAQ.rst | 32 +++++++++---------- .../TechnicalDetails/ConfigWorkflow.rst | 2 +- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/UsersGuide/source/Reference/FAQ.rst b/docs/UsersGuide/source/Reference/FAQ.rst index 98c7ebfb18..9fc150fc84 100644 --- a/docs/UsersGuide/source/Reference/FAQ.rst +++ b/docs/UsersGuide/source/Reference/FAQ.rst @@ -65,7 +65,7 @@ However, users can choose from a variety of predefined grids listed in :numref:` How can I select which workflow tasks to run? =============================================== -The ``/parm/wflow`` directory contains several ``YAML`` files that configure various workflow task groups. Each task group file contains a number of tasks that are typically run together. :numref:`Table %s ` describes each of the task groups. +The ``/parm/wflow`` directory contains several ``YAML`` files that configure different workflow task groups. Each task group file contains a number of tasks that are typically run together. :numref:`Table %s ` describes each of the task groups. .. _task-group-files: @@ -80,9 +80,9 @@ The ``/parm/wflow`` directory contains several ``YAML`` files that configure var * - aqm_prep.yaml - SRW-AQM pre-processing tasks * - coldstart.yaml - - + - Tasks required to run a cold-start forecast * - da_data_preproc.yaml - - + - Preprocessing tasks for RRFS `DA `. * - plot.yaml - Plotting tasks * - post.yaml @@ -98,9 +98,9 @@ The ``/parm/wflow`` directory contains several ``YAML`` files that configure var * - verify_pre.yaml - Verification pre-processing tasks -.. COMMENT: What does prdgen.yaml do? da_data_preproc.yaml? coldstart.yaml? +.. COMMENT: What does prdgen.yaml do? -The default workflow task groups are set in ``parm/wflow/default_workflow.yaml`` and include ``prep.yaml``, ``coldstart.yaml``, and ``post.yaml``. Changing this list of task groups in ``config.yaml`` will override the default and run only the task groups listed. For example, to omit :term:`cycle-independent` tasks and run plotting tasks, users would delete ``prep.yaml`` from the list of tasks and add ``plot.yaml``: +The default workflow task groups are set in ``parm/wflow/default_workflow.yaml`` and include ``prep.yaml``, ``coldstart.yaml``, and ``post.yaml``. Changing this list of task groups in the user configuration file (``config.yaml``) will override the default and run only the task groups listed. For example, to omit :term:`cycle-independent` tasks and run plotting tasks, users would delete ``prep.yaml`` from the list of tasks and add ``plot.yaml``: .. code-block:: console @@ -108,7 +108,7 @@ The default workflow task groups are set in ``parm/wflow/default_workflow.yaml`` tasks: taskgroups: '{{ ["parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' -Users may need to make additional adjustments to ``config.yaml`` depending on which task groups they add or remove. For example, when plotting, the user should add the plotting increment (``PLOT_FCST_INC``) for the plotting tasks in ``task_plot_allvars:``. +Users may need to make additional adjustments to ``config.yaml`` depending on which task groups they add or remove. For example, when plotting, the user should add the plotting increment (``PLOT_FCST_INC``) for the plotting tasks in ``task_plot_allvars``. Users can omit specific tasks from a task group by including them under the list of tasks as an empty entry. For example, if a user wanted to run only ``task_pre_post_stat`` from ``aqm_post.yaml``, the taskgroups list would include ``aqm_post.yaml``, and the tasks that the user wanted to omit would be listed with no value: @@ -154,7 +154,7 @@ Then, add the paths to the previously generated grid, orography, and surface cli task_make_sfc_climo: SFC_CLIMO_DIR: /path/to/directory/containing/surface/climatology/files -All three sets of files *may* be placed in the same directory location (and would therefore have the same path). +All three sets of files *may* be placed in the same directory location (and would therefore have the same path), but they can also reside in different directories and use different paths. .. _RestartTask: @@ -181,8 +181,8 @@ has been identified and fixed (by referencing the log files in ``$EXPTDIR/log``) rocotorewind -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201906151800 -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 +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 advance the workflow, the job will be resubmitted. .. _CleanUp: @@ -227,7 +227,7 @@ In addition to the options above, many standard terminal commands can be run to How can I run a new experiment? ================================== -To run a new experiment at a later time, users need to rerun the commands in :numref:`Section %s ` that reactivate the regional workflow python environment: +To run a new experiment at a later time, users need to rerun the commands in :numref:`Section %s ` that reactivate the *workflow_tools* environment: .. code-block:: console @@ -235,9 +235,9 @@ To run a new experiment at a later time, users need to rerun the commands in :nu module use module load wflow_ -Follow any instructions output by the console. +Follow any instructions output by the console (e.g., ``conda activate workflow_tools``). -Then, users can configure a new experiment by updating the environment variables in ``config.yaml`` to reflect the desired experiment configuration. Detailed instructions can be viewed in :numref:`Section %s `. Parameters and valid values are listed in :numref:`Chapter %s `. After adjusting the configuration file, generate the new experiment by running ``./generate_FV3LAM_wflow.py``. Check progress by navigating to the ``$EXPTDIR`` and running ``rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10``. +Then, users can configure a new experiment by updating the environment variables in ``config.yaml`` to reflect the desired experiment configuration. Detailed instructions can be viewed in :numref:`Section %s `. Parameters and valid values are listed in :numref:`Section %s `. After adjusting the configuration file, generate the new experiment by running ``./generate_FV3LAM_wflow.py``. Check progress by navigating to the ``$EXPTDIR`` and running ``rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10``. .. _AddPhys: @@ -245,10 +245,10 @@ Then, users can configure a new experiment by updating the environment variables How can I add a physics scheme (e.g., YSU PBL) to the UFS SRW App? ==================================================================== -At this time, there are ten physics suites available in the SRW App, :ref:`five of which are fully supported `. However, several additional physics schemes are available in the UFS Weather Model (WM) and can be enabled in the SRW App. -To enable an additional physics scheme, such as the YSU PBL scheme, users must modify ``ufs-srweather-app/parm/FV3.input.yml`` and set the variable corresponding to the desired physics scheme to True under the physics suite they would like to use (e.g., ``do_ysu = True``). +At this time, there are ten physics suites available in the SRW App, :ref:`four of which are fully supported `. However, several additional physics schemes are available in the UFS Weather Model (WM) and can be enabled in the SRW App. The CCPP Scientific Documentation details the various `namelist options `__ available in the UFS WM, including physics schemes, and also includes an `overview of schemes and suites `__. +To enable an additional physics scheme, such as the YSU PBL scheme, in the SRW App, users must modify ``ufs-srweather-app/parm/FV3.input.yml`` and set the variable corresponding to the desired physics scheme to *True* under the physics suite they would like to use (e.g., ``do_ysu = True``). -It may be necessary to disable another physics scheme, too. For example, when using the YSU PBL scheme, users should disable the default SATMEDMF PBL scheme (*satmedmfvdifq*) by setting the ``satmedmf`` variable to False in the ``FV3.input.yml`` file. +It may be necessary to disable another physics scheme, too. For example, when using the YSU PBL scheme, users should disable the default SATMEDMF PBL scheme (*satmedmfvdifq*) by setting the ``satmedmf`` variable to *False* in the ``FV3.input.yml`` file. Regardless, users will need to modify the suite definition file (SDF) and recompile the code. For example, to activate the YSU PBL scheme, users should replace the line ``satmedmfvdifq`` with ``ysuvdif`` and recompile the code. Users must ensure that they are using the same physics suite in their ``config.yaml`` file as the one they modified in ``FV3.input.yml``. Then, the user can run the ``generate_FV3LAM_wflow.py`` script to generate an experiment and navigate to the experiment directory. They should see ``do_ysu = .true.`` in the namelist file (or a similar statement, depending on the physics scheme selected), which indicates that the YSU PBL scheme is enabled. @@ -263,4 +263,4 @@ If you encounter issues while generating ICS and LBCS for a predefined 3-km grid Additionally, users can try increasing the number of processors or the wallclock time requested for the jobs. Sometimes jobs may fail without errors because the process is cut short. These settings can be adusted in one of the ``ufs-srweather-app/parm/wflow`` files. For ICs/LBCs tasks, these parameters are set in the ``coldstart.yaml`` file. -Users can also update the hash of UFS_UTILS in the ``Externals.cfg`` file to the HEAD of that repository. There was a known memory issue with how ``chgres_cube`` was handling regridding of the 3-D wind field for large domains at high resolutions (see `UFS_UTILS PR #766 `__ and the associated issue for more information). If changing the hash in ``Externals.cfg``, users will need to rerun ``manage_externals`` and rebuild the code (see :numref:`Chapter %s `). \ No newline at end of file +Users can also update the hash of UFS_UTILS in the ``Externals.cfg`` file to the HEAD of that repository. There was a known memory issue with how ``chgres_cube`` was handling regridding of the 3-D wind field for large domains at high resolutions (see `UFS_UTILS PR #766 `__ and the associated issue for more information). If changing the hash in ``Externals.cfg``, users will need to rerun ``manage_externals`` and rebuild the code (see :numref:`Section %s `). \ No newline at end of file diff --git a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst index f778641f04..ab8e47d53b 100644 --- a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst @@ -310,7 +310,7 @@ CCPP Parameter | ``"FV3_RRFS_v1beta"`` | ``"FV3_HRRR"`` | ``"FV3_WoFS_v0"`` - | ``"FV3_RAP"`` + | ``"FV3_RAP"`` (limited support) Other valid values can be found in the ``ush/valid_param_vals.yaml`` file, but users can not expect full support for these schemes. From 757050380ac0488771a5efd69e326c3289274bd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 7 Aug 2023 11:58:19 -0400 Subject: [PATCH 051/116] add comma --- docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst index b56981d78f..6c7b4a9f9f 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst @@ -539,7 +539,7 @@ Sample Forecast #3: Southern Plains Winter Weather Event Weather Summary -------------------- -A polar vortex brought arctic air to much of the U.S. and Mexico. A series of cold fronts and vorticity disturbances helped keep this cold air in place for an extended period of time resulting in record-breaking cold temperatures for many southern states and Mexico. This particular case captures two winter weather disturbances between February 14, 2021 at 06z and February 17, 2021 at 06z that brought several inches of snow to Oklahoma City. A lull on February 16, 2021 resulted in record daily low temperatures. +A polar vortex brought arctic air to much of the U.S. and Mexico. A series of cold fronts and vorticity disturbances helped keep this cold air in place for an extended period of time, resulting in record-breaking cold temperatures for many southern states and Mexico. This particular case captures two winter weather disturbances between February 14, 2021 at 06z and February 17, 2021 at 06z that brought several inches of snow to Oklahoma City. A lull on February 16, 2021 resulted in record daily low temperatures. **Weather Phenomena:** Snow and record-breaking cold temperatures From f23e4417be45456a55b380d120cade95c39c1863 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 7 Aug 2023 16:20:10 -0400 Subject: [PATCH 052/116] update Rocoto ch & minor details in other chs --- .../source/BackgroundInfo/Components.rst | 2 + .../source/BuildingRunningTesting/AQM.rst | 2 +- .../source/BuildingRunningTesting/RunSRW.rst | 8 +- .../source/Reference/RocotoInfo.rst | 115 +++++++++--------- 4 files changed, 67 insertions(+), 60 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Components.rst b/docs/UsersGuide/source/BackgroundInfo/Components.rst index 890270198a..67ee606ffb 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Components.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Components.rst @@ -97,6 +97,8 @@ RRFS Utilities The Rapid Refresh Forecast System (RRFS) Utilities (rrfs_utl) are a set of tools that that perform tasks required for implementing RRFS capabilities in the SRW App. For example, rrfs_utl performs preprocessing for lightning data, METAR cloud observations, NASA LaRC cloud products, and the NSSL radar reflectivity mosaic. It also provides cloud analysis for the FV3 dycore and radar reflectivity to temperature tendency conversions. For more information on RRFS Utilities, visit the GitHub repository at https://github.com/NOAA-GSL/rrfs_utl or see :numref:`Table %s ` for a detailed description of executables. +.. _uwtools: + Unified Workflow Tools ======================== diff --git a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst index 846f112474..b86786e17a 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst @@ -117,7 +117,7 @@ The community AQM configuration assumes that users have :term:`HPSS` access and EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/data task_get_extrn_lbcs: USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_LBCS: "/path/to/UFS_SRW_App/develop/input_model_data///" + EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/data On Hera, users can find :term:`ICs/LBCs` at ``/scratch2/NCEPDEV/naqfc/RRFS_CMAQ/GFS_DATA/gfs.20230217/{hh}/atmos``. diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index a7174fb738..9e4db3fca4 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -781,13 +781,13 @@ The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``jobs/JREGIONAL_ | get_extrn_lbcs | Cycle-specific task to obtain external data for the | | | lateral boundary conditions (LBCs) | +----------------------+------------------------------------------------------------+ - | make_ics* | Generate ICs from the external data | + | make_ics_* | Generate ICs from the external data | +----------------------+------------------------------------------------------------+ - | make_lbcs* | Generate LBCs from the external data | + | make_lbcs_* | Generate LBCs from the external data | +----------------------+------------------------------------------------------------+ - | run_fcst* | Run the forecast model (UFS Weather Model) | + | run_fcst_* | Run the forecast model (UFS Weather Model) | +----------------------+------------------------------------------------------------+ - | run_post* | Run the post-processing tool (UPP) | + | run_post_* | Run the post-processing tool (UPP) | +----------------------+------------------------------------------------------------+ In addition to the baseline tasks described in :numref:`Table %s ` above, users may choose to run a variety of optional tasks, including plotting and verification tasks. diff --git a/docs/UsersGuide/source/Reference/RocotoInfo.rst b/docs/UsersGuide/source/Reference/RocotoInfo.rst index ad0ec024c9..627969269b 100644 --- a/docs/UsersGuide/source/Reference/RocotoInfo.rst +++ b/docs/UsersGuide/source/Reference/RocotoInfo.rst @@ -3,21 +3,23 @@ ================================== Rocoto Introductory Information ================================== -The tasks in the SRW Application (:numref:`Table %s `) are typically run using -the Rocoto Workflow Manager. Rocoto is a Ruby program that communicates with the batch system on an +The tasks in the SRW Application are typically run using the Rocoto Workflow Manager +(see :numref:`Table %s ` for default tasks). +Rocoto is a Ruby program that communicates with the batch system on an :term:`HPC` system to run and manage dependencies between the tasks. Rocoto submits jobs to the HPC batch system as the task dependencies allow and runs one instance of the workflow for a set of user-defined -:term:`cycles `. More information about Rocoto can be found on the `Rocoto Wiki `__. +:term:`cycles `. More information about Rocoto can be found on the +`Rocoto Wiki `__. The SRW App workflow is defined in a Jinja-enabled Rocoto XML template called ``FV3LAM_wflow.xml``, -which resides in the ``parm`` directory. When the ``generate_FV3LAM_wflow.py`` -script is run, the ``set_template`` uwtool is called, and the parameters in the template file +which resides in the ``parm`` directory. When the ``generate_FV3LAM_wflow.py`` script is run, +the :ref:`Unified Workflow ` ``set_template`` tool 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: ``$EXPTDIR/FV3LAM_wflow.xml``. There are a number of Rocoto commands available to run and monitor the workflow; users can find more information in the -complete `Rocoto documentation `__. +complete `Rocoto documentation `__. Descriptions and examples of commonly used commands are discussed below. .. _RocotoRunCmd: @@ -34,7 +36,7 @@ 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 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. +* ``-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 does not need to exist when the command is initially 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: @@ -43,10 +45,12 @@ From the ``$EXPTDIR`` directory, the ``rocotorun`` command for the workflow woul rocotorun -w FV3LAM_wflow.xml -d FV3LAM_wflow.db +Users will need to include the absolute or relative path to these files when running the command from another directory. + 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 in the `Rocoto documentation `__. +placed in the user’s :term:`crontab`, and cron will call it with a specified frequency. More information on +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. @@ -72,23 +76,23 @@ 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 - - - - - - 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 - - - - - + 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_mem000 - - - - - + 201907010000 make_lbcs_mem000 - - - - - + 201907010000 run_fcst_mem000 - - - - - + 201907010000 run_post__mem000_f000 - - - - - + 201907010000 run_post__mem000_f001 - - - - - + 201907010000 run_post__mem000_f002 - - - - - + 201907010000 run_post__mem000_f003 - - - - - + 201907010000 run_post__mem000_f004 - - - - - + 201907010000 run_post__mem000_f005 - - - - - + 201907010000 run_post__mem000_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 currently being @@ -105,27 +109,28 @@ on the grid size and computational resources available), the output of the ``roc .. 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 - 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 - - - - - + 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_mem000 175825 SUCCEEDED 0 1 99.0 + 201907010000 make_lbcs_mem000 175826 SUCCEEDED 0 1 90.0 + 201907010000 run_fcst_mem000 175937 RUNNING - 0 0.0 + 201907010000 run_post__mem000_f000 - - - - - + 201907010000 run_post__mem000_f001 - - - - - + 201907010000 run_post__mem000_f002 - - - - - + 201907010000 run_post__mem000_f003 - - - - - + 201907010000 run_post__mem000_f004 - - - - - + 201907010000 run_post__mem000_f005 - - - - - + 201907010000 run_post__mem000_f006 - - - - - When the workflow runs to completion, all tasks will be marked as SUCCEEDED. The log file for each task is located in ``$EXPTDIR/log``. If any task fails, the corresponding log file can be checked for error -messages. Optional arguments for the ``rocotostat`` command can be found in the `Rocoto documentation `__. +messages. Optional arguments for the ``rocotostat`` command can be found in the +`Rocoto documentation `__. .. _rocotocheck: @@ -138,35 +143,35 @@ from the ``$EXPTDIR`` directory as follows: .. code-block:: console - rocotocheck -w -d file -c -t + rocotocheck -w FV3LAM_wflow.xml -d FV3LAM_wflow.db file -c -t where -* ``-c`` is the cycle to query in YYYYMMDDHHmm format -* ``-t`` is the task name (e.g., ``make_grid``, ``get_extrn_ics``, ``run_fcst``). +* ``-c`` is the cycle to query in YYYYMMDDHHmm format. +* ``-t`` is the task name (e.g., ``make_grid``, ``get_extrn_ics``, ``run_fcst_mem000``). -The cycle and task names appear in the first and second columns of the table output by ``rocotostat``. +The cycle and task names appear in the first and second columns of the table output by ``rocotostat``. Users will need to include the absolute or relative path to the worflow XML and database files when running the command from another directory. A specific example is: .. code-block:: console - rocotocheck -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201907010000 -t run_fcst + rocotocheck -w /Users/John.Doe/expt_dirs/test_community/FV3LAM_wflow.xml -d /Users/John.Doe/expt_dirs/test_community/FV3LAM_wflow.db -v 10 -c 201907010000 -t run_fcst_mem000 Running ``rocotocheck`` will result in output similar to the following: .. code-block:: console :emphasize-lines: 8,19,34 - Task: run_fcst + Task: run_fcst_mem000 account: gsd-fv3 - command: /scratch2/BMC/det/$USER/ufs-srweather-app/ush/load_modules_run_task.sh "run_fcst" "/scratch2/BMC/det/$USER/ufs-srweather-app/jobs/JREGIONAL_RUN_FCST" + command: /scratch2/BMC/det/$USER/ufs-srweather-app/ush/load_modules_run_task.sh "run_fcst_mem000" "/scratch2/BMC/det/$USER/ufs-srweather-app/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 + join: /scratch2/BMC/det/$USER/expt_dirs/test_community/log/run_fcst_mem000_2019070100.log maxtries: 3 - name: run_fcst + name: run_fcst_mem000 nodes: 1:ppn=24 queue: batch throttle: 9999999 @@ -222,13 +227,13 @@ command to rerun the forecast task from ``$EXPTDIR`` is: .. code-block:: console - rocotorewind -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201907010000 -t run_fcst + rocotorewind -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 -c 201907010000 -t run_fcst_mem000 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 the ``$EXPTDIR`` is: +use this command to rerun the ``make_ics`` task from ``$EXPTDIR`` is: .. code-block:: console From 188a149315533c65d44ab474c7d280dc0059faba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 7 Aug 2023 17:41:25 -0400 Subject: [PATCH 053/116] rename Tech Deteails ch --- .../source/TinkeringWWflowDetails/.DS_Store | Bin 0 -> 6148 bytes .../ConfigWorkflow.rst | 0 .../DefineWorkflow.rst | 0 .../InputOutputFiles.rst | 0 .../LAMGrids.rst | 0 .../TemplateVars.rst | 0 .../index.rst | 0 7 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/UsersGuide/source/TinkeringWWflowDetails/.DS_Store rename docs/UsersGuide/source/{TechnicalDetails => TinkeringWWflowDetails}/ConfigWorkflow.rst (100%) rename docs/UsersGuide/source/{TechnicalDetails => TinkeringWWflowDetails}/DefineWorkflow.rst (100%) rename docs/UsersGuide/source/{TechnicalDetails => TinkeringWWflowDetails}/InputOutputFiles.rst (100%) rename docs/UsersGuide/source/{TechnicalDetails => TinkeringWWflowDetails}/LAMGrids.rst (100%) rename docs/UsersGuide/source/{TechnicalDetails => TinkeringWWflowDetails}/TemplateVars.rst (100%) rename docs/UsersGuide/source/{TechnicalDetails => TinkeringWWflowDetails}/index.rst (100%) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/.DS_Store b/docs/UsersGuide/source/TinkeringWWflowDetails/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..96cee1fa00d593680d3ed807d100982b4dacb699 GIT binary patch literal 6148 zcmeHK!A=4}41GmnBzhpmgBO$i0uujVLDZ0FJZSW)2pHlDMj(3JyC38CdD7SEh_Zl3 zHKtA4H`{GHvu`%r9RSjpbasI%fHkUOsY0_r^uFqxl%i*qD4|9lH@LtM54fF+cE?|2 zK=*DFd)%`Ddic73J!JGgqQ>1EVcg1w*X?ZBX1u;EFVxyw5RSA)6Wvf@K>T>Z8y~Pz#yX?Lb>z8FX9Gv5;~0m0);?FTEbq0D zSH&4;x#J2lTyYIuoD-F=1*{ocpO&>;oB?OR8TcIr*t1pE)(zb{1I~amFl9i$4+&K< zjhGvTPX|pn0uak|2jN(M4>c!=m`2PEd50pFO0-moM+~ua`jZ%!M$8Q@9TE>85@(ip zLXj{#>n9-`k{Y^o2AqLe23G8{s{Ma|`T2h~$*-INXW(BkAm!$1v%yD-y>;&4wAUuo qOR9>-<%ZJ~4niwtthVB9Y7qJp9T3xqxgk9i{}Bi@xN!!4l!15ug?5(! literal 0 HcmV?d00001 diff --git a/docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst similarity index 100% rename from docs/UsersGuide/source/TechnicalDetails/ConfigWorkflow.rst rename to docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst diff --git a/docs/UsersGuide/source/TechnicalDetails/DefineWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst similarity index 100% rename from docs/UsersGuide/source/TechnicalDetails/DefineWorkflow.rst rename to docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst diff --git a/docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst similarity index 100% rename from docs/UsersGuide/source/TechnicalDetails/InputOutputFiles.rst rename to docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst diff --git a/docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/LAMGrids.rst similarity index 100% rename from docs/UsersGuide/source/TechnicalDetails/LAMGrids.rst rename to docs/UsersGuide/source/TinkeringWWflowDetails/LAMGrids.rst diff --git a/docs/UsersGuide/source/TechnicalDetails/TemplateVars.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst similarity index 100% rename from docs/UsersGuide/source/TechnicalDetails/TemplateVars.rst rename to docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst diff --git a/docs/UsersGuide/source/TechnicalDetails/index.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/index.rst similarity index 100% rename from docs/UsersGuide/source/TechnicalDetails/index.rst rename to docs/UsersGuide/source/TinkeringWWflowDetails/index.rst From e1ef957703a00723dfe683444a5b64a8619e475f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 7 Aug 2023 17:47:18 -0400 Subject: [PATCH 054/116] update index file w/new dir names --- docs/UsersGuide/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index 95c0c525ba..8aa16e2969 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -13,5 +13,5 @@ UFS Short-Range Weather App Users Guide BackgroundInfo/index BuildingRunningTesting/index - TechnicalDetails/index + TinkeringWWflowDetails/index Reference/index From 7c5818d6700527062e9aee839ebeb3b5f41939bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 8 Aug 2023 10:54:17 -0400 Subject: [PATCH 055/116] add ufs wm intersphinx --- docs/UsersGuide/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/UsersGuide/source/conf.py b/docs/UsersGuide/source/conf.py index 1490321e96..a6023d339d 100644 --- a/docs/UsersGuide/source/conf.py +++ b/docs/UsersGuide/source/conf.py @@ -211,6 +211,7 @@ def setup(app): 'hpc-stack': ('https://hpc-stack-epic.readthedocs.io/en/latest/', None), 'met': ('https://met.readthedocs.io/en/latest/', None), 'srw_v2.1.0': ('https://ufs-srweather-app.readthedocs.io/en/release-public-v2.1.0/', None), + 'ufs-wm': ('https://ufs-weather-model.readthedocs.io/en/latest/', None), } # -- Options for todo extension ---------------------------------------------- From 3c2c727e20c8af668af1c356efaa3c22fa116ed8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 8 Aug 2023 10:54:51 -0400 Subject: [PATCH 056/116] I/O updates --- .../InputOutputFiles.rst | 91 ++++++++----------- 1 file changed, 38 insertions(+), 53 deletions(-) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst index 8755fae6c7..98fd6f2f85 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst @@ -19,9 +19,9 @@ 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 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. + * 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. 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. @@ -32,7 +32,7 @@ When a user generates the SRW App workflow as described in :numref:`Section %s < UFS Weather Model ----------------- The input files for the UFS Weather Model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix(ed) 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 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 `. +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 on staging the data on a new machine and :numref:`Section %s ` for data locations on Level 1 machines.) The workflow scripts link the static, grid, and date-specific files to 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) ---------------------------- @@ -53,49 +53,32 @@ and are shown in :numref:`Table %s `. .. _TemplateFiles: -.. table:: Template Files for the SRW App 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 | - | | :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 | - | | :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 | - | | ``generate_FV3LAM_wflow.py``. | - +-----------------------------+--------------------------------------------------------------+ - | input.nml.FV3 | Namelist file for the Weather Model. | - +-----------------------------+--------------------------------------------------------------+ - | model_configure | Settings and configurations for the | - | | :term:`NUOPC`/:term:`ESMF` main component. | - +-----------------------------+--------------------------------------------------------------+ - | 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 :term:`ESG` | - | | grid. | - +-----------------------------+--------------------------------------------------------------+ - | README.xml_templating.md | Instructions for Rocoto XML templating with Jinja. | - +-----------------------------+--------------------------------------------------------------+ +.. list-table:: Template Files for the SRW App Workflow + :widths: 20 50 + :header-rows: 1 + + * - 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 :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 :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 ``generate_FV3LAM_wflow.py``. + * - input.nml.FV3 + - Namelist file for the Weather Model. + * - model_configure + - Settings and configurations for the :term:`NUOPC`/:term:`ESMF` main component. + * - nems.configure + - :term:`NEMS` (NOAA Environmental Modeling System) configuration file. No need to change because the usual SRW App configuration is atmosphere-only, and UFS-AQM settings handle any configuration/templating required for that configuration. + * - 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 ``diag_table.[CCPP]``, ``field_table.[CCPP]``, ``input.nml.FV3``, ``model_configure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, while information on ``regional_grid.nml`` options can be found in the `UFS_UTILS Technical Documentation `__. @@ -115,13 +98,15 @@ Migratory Route of the Input Files in the Workflow Output Files ============== -Output files from each workflow task are written to a subdirectory within the experiment directory (``$EXPTDIR/YYYYMMDDHH``), named based on the settings in ``config.yaml``. +Output files from each workflow task are written to a subdirectory within the experiment directory (``$EXPTDIR/YYYYMMDDHH``), named based on the settings in ``config.yaml``. These files may then be used as input to future tasks. Initial and boundary condition files ------------------------------------ The external model data used by ``chgres_cube`` (as part of the pre-processing utilities) are located in the experiment directory under ``$EXPTDIR/YYYYMMDDHH/EXTRN_MDL_NAME/{for_ICS/for_LBCS}``. +.. COMMENT: This is confusing bc it sounds like these are input files, not output files. Does chgres_cube output these? In which tasks? + Pre-processing (UFS_UTILS) -------------------------- The files output by the other pre-processing utilities reside in the ``INPUT`` directory under the @@ -146,7 +131,7 @@ These output files are used as inputs for the UFS Weather Model and are describe UFS Weather Model ------------------ -As stated in :numref:`Section %s `, the workflow can be run in "community" mode or "nco" mode, which determines the location and names of the output files. Weather Model output files can 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 as output for the SRW Application. +As stated in :numref:`Section %s `, the workflow can be run in "community" mode or "nco" mode, which determines the location and names of the output files. Weather Model output files can be in :term:`netCDF` or :term:`NEMSIO` format. The output file format is set in the ``model_configure`` file using the ``output_file`` variable (see :ref:`UFS WM Documentation `). At this time, due to limitations in the post-processing component, only netCDF output is recommended as output for the SRW Application. .. note:: The fully supported options for this release include running in "community" mode with netCDF-formatted output files. @@ -191,7 +176,7 @@ After creating the new flat text file to reflect the changes, users will need to .. code-block:: console USE_CUSTOM_POST_CONFIG_FILE: true - CUSTOM_POST_CONFIG_FP: + CUSTOM_POST_CONFIG_FP: /path/to/custom/postxconfig-NT-fv3lam.txt which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If ``USE_CUSTOM_POST_CONFIG_FILE`` is set to true, but the file path is not found, then an error will occur when trying to generate the SRW Application workflow. @@ -217,7 +202,7 @@ Modify the ``config.yaml`` file to include the following lines: .. code-block:: console USE_CRTM: true - CRTM_DIR: + 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. @@ -279,11 +264,11 @@ The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBC task_get_extrn_ics: USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_ICS: + EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH EXTRN_MDL_DATA_STORES: disk task_get_extrn_lbcs: USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_LBCS: + EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH EXTRN_MDL_DATA_STORES: disk The two ``EXTRN_MDL_SOURCE_BASEDIR_*CS`` variables describe where the :term:`IC ` and :term:`LBC ` file directories are located, respectively. For ease of reusing ``config.yaml`` across experiments, it is recommended that users set up the raw :term:`IC/LBC ` file paths to include the model name (e.g., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path-to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. From 9806215d050f429fbd2dd246b65e61f7e2635b12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 8 Aug 2023 10:56:15 -0400 Subject: [PATCH 057/116] update file /path/to convention --- .../source/BackgroundInfo/Introduction.rst | 4 ++- .../BuildingRunningTesting/BuildSRW.rst | 10 +++---- .../ContainerQuickstart.rst | 14 +++++----- .../BuildingRunningTesting/Quickstart.rst | 2 +- .../source/BuildingRunningTesting/RunSRW.rst | 20 +++++++------- .../BuildingRunningTesting/Tutorial.rst | 2 +- .../source/BuildingRunningTesting/VXCases.rst | 26 +++++++++---------- docs/UsersGuide/source/Reference/FAQ.rst | 4 +-- .../source/Reference/RocotoInfo.rst | 6 ++--- .../TinkeringWWflowDetails/TemplateVars.rst | 2 +- 10 files changed, 46 insertions(+), 44 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index c8e8f8d4a7..3c843c6509 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -80,7 +80,9 @@ 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, or directories. -File paths and code that include angle brackets (e.g., ``build__``) indicate that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). +Code that includes angle brackets (e.g., ``build__``) indicates that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). + +File or directory paths that begin with ``/path/to/`` should be replaced with the actual path on the user's system. For example, ``/path/to/modulefiles`` might be replaced by ``/Users/Jane.Smith/ufs-srweather-app/modulefiles``. User Support, Documentation, and Contributions to Development =============================================================== diff --git a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst index 726a4b7ca6..c75b623b24 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst @@ -167,7 +167,7 @@ Run the executable that pulls in SRW App components from external repositories: .. code-block:: console - cd + cd /path/to/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. @@ -383,10 +383,10 @@ From here, ``Lmod`` is ready to load the modulefiles needed by the SRW App. Thes .. code-block:: console - module use + module use /path/to/modulefiles module load build__ -where ```` is the full path to the ``modulefiles`` directory. +where ``/path/to/modulefiles/`` is the full path to the ``modulefiles`` directory. This will work on Level 1 systems, where a modulefile is available in the ``modulefiles`` directory. Users on Level 2-4 systems (including generic Linux/MacOS systems) will need to modify an appropriate ``build__`` modulefile. One of the current ``build__`` modulefiles can be copied and used as a template. However, users will need to adjust certain environment variables in their modulefile, such as the path to HPC-Stack, so that the SRW App can find and load the appropriate modules. @@ -457,8 +457,8 @@ Next, users must source the Lmod setup file, just as they would on other systems .. code-block:: console - source etc/lmod-setup.sh - module use + source /path/to/ufs-srweather-app/etc/lmod-setup.sh + module use /path/to/ufs-srweather-app/modulefiles module load build__gnu export LDFLAGS+=" -L${MPI_ROOT}/lib " diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index 02f1e07508..521dbdba4a 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -40,8 +40,8 @@ For users working on systems with limited disk space in their ``/home`` director .. code-block:: - export SINGULARITY_CACHEDIR= - export SINGULARITY_TMPDIR= + export SINGULARITY_CACHEDIR=/absolute/path/to/writable/directory/cache + export SINGULARITY_TMPDIR=/absolute/path/to/writable/directory/tmp where ``/absolute/path/to/writable/directory/`` refers to a writable directory (usually a project or user directory within ``/lustre``, ``/work``, ``/scratch``, or ``/glade`` on NOAA Level 1 systems). If the ``cache`` and ``tmp`` directories do not exist already, they must be created with a ``mkdir`` command. @@ -188,7 +188,7 @@ If the command worked properly, ``stage-srw.sh`` should appear in the local dire .. code-block:: console - mkdir /user1234 + mkdir /path/to/container/user1234 singularity exec -B /user1234:/user1234 $img cp /opt/ufs-srweather-app/container-scripts/stage-srw.sh . .. attention:: @@ -257,12 +257,12 @@ To activate the workflow, run the following commands: .. code-block:: console - module use + module use /path/to/modulefiles module load wflow_ where: - * ```` is replaced with the actual path to the modulefiles on the user's local system (often ``$PWD/modulefiles``), and + * ``/path/to/modulefiles`` is replaced with the actual path to the modulefiles on the user's local system (often ``$PWD/modulefiles``), and * ```` is a valid, lowercased machine/platform name (see the ``MACHINE`` variable in :numref:`Section %s `). The ``wflow_`` modulefile will then output instructions to activate the workflow. The user should run the commands specified in the modulefile output. For example, if the output says: @@ -413,7 +413,7 @@ If a task goes DEAD, it will be necessary to restart it according to the instruc crontab -e i - */3 * * * * cd //expt_dirs/test_community && ./launch_FV3LAM_wflow.sh called_from_cron="TRUE" + */3 * * * * cd /path/to/expt_dirs/test_community && ./launch_FV3LAM_wflow.sh called_from_cron="TRUE" esc :wq enter @@ -422,7 +422,7 @@ If a task goes DEAD, it will be necessary to restart it according to the instruc where: - * ```` is replaced by the actual path to the user's experiment directory, and + * ``/path/to`` is replaced by the actual path to the user's experiment directory, and * ``esc`` and ``enter`` refer to the escape and enter **keys** (not a typed command). New Experiment diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst index b7eb9d5fc4..4829b21774 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst @@ -52,7 +52,7 @@ For a detailed explanation of how to build and run the SRW App on any supported .. code-block:: console - module use + module use /path/to/ufs-srweather-app/modulefiles module load wflow_ where ```` refers to a valid machine name (see :numref:`Section %s `). After loading the workflow, users should follow the instructions printed to the console. For example, if the output says: diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 9e4db3fca4..09c520515d 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -126,8 +126,8 @@ The ``workflow_tools`` conda/Python environment has already been set up on Level .. code-block:: console - source - module use + source /path/to/etc/lmod-setup.sh/OR/lmod-setup.csh + module use /path/to/modulefiles module load wflow_ where ```` refers to a valid machine name (see :numref:`Section %s ` for ``MACHINE`` options). @@ -216,8 +216,8 @@ After creating a ``workflow_tools`` environment and making modifications to a `` .. code-block:: console - source - module use + source /path/to/etc/lmod-setup.sh + module use /path/to/modulefiles module load wflow_ where ```` refers to a valid machine name (i.e., ``linux`` or ``macos``). @@ -634,7 +634,7 @@ Users who want to use the METplus verification suite to evaluate their forecasts .. code-block:: console - module use -a + module use -a /path/to/met/modulefiles module load met/ To use METplus verification, the path to the MET and METplus directories must be added to ``config.yaml``: @@ -642,8 +642,8 @@ To use METplus verification, the path to the MET and METplus directories must be .. code-block:: console platform: - METPLUS_PATH: - MET_INSTALL_DIR: + METPLUS_PATH: /path/to/METplus/METplus-4.1.0 + MET_INSTALL_DIR: /path/to/met/10.1.0 On Level 1 systems, users can find this path in the machine file for their system. On other systems, users will need to determine where MET and METplus were installed. @@ -922,9 +922,9 @@ This will automatically add an appropriate entry to the user's :term:`cron table .. code-block:: console - */3 * * * * cd && ./launch_FV3LAM_wflow.sh called_from_cron="TRUE" + */3 * * * * cd /path/to/experiment/directory && ./launch_FV3LAM_wflow.sh called_from_cron="TRUE" -where ```` is changed to correspond to the user's ``$EXPTDIR``. The number ``3`` can be changed to a different positive integer; it simply means that the workflow will be resubmitted every three minutes. +where ``/path/to/experiment/directory`` is changed to correspond to the user's ``$EXPTDIR``. The number ``3`` can be changed to a different positive integer; it simply means that the workflow will be resubmitted every three minutes. .. hint:: @@ -1128,7 +1128,7 @@ The SRW App workflow can be run using standalone shell scripts in cases where th .. code-block:: console - cp /ufs-srweather-app/ush/wrappers/* . + cp /path/to/ufs-srweather-app/ush/wrappers/* . #. Set the ``OMP_NUM_THREADS`` variable. diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst index 6c7b4a9f9f..c27544f54e 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Tutorial.rst @@ -338,7 +338,7 @@ In summary, users can run the ``scp`` command in a new terminal/command prompt w scp username@your-IP-address:/path/to/source_file_or_directory /path/to/destination_file_or_directory # OR - scp -P 12345 username@localhost:/path/to/source_file_or_directory path/to/destination_file_or_directory + scp -P 12345 username@localhost:/path/to/source_file_or_directory /path/to/destination_file_or_directory Users would need to modify ``username``, ``your-IP-address``, ``-P 12345``, and the file paths to reflect their systems' information. See the :ref:`Introduction to SSH & Data Transfer ` for example commands. diff --git a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst index 752f930c60..db52de9a10 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst @@ -87,11 +87,11 @@ First, navigate to the ``ufs-srweather-app/ush`` directory. Then, load the workf .. code-block:: console - source - module use + source /path/to/etc/lmod-setup.sh + module use /path/to/ufs-srweather-app/modulefiles module load wflow_ -Users running a csh/tcsh shell would run ``source `` in place of the first command above. +Users running a csh/tcsh shell would run ``source /path/to/etc/lmod-setup.csh `` in place of the first command above. After loading the workflow, users should follow the instructions printed to the console. Usually, the instructions will tell the user to run ``conda activate regional_workflow``. @@ -102,10 +102,10 @@ Once the workflow environment is loaded, copy the out-of-the-box configuration: .. code-block:: console - cd + cd /path/to/ufs-srweather-app/ush cp config.community.yaml config.yaml -where ```` is replaced by the actual path to the ``ufs-srweather-app/ush`` directory on the user's system. +where ``/path/to/ufs-srweather-app/ush`` is replaced by the actual path to the ``ufs-srweather-app/ush`` directory on the user's system. Then, edit the configuration file (``config.yaml``) to include the variables and values in the sample configuration excerpt below (variables not listed below do not need to be changed or removed). Users must be sure to substitute values in ``<>`` with values appropriate to their system. @@ -118,13 +118,13 @@ Then, edit the configuration file (``config.yaml``) to include the variables and ACCOUNT: platform: MODEL: FV3_GFS_v16_SUBCONUS_3km - MET_INSTALL_DIR: # Example: MET_INSTALL_DIR: /contrib/met/10.1.1 - METPLUS_PATH: # Example: METPLUS_PATH: /contrib/METplus/METplus-4.1.1 + MET_INSTALL_DIR: /path/to/met/x.x.x # Example: MET_INSTALL_DIR: /contrib/met/10.1.1 + METPLUS_PATH: /path/to/METplus/METplus-x.x.x # Example: METPLUS_PATH: /contrib/METplus/METplus-4.1.1 # Add MET_BIN_EXEC variable to config.yaml MET_BIN_EXEC: bin - CCPA_OBS_DIR: - MRMS_OBS_DIR: - NDAS_OBS_DIR: + CCPA_OBS_DIR: /path/to/Indy-Severe-Weather/obs_data/ccpa/proc + MRMS_OBS_DIR: /path/to/Indy-Severe-Weather/obs_data/mrms/proc + NDAS_OBS_DIR: /path/to/Indy-Severe-Weather/obs_data/ndas/proc workflow: EXPT_SUBDIR: DATE_FIRST_CYCL: '2019061500' @@ -135,11 +135,11 @@ Then, edit the configuration file (``config.yaml``) to include the variables and RUN_TASK_VX_POINTSTAT: true task_get_extrn_ics: # Add EXTRN_MDL_SOURCE_BASEDIR_ICS variable to config.yaml - EXTRN_MDL_SOURCE_BASEDIR_ICS:     + EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/Indy-Severe-Weather/input_model_data/FV3GFS/grib2/2019061500 USE_USER_STAGED_EXTRN_FILES: true task_get_extrn_lbcs: # Add EXTRN_MDL_SOURCE_BASEDIR_LBCS variable to config.yaml - EXTRN_MDL_SOURCE_BASEDIR_LBCS:     + EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/Indy-Severe-Weather/input_model_data/FV3GFS/grib2/2019061500 USE_USER_STAGED_EXTRN_FILES: true task_run_fcst: WTIME_RUN_FCST: 05:00:00 @@ -193,7 +193,7 @@ The plots are created using the graphics generation script that comes with the S .. code-block:: console - cd + cd /path/to/ufs-srweather-app/ush/Python python plot_allvars.py 2019061500 0 60 6 / SUBCONUS_Ind_3km Compare diff --git a/docs/UsersGuide/source/Reference/FAQ.rst b/docs/UsersGuide/source/Reference/FAQ.rst index 9fc150fc84..60ed0290c2 100644 --- a/docs/UsersGuide/source/Reference/FAQ.rst +++ b/docs/UsersGuide/source/Reference/FAQ.rst @@ -231,8 +231,8 @@ To run a new experiment at a later time, users need to rerun the commands in :nu .. code-block:: console - source - module use + source /path/to/etc/lmod-setup.sh/or/lmod-setup.csh + module use /path/to/modulefiles module load wflow_ Follow any instructions output by the console (e.g., ``conda activate workflow_tools``). diff --git a/docs/UsersGuide/source/Reference/RocotoInfo.rst b/docs/UsersGuide/source/Reference/RocotoInfo.rst index 627969269b..0aee6efda7 100644 --- a/docs/UsersGuide/source/Reference/RocotoInfo.rst +++ b/docs/UsersGuide/source/Reference/RocotoInfo.rst @@ -31,7 +31,7 @@ automatically resubmit failed tasks and can recover from system outages without .. code-block:: console - rocotorun -w -d -v 10 + rocotorun -w /path/to/workflow/xml/file -d /path/to/workflow/database/file -v 10 where @@ -70,7 +70,7 @@ workflow using the ``rocotostat`` command: .. code-block:: console - rocotostat -w -d     + rocotostat -w /path/to/workflow/xml/file -d /path/to/workflow/database/file Executing this command will generate a workflow status table similar to the following: @@ -217,7 +217,7 @@ command will rerun tasks in the workflow. The command line options are the same .. code-block:: console - rocotorewind -w     -d file -c -t + rocotorewind -w /path/to/workflow/xml/file -d /path/to/workflow/database/ 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 diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst index 2677888f5a..f22d915a62 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst @@ -5,7 +5,7 @@ Template Variables ====================== The SRW App's experiment configuration system supports the use of template variables -in ``config_defaults.yaml`` and ``config.yaml``. A template variable --- or "template" --- is an experiment configuration variable that contains references to values of other variables. +in ``config_defaults.yaml`` and ``config.yaml``. A template variable is an experiment configuration variable that contains references to values of other variables. These references are **not** set to the values of the referenced variables (or "expanded") when the experiment's variable definitions file (``var_defns.sh``) is generated or sourced. Instead, they are expanded and evaluated **at run time** when bash's ``eval`` command is used on the template. From 995ccf2a397fd36d09f532c6ae987c5afb07de8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 8 Aug 2023 12:37:11 -0400 Subject: [PATCH 058/116] update file /path/to convention --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 8 ++++---- docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 09c520515d..41f36c0da6 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -506,11 +506,11 @@ Configure a ``macos.yaml`` or ``linux.yaml`` machine file in ``ufs-srweather-app task_make_orog: # Path to location of static input files used by the make_orog task - TOPO_DIR: path/to/FIXgsm/files + FIXorg: path/to/FIXorg/files task_make_sfc_climo: # Path to location of static surface climatology input fields used by sfc_climo_gen - SFC_CLIMO_INPUT_DIR: path/to/FIXgsm/files + FIXsfc: path/to/FIXsfc/files task_run_fcst: FIXaer: /path/to/FIXaer/files @@ -897,13 +897,13 @@ Optionally, an environment variable can be set to navigate to the experiment dir .. code-block:: console - export EXPTDIR=// + export EXPTDIR=/path/to/experiment/directory If the login shell is csh/tcsh, it can be set using: .. code-block:: console - setenv EXPTDIR // + setenv EXPTDIR /path/to/experiment/directory .. _Automate: diff --git a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst index db52de9a10..533f6e7fb2 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst @@ -194,7 +194,7 @@ The plots are created using the graphics generation script that comes with the S .. code-block:: console cd /path/to/ufs-srweather-app/ush/Python - python plot_allvars.py 2019061500 0 60 6 / SUBCONUS_Ind_3km + python plot_allvars.py 2019061500 0 60 6 /path/to/experiment/directory /path/to/NaturalEarth SUBCONUS_Ind_3km Compare ---------- From 67c17af178dc4ea567ac026111ec0d52f78c9859 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 8 Aug 2023 13:04:51 -0400 Subject: [PATCH 059/116] update I/O ch --- .../TinkeringWWflowDetails/ConfigWorkflow.rst | 4 ++-- .../InputOutputFiles.rst | 20 +++++++++---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst index ab8e47d53b..6b73d15a01 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst @@ -937,10 +937,10 @@ These parameters are associated with the fixed (i.e., static) files. On `Level 1 ``FIXshp``: (Default: "") System directory where the graphics shapefiles are located. On Level 1 systems, these are set within the machine files. Users on other systems will need to provide the path to the directory that contains the *Natural Earth* shapefiles. -``TOPO_DIR``: (Default: "") +``FIXorg``: (Default: "") The location on disk of the static input files used by the ``make_orog`` task (i.e., ``orog.x`` and ``shave.x``). Can be the same as ``FIXgsm``. -``SFC_CLIMO_INPUT_DIR``: (Default: "") +``FIXsfc``: (Default: "") The location on disk of the static surface climatology input fields, used by ``sfc_climo_gen``. These files are only used if the ``MAKE_SFC_CLIMO`` task is meant to run. ``SYMLINK_FIX_FILES``: (Default: true) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst index 98fd6f2f85..273af8ac91 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst @@ -180,7 +180,7 @@ After creating the new flat text file to reflect the changes, users will need to which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If ``USE_CUSTOM_POST_CONFIG_FILE`` is set to true, but 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. +After successfully generating the workflow, users may run/monitor their experiment as usual, and the UPP will use the new flat ``*.txt`` file. .. _SatelliteProducts: @@ -230,13 +230,15 @@ Static files are available in the `"fix" directory `__ of the SRW Data Bucket using the ``wget`` command for each required file. A list of ``wget`` commands with links is provided :ref:`here ` for the release v2.1.0 fix file data. Users will need to create an appropriate directory structure for the files when downloading them individually. The best solution is to download the files into directories that mirror the structure of the `Data Bucket `__. -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.yaml``. Add the following code to the ``task_run_fcst:`` section of the ``config.yaml`` file, and alter the variable paths accordingly: +.. COMMENT: Update release file list above for next SRW release. + +The environment variables ``FIXgsm``, ``FIXorg``, and ``FIXsfc`` 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.yaml``. Add the following code to the ``task_run_fcst:`` section of the ``config.yaml`` file, and alter the variable paths accordingly: .. code-block:: console - FIXgsm: - TOPO_DIR: - SFC_CLIMO_INPUT_DIR: + FIXgsm: /path/to/fix/fix_am + FIXorg: /path/to/fix/fix_orog + FIXsfc: /path/to/fix/sfc_climo/ .. _InitialConditions: @@ -265,13 +267,11 @@ The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBC task_get_extrn_ics: USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH - EXTRN_MDL_DATA_STORES: disk task_get_extrn_lbcs: USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH - EXTRN_MDL_DATA_STORES: disk -The two ``EXTRN_MDL_SOURCE_BASEDIR_*CS`` variables describe where the :term:`IC ` and :term:`LBC ` file directories are located, respectively. For ease of reusing ``config.yaml`` across experiments, it is recommended that users set up the raw :term:`IC/LBC ` file paths to include the model name (e.g., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path-to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. +The two ``EXTRN_MDL_SOURCE_BASEDIR_*CS`` variables describe where the :term:`IC ` and :term:`LBC ` file directories are located, respectively. For ease of reusing ``config.yaml`` across experiments, it is recommended that users set up the raw :term:`IC/LBC ` file paths to include the model name (e.g., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path/to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. When files are pulled from NOAA :term:`HPSS` (rather than downloaded from the data bucket), the naming convention looks something like: @@ -373,8 +373,8 @@ It is recommended that users have a separate directory for each file format if t .. code-block:: console - /path-to/input_model_data/FV3GFS/grib2/YYYYMMDDHH - /path-to/input_model_data/FV3GFS/nemsio/YYYYMMDDHH + /path/to/input_model_data/FV3GFS/grib2/YYYYMMDDHH + /path/to/input_model_data/FV3GFS/nemsio/YYYYMMDDHH Additionally, users must set the following environment variables if they plan to use GRIB2-formatted files for FV3GFS: From 351141af13f2acfb5bb17dbf5e02b1fc549e722a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 8 Aug 2023 14:32:55 -0400 Subject: [PATCH 060/116] add FAQ update & link update --- docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst | 2 +- docs/UsersGuide/source/Reference/FAQ.rst | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst index 4829b21774..8a6fd5ec12 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst @@ -96,4 +96,4 @@ For a detailed explanation of how to build and run the SRW App on any supported The workflow must be relaunched regularly and repeatedly until the log output includes a ``Workflow status: SUCCESS`` message indicating that the experiment has finished. -Optionally, users may :ref:`configure their own grid `, instead of using a predefined grid, and/or :ref:`plot the output ` of their experiment(s). +Optionally, users may :ref:`configure their own grid `, instead of using a predefined grid, and/or :ref:`plot the output ` of their experiment(s). diff --git a/docs/UsersGuide/source/Reference/FAQ.rst b/docs/UsersGuide/source/Reference/FAQ.rst index 60ed0290c2..c6d52faa26 100644 --- a/docs/UsersGuide/source/Reference/FAQ.rst +++ b/docs/UsersGuide/source/Reference/FAQ.rst @@ -239,6 +239,10 @@ Follow any instructions output by the console (e.g., ``conda activate workflow_t Then, users can configure a new experiment by updating the environment variables in ``config.yaml`` to reflect the desired experiment configuration. Detailed instructions can be viewed in :numref:`Section %s `. Parameters and valid values are listed in :numref:`Section %s `. After adjusting the configuration file, generate the new experiment by running ``./generate_FV3LAM_wflow.py``. Check progress by navigating to the ``$EXPTDIR`` and running ``rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10``. +.. note:: + + If users have updated their clone of the SRW App (e.g., via ``git pull`` or ``git fetch``/``git merge``) since running their last experiement, and the updates include a change to ``Externals.cfg``, users will need to rerun ``checkout_externals`` (instructions :ref:`here `) and rebuild the SRW App according to the instructions in :numref:`Section %s `. + .. _AddPhys: ==================================================================== From bf48e21d81703c268295c0f45841421bb9bc0e4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 8 Aug 2023 16:17:54 -0400 Subject: [PATCH 061/116] Defining Wflow updates --- .../TinkeringWWflowDetails/DefineWorkflow.rst | 41 +++++++++---------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst index 470d04ea95..1fb748fbc8 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst @@ -4,21 +4,20 @@ Defining an SRW App Workflow ============================= +Many predefined workflows with optional variants exist within the Short-Range Weather Application, but the Application also includes the ability to define a new workflow from scratch. This functionality allows users to add tasks to the workflow to meet their scientific exploration needs. -Rocoto is the primary workflow manager software used by the UFS SRW App. Because the SRW App supports a variety of research and operational configurations, it is important to incorporate the ability to build a static Rocoto XML from scratch. This means a user will be able to specify exactly which tasks are included in the workflow definition from a YAML configuration file. While many predefined workflows will exist with optional variants in the SRW App, additional tasks may be added by individuals for their scientific exploration needs. - -This guide explains how the Rocoto XML is built using a Jinja2 template (`Jinja docs here `__) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation `__ with a few exceptions or additions outlined in this documentation. +Rocoto is the primary workflow manager software used by the UFS SRW App. Rocoto workflows are defined in an XML file (``FV3LAM_wflow.xml``) based on parameters set during experiment generation. This section explains how the Rocoto XML is built using a Jinja2 template (`Jinja docs here `__) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation `__ with a few exceptions or additions outlined in this documentation. The Jinja2 Template =================== -In previous versions of the SRW App, the Jinja2 template to create the Rocoto XML was tightly coupled to specific configuration settings of the SRW App. It was built from a limited, pre-defined set of specific tasks, defining switches for those tasks to be included or not in the rendered XML. +In previous versions of the SRW Application, the Jinja2 template to create the Rocoto XML was tightly coupled to specific configuration settings of the SRW App. It was built from a limited, pre-defined set of specific tasks, defining switches for those tasks to be included or not in the rendered XML. -Now, the Jinja2 template is entirely agnostic to Short-Range Weather Application decisions and has been developed to wrap the features of Rocoto in an extensible, configurable format. +Now, the Jinja2 template is entirely agnostic to SRW Application decisions and has been developed to wrap the features of Rocoto in an extensible, configurable format. -The ``rocoto`` section of ``config.py`` -======================================= +The ``rocoto`` section of ``config.yaml`` +========================================== The structured YAML file that defines the Rocoto XML is meant to reflect the sections required by any Rocoto XML. That structure looks like this, with some example values filled in: .. code-block:: console @@ -32,10 +31,10 @@ The structured YAML file that defines the Rocoto XML is meant to reflect the sec taskthrottle: cycledefs: groupname: - !startstopfreq ['2022102000', ‘2023102018’, ‘06:00:00’] - groupname2: - !startstopfreq ['2022102000', ‘2023102018’, ‘24:00:00’] - !startstopfreq ['2022102006', ‘2023102018’, ‘24:00:00’] + - !startstopfreq ['2022102000', ‘2023102018’, ‘06:00:00’] + groupname2: + - !startstopfreq ['2022102000', ‘2023102018’, ‘24:00:00’] + - !startstopfreq ['2022102006', ‘2023102018’, ‘24:00:00’] entities: foo: 1 bar: “/some/path” @@ -45,22 +44,22 @@ The structured YAML file that defines the Rocoto XML is meant to reflect the sec task_*: metatask_*: -In addition to the structured YAML itself, the SRW App enables additional functionality in defining a YAML file. Often, PyYAML features are introduced and documented `here `__. In the above example, the ``!startstopfreq`` is an example of a PyYAML constructor. Supported constructors will be outlined :ref:`below `. There are also examples of using PyYAML anchors and aliases in the definition of groups of tasks in the SRW App. Please see `this documentation `__ for the behavior of PyYAML anchors and aliases. - -The use of Jinja2 templates inside the values of entries allows for the reference to other keys, mathematical operations, Jinja2 control structures, and the use of user-defined filters. Here, the ``include`` filter in the ``taskgroups`` entry is a user-defined filter. The supported filters are described in a section :ref:`below `. - Under the Rocoto section, several subentries are required. They are described here using similar language as in the Rocoto documentation. ``attrs``: Any of the attributes to the ``workflow`` tag in Rocoto. This is meant to contain a nested dictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. -``cycledefs``: A dictionary with each key defining a group name for a ``cycledef`` tag, where the key’s value is a list of acceptable ``cycledef`` formatted strings. The PyYAML constructor ``!startstopfreq`` has been included here to help with the automated construction of a tag of that nature. The preferred option for the SRW App is to use the “start, stop, step” method. +``cycledefs``: A dictionary in which each key defines a group name for a ``cycledef`` tag; the key’s value is a list of acceptable ``cycledef`` formatted strings. The PyYAML constructor ``!startstopfreq`` has been included here to help with the automated construction of a tag of that nature. The preferred option for the SRW App is to use the “start, stop, step” method. -``entities``: A dictionary with each key defining the name of a Rocoto entity and its value. These variables are referenceable throughout the workflow with the ‘&foo;’ notation. +``entities``: A dictionary in which each key defines the name of a Rocoto entity and its value. These variables are referenceable throughout the workflow with the ``&foo;`` notation. ``log``: The path to the log file. This corresponds to the ```` tag. ``tasks``: This section is where the defined tasks and metatasks are created. This is the main portion of the workflow that will most commonly differ from experiment to experiment with different configurations. +In addition to the structured YAML itself, the SRW App enables additional functionality when defining a YAML file. Often, PyYAML features are introduced and documented `here `__. In the above example, the ``!startstopfreq`` is an example of a PyYAML constructor. Supported constructors will be outlined :ref:`below `. There are also examples of using PyYAML anchors and aliases in the definition of groups of tasks in the SRW App. Please see `this documentation `__ for the behavior of PyYAML anchors and aliases. + +The use of Jinja2 templates inside the values of entries allows for the reference to other keys, mathematical operations, Jinja2 control structures, and the use of user-defined filters. Here, the ``include`` filter in the ``taskgroups`` entry is a user-defined filter. The supported filters are described in a section :ref:`below `. + .. _tasks: The ``tasks`` Subsection @@ -68,9 +67,9 @@ The ``tasks`` Subsection ``taskgroups``: This entry is not a standard Rocoto entry. It defines a set of files that will be included to build a workflow from predefined groups of tasks. The supported groups are included under ``parm/wflow`` for the SRW App, but the paths can point to any location on your local disk. The resulting order of the tasks will be in the same order as defined in this list. The syntax for the “include” is included as a Jinja2 filter. -``task_*``: This is a section header to add a task. The task name will be whatever the section key has defined after the first underscore. For example, “task_run_fcst” will be named “run_fcst” in the resulting workflow. More information about defining a task is included :ref:`below `. +``task_*``: This is a section header to add a task. The task name will be whatever the section key has defined after the first underscore. For example, ``task_run_fcst`` will be named ``run_fcst`` in the resulting workflow. More information about defining a task is included :ref:`below `. -``metatask_*``: This is a section header to add a metatask. The metatask name will be whatever the section key has defined after the first underscore. For example “metatask_run_ensemble” will be named “run_ensemble” in the resulting workflow. More information about defining a metatask is included :ref:`below `. +``metatask_*``: This is a section header to add a metatask. The metatask name will be whatever the section key has defined after the first underscore. For example ``“``metatask_run_ensemble`` will be named ``run_ensemble`` in the resulting workflow. More information about defining a metatask is included :ref:`below `. .. _defining_tasks: @@ -107,7 +106,7 @@ Each task supports any of the tags that are defined in the Rocoto documentation. The following sections are constructs of the interface, while all others are direct translations to tags available in Rocoto. Any tag that allows for attributes to the XML tag will take an ``attrs`` nested dictionary entry. -``attrs``: Any of the attributes to the task tag in Rocoto. This is meant to be a subdictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. This might include any combination of the following: cycledefs, maxtries, throttle, or final. +``attrs``: Any of the attributes to the task tag in Rocoto. This is meant to be a subdictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. Attributes might include any combination of the following: cycledefs, maxtries, throttle, or final. ``envars``: A dictionary of keys that map to variable names that will be exported for the job. These will show up as the set of ```` tags in the XML. The value will be the value of the defined variable when it is exported. @@ -121,7 +120,7 @@ The dependency entry will be an arbitrarily deep nested dictionary of key, value Because we are representing these entries as a dictionary, which requires hashable keys (no repeats at the same level), some tags may need to be differentiated where XML may not differentiate at all. In these instances, it is best practice to name them something descriptive. For example, you might have multiple “or” dependencies at the same level that could be named “or_files_exist” and “or_task_ran”. This style can be adopted whether or not differentiation is needed. -The text entry on some dependencies is for those dependency tags that need the information to come between two flags, as in a data dependency. +The ``text`` entry on some dependencies is for those dependency tags that need the information to come between two flags, as in a data dependency. Otherwise, all dependencies follow the same naming conventions as defined in Rocoto with ``attrs`` dictionaries included to define any of the tag attributes that may be accepted by Rocoto. From c3e0ba0dd720141fb27eae01867fdd7235b6d5b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 9 Aug 2023 07:48:22 -0400 Subject: [PATCH 062/116] Defining Wflow updates --- .../source/TinkeringWWflowDetails/DefineWorkflow.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst index 1fb748fbc8..65a5bc9bee 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst @@ -219,16 +219,16 @@ There is a specific order of precedence imposed when the SRW App loads configura #. Load ``config_defaults.yaml`` file. #. Load the user’s ``config.yaml`` file. -#. Load the workflow defaults YAML file. -#. At this point, all anchors and references will be resolved. -#. All PyYAML constructors will also be called for the data provided in that entry. +#. Load the ``default_workflow.yaml`` file. + + * At this point, all anchors and references will be resolved. + * All PyYAML constructors will also be called for the data provided in that entry. #. Call ``update_dict`` function to remove any null entries from default tasks using the PyYAML anchors. #. Load all files from the ``taskgroups:`` entry from the user’s config or from the default if not overridden. This is achieved with a call to the ``extend_yaml()`` function. #. Add the contents of the files to the ``task:`` section. #. Update the existing workflow configuration with any user-specified entries (removing the ones that are null entries). #. Add a ``jobname:`` entry to every task in the workflow definition section. - -#. Incorporate other default configuration settings from machine files, constants, etc. into the default config dictionary in memory. +#. Incorporate other default configuration settings from machine files, constants, etc. into the default configuration dictionary in memory. #. Apply all user settings last to take highest precedence. #. Call ``extend_yaml()`` to render templates that are available. NOTE: This is the one that is likely to trip up any settings that ``setup.py`` will make. References to other defaults that get changed during the course of validation may be rendered here earlier than desired. From f6d0b9b247333e59c7511282dcc96f95b606b7b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 9 Aug 2023 08:40:13 -0400 Subject: [PATCH 063/116] Intro updates --- .../source/BackgroundInfo/Introduction.rst | 169 ++++++++++-------- 1 file changed, 96 insertions(+), 73 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 3c843c6509..203a47ffe7 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -24,53 +24,53 @@ UFS Development Team. (2022, Nov. 17). Unified Forecast System (UFS) Short-Range User's Guide Organization ============================ -The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Technical Information*; and *Reference*. +The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Tinkering With Workflow Details*; and *Reference*. .. hint:: * To get started with the SRW App, users can try one of the following options: - #. View :numref:`Chapter %s ` for a quick overview of the workflow steps. + #. View :numref:`Section %s: Quick Start Guide ` for a quick overview of the workflow steps. #. To build the application in a container, which provides a more uniform work environment, users can refer to the :ref:`Container-Based Quick Start Guide `. - #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Chapter %s: Building the SRW App ` and :numref:`Chapter %s: Running the SRW App `. + #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Section %s: Building the SRW App ` and :numref:`Section %s: Running the SRW App `. Background Information ------------------------- - * This **Introduction** chapter explains how the SRW App documentation is organized, how to use this guide, and where to find user support/documentation. - * :numref:`Chapter %s: Technical Overview ` provides a technical overview, including SRW App prerequisites and an overview of the code directory structure. - * :numref:`Chapter %s: Components ` provides a detailed description of the application components, including optional application components. + * This **Introduction** section explains how the SRW App documentation is organized, how to use this guide, and where to find user support/documentation. + * :numref:`Section %s: Technical Overview ` provides a technical overview, including SRW App prerequisites and an overview of the code directory structure. + * :numref:`Section %s: SRW Application Components ` provides a detailed description of the application components, including optional application components. Building, Running, and Testing the SRW App -------------------------------------------- - * :numref:`Chapter %s: Quick Start Guide ` is designed for use on `Level 1 systems `__ or as an overview of the workflow. - * :numref:`Chapter %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers come with SRW App prerequisites already installed and run on a broad range of systems. - * :numref:`Chapter %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. - * :numref:`Chapter %s: Running the SRW App ` provides a *detailed* explanation of how to run the App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. - * :numref:`Chapter %s: Testing the SRW App ` explains how to run workflow end-to-end tests to ensure that new developments do not break the current workflow. - * :numref:`Chapter %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. - * :numref:`Chapter %s: METplus Verification Sample Cases ` explains how to run METplus verification as part of the workflow. - * :numref:`Chapter %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this chapter is a starting point for those interested in AQM. + * :numref:`Section %s: Quick Start Guide ` is designed for use on `Level 1 systems `__ or as an overview of the workflow. + * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers come with SRW App prerequisites already installed and run on a broad range of systems. + * :numref:`Section %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. + * :numref:`Section %s: Running the SRW App ` provides a *detailed* explanation of how to run the SRW App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. + * :numref:`Section %s: Testing the SRW App ` explains how to run workflow end-to-end (WE2E) tests to ensure that new developments do not break the current workflow. + * :numref:`Section %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. + * :numref:`Section %s: METplus Verification Sample Cases ` explains how to run METplus verification as part of the workflow. + * :numref:`Section %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this section is a starting point for those interested in AQM. Tinkering with Workflow Details --------------------------------- - * :numref:`Chapter %s: Workflow Parameters ` documents all of the user-configurable experiment parameters that can be set in ``config.yaml``. - * :numref:`Chapter %s: Input & Output Files ` describes application input and output files, as well as information on where to get publicly available data. - * :numref:`Chapter %s: Limited Area Model (LAM) Grids ` describes the SRW App predefined grids in detail and explains how to create a custom user-generated grid. - * :numref:`Chapter %s: Defining an SRW App Workflow ` explains how to build or alter the SRW App workflow XML file. - * :numref:`Chapter %s: Template Variables ` explains how to use template variables. + * :numref:`Section %s: Workflow Parameters ` documents all of the user-configurable experiment parameters that can be set in the user configuration file (``config.yaml``). + * :numref:`Section %s: Input & Output Files ` describes application input and output files, as well as information on where to get publicly available data. + * :numref:`Section %s: Limited Area Model (LAM) Grids ` describes the SRW App predefined grids in detail and explains how to create a custom user-generated grid. + * :numref:`Section %s: Defining an SRW App Workflow ` explains how to build a customized SRW App workflow XML file. + * :numref:`Section %s: Template Variables ` explains how to use template variables. Reference Information ----------------------- - * :numref:`Chapter %s: Rocoto Introductory Information ` provides an introduction to standard Rocoto commands with examples. - * :numref:`Chapter %s: FAQ ` answers users' frequently asked questions. - * :numref:`Chapter %s: Glossary ` defines important terms related to the SRW App. + * :numref:`Section %s: Rocoto Introductory Information ` provides an introduction to standard Rocoto commands with examples. + * :numref:`Section %s: FAQ ` answers users' frequently asked questions. + * :numref:`Section %s: Glossary ` defines important terms related to the SRW App. -How to Use This Document -======================== +SRW App Documentation Conventions +=================================== This guide instructs both novice and experienced users on downloading, building, and running the SRW Application. Please post questions in the `GitHub Discussions `__ forum. @@ -80,64 +80,87 @@ 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, or directories. -Code that includes angle brackets (e.g., ``build__``) indicates that users should insert options appropriate to their SRW App configuration (e.g., ``build_orion_intel``). +Code that includes angle brackets (e.g., ``build__``) indicates that users should insert options appropriate to their SRW App configuration (e.g., ``build_hera_intel``). File or directory paths that begin with ``/path/to/`` should be replaced with the actual path on the user's system. For example, ``/path/to/modulefiles`` might be replaced by ``/Users/Jane.Smith/ufs-srweather-app/modulefiles``. -User Support, Documentation, and Contributions to Development +Component Documentation +========================= + +A list of available component documentation is shown in :numref:`Table %s `. In general, technical documentation will explain how to use a particular component, whereas scientific documentation provides more in-depth information on the science involved in a given file. + +.. _list_of_documentation: + +.. list-table:: Centralized list of documentation + :widths: 20 50 + :header-rows: 1 + + * - Documentation + - Location + * - UFS SRW Application User's Guide + - https://ufs-srweather-app.readthedocs.io/en/develop/ + * - UFS_UTILS Technical Documentation + - https://noaa-emcufs-utils.readthedocs.io/en/latest + * - UFS_UTILS Scientific Documentation + - https://ufs-community.github.io/UFS_UTILS/index.html + * - UFS Weather Model User's Guide + - https://ufs-weather-model.readthedocs.io/en/latest + * - HPC-Stack Documentation + - https://hpc-stack.readthedocs.io/en/latest/ + * - spack-stack Documentation + - https://spack-stack.readthedocs.io/en/latest/ + * - FV3 Scientific Documentation + - https://repository.library.noaa.gov/view/noaa/30725 + * - FV3 Technical Documentation + - https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html + * - CCPP Scientific Documentation + - https://dtcenter.ucar.edu/GMTB/v6.0.0/sci_doc/index.html + * - CCPP Technical Documentation + - https://ccpp-techdoc.readthedocs.io/en/latest/ + * - Stochastic Physics Documentation + - https://stochastic-physics.readthedocs.io/en/latest/ + * - ESMF manual + - https://earthsystemmodeling.org/docs/release/latest/ESMF_usrdoc/ + * - Unified Post Processor User's Guide + - https://upp.readthedocs.io/en/latest/ + * - Unified Post Processor Scientific Documentation + - https://noaa-emc.github.io/UPP/ + * - Unified Workflow User's Guide + - https://unified-workflow.readthedocs.io/en/latest/ + +User Support and Contributions to Development =============================================================== -The SRW App's `GitHub Discussions `__ forum provides online support for UFS users and developers to post questions and exchange information. +Questions +----------- -A list of available documentation is shown in :numref:`Table %s `. +The SRW App's `GitHub Discussions `__ forum provides online support for UFS users and developers to post questions and exchange information. When users are running into difficulties running the workflow, this is the place to post! Users can expect an initial response within two business days. -.. _list_of_documentation: +When posting a question, it is recommended that users provide the following information: + +* The platform or system being used (e.g., Hera, Orion, MacOS, Linux) +* The version of the SRW Application being used (e.g., ``develop``, ``release/public-v2.1.0``). (To determine this, users can run ``git branch``, and the name of the branch with an asterisk ``*`` in front of it is the name of the branch they are working on). Note that the version of the application being used and the version of the documentation being used should match, or users will run into difficulties. +* Stage of the application when the issue appeared (i.e., configuration, build/compilation, or forecast run) +* Configuration file +* Error message or screenshot +* Current shell (e.g., bash, csh) and modules loaded +* Compiler + MPI combination being used + +Bug Reports +------------- + +If users have identified a bug in the system, they can report it as a `GitHub Issue `__. For new users, the best approach is typically to ask about problems in `GitHub Discussions `__ first, since many "bugs" do not require a code change --- instead, the user is unfamiliar with the system an may have misunderstood some component of the system, which is then causing problems. + +Feature Requests +------------------ + +Users who want to request the addition of a new feature can file a `GitHub Issue `__ and add (or request that a code manager add) the ``EPIC Support Requested`` label. These feature requests will be forwarded to the Earth Prediction Innovation Center (EPIC) management team for prioritization and eventual addition to the SRW App. + +Community Contributions +------------------------- -.. table:: Centralized list of documentation - - +----------------------------+---------------------------------------------------------------------------------+ - | **Documentation** | **Location** | - +============================+=================================================================================+ - | UFS SRW Application | https://ufs-srweather-app.readthedocs.io/en/develop/ | - | User's Guide | | - +----------------------------+---------------------------------------------------------------------------------+ - | UFS_UTILS Technical | https://noaa-emcufs-utils.readthedocs.io/en/latest | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | UFS_UTILS Scientific | https://ufs-community.github.io/UFS_UTILS/index.html | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | UFS Weather Model | https://ufs-weather-model.readthedocs.io/en/latest | - | User's Guide | | - +----------------------------+---------------------------------------------------------------------------------+ - | HPC-Stack Documentation | https://hpc-stack.readthedocs.io/en/latest/ | - +----------------------------+---------------------------------------------------------------------------------+ - | spack-stack Documentation | https://spack-stack.readthedocs.io/en/latest/ | - +----------------------------+---------------------------------------------------------------------------------+ - | FV3 Scientific | https://repository.library.noaa.gov/view/noaa/30725 | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | FV3 Technical | https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | CCPP Scientific | https://dtcenter.ucar.edu/GMTB/v6.0.0/sci_doc/index.html | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | CCPP Technical | https://ccpp-techdoc.readthedocs.io/en/latest/ | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | Stochastic Physics | https://stochastic-physics.readthedocs.io/en/latest/ | - | Documentation | | - +----------------------------+---------------------------------------------------------------------------------+ - | ESMF manual | https://earthsystemmodeling.org/docs/release/latest/ESMF_usrdoc/ | - +----------------------------+---------------------------------------------------------------------------------+ - | Unified Post Processor | https://upp.readthedocs.io/en/latest/ | - +----------------------------+---------------------------------------------------------------------------------+ - | Unified Workflow | https://unified-workflow.readthedocs.io/en/latest/ | - +----------------------------+---------------------------------------------------------------------------------+ - The UFS community is encouraged to contribute to the development effort of all related -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 into the authoritative repositories, users must follow the code management rules of each UFS component repository. These rules are usually outlined in the User's Guide (see :numref:`Table %s `) or wiki for each respective repository (see :numref:`Table %s `). Contributions to the `ufs-srweather-app `__ repository should follow the guidelines contained in the `SRW App Contributor's Guide `__. +utilities, model code, and infrastructure. As described above, users can post issues in the SRW App and related GitHub repositories to report bugs or to announce upcoming contributions to the code base. Contributions to the `ufs-srweather-app `__ repository should follow the guidelines contained in the `SRW App Contributor's Guide `__. For code to be accepted into the authoritative repositories, users must follow the code management rules of each UFS component repository. These rules are usually outlined in the User's Guide (see :numref:`Table %s `) or wiki for each respective repository (see :numref:`Table %s `). Future Direction ================= From a8335a1addd676f617a16cd74a1ce583a8076ad4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 9 Aug 2023 17:29:58 -0400 Subject: [PATCH 064/116] Intro updates --- .../source/BackgroundInfo/Introduction.rst | 68 ++++++++++--------- .../source/BuildingRunningTesting/RunSRW.rst | 4 +- .../source/TinkeringWWflowDetails/index.rst | 2 +- 3 files changed, 38 insertions(+), 36 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 203a47ffe7..27f8b568f2 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -26,17 +26,10 @@ User's Guide Organization The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Tinkering With Workflow Details*; and *Reference*. -.. hint:: - * To get started with the SRW App, users can try one of the following options: - - #. View :numref:`Section %s: Quick Start Guide ` for a quick overview of the workflow steps. - #. To build the application in a container, which provides a more uniform work environment, users can refer to the :ref:`Container-Based Quick Start Guide `. - #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Section %s: Building the SRW App ` and :numref:`Section %s: Running the SRW App `. - Background Information ------------------------- - * This **Introduction** section explains how the SRW App documentation is organized, how to use this guide, and where to find user support/documentation. + * This **Introduction** section explains how the SRW App documentation is organized, how to use this guide, and where to find user support and component documentation. * :numref:`Section %s: Technical Overview ` provides a technical overview, including SRW App prerequisites and an overview of the code directory structure. * :numref:`Section %s: SRW Application Components ` provides a detailed description of the application components, including optional application components. @@ -44,14 +37,21 @@ Building, Running, and Testing the SRW App -------------------------------------------- * :numref:`Section %s: Quick Start Guide ` is designed for use on `Level 1 systems `__ or as an overview of the workflow. - * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers come with SRW App prerequisites already installed and run on a broad range of systems. + * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers run on a broad range of systems and come with SRW App prerequisites already installed. * :numref:`Section %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. - * :numref:`Section %s: Running the SRW App ` provides a *detailed* explanation of how to run the SRW App after it has been built. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. + * :numref:`Section %s: Running the SRW App ` provides a *detailed* explanation of how to run the SRW App after it has been built/compiled. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. * :numref:`Section %s: Testing the SRW App ` explains how to run workflow end-to-end (WE2E) tests to ensure that new developments do not break the current workflow. * :numref:`Section %s: Tutorials ` walks users through different SRW App experiment cases and analysis of results. * :numref:`Section %s: METplus Verification Sample Cases ` explains how to run METplus verification as part of the workflow. * :numref:`Section %s: Air Quality Modeling ` provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this section is a starting point for those interested in AQM. +.. hint:: + * To get started with the SRW App, it is recommended that users try one of the following options: + + #. View :numref:`Section %s: Quick Start Guide ` for a quick overview of the workflow steps. + #. To build the application in a container, which provides a more uniform work environment, users can refer to :numref:`Section %s: Container-Based Quick Start Guide `. + #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Section %s: Building the SRW App ` and :numref:`Section %s: Running the SRW App `. + Tinkering with Workflow Details --------------------------------- @@ -72,13 +72,13 @@ Reference Information SRW App Documentation Conventions =================================== -This guide instructs both novice and experienced users on downloading, building, and running the SRW Application. Please post questions in the `GitHub Discussions `__ forum. +This guide uses particular conventions to indicate commands and code snippets, file and directory paths, variables, and options. .. 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, code snippets, etc. -Variables presented as ``AaBbCc123`` in this User's Guide typically refer to variables in scripts, names of files, or directories. +Text rendered as ``AaBbCc123`` typically refers to variables in scripts, names of files, or directories. Code that includes angle brackets (e.g., ``build__``) indicates that users should insert options appropriate to their SRW App configuration (e.g., ``build_hera_intel``). @@ -87,7 +87,7 @@ File or directory paths that begin with ``/path/to/`` should be replaced with th Component Documentation ========================= -A list of available component documentation is shown in :numref:`Table %s `. In general, technical documentation will explain how to use a particular component, whereas scientific documentation provides more in-depth information on the science involved in a given file. +A list of available component documentation is shown in :numref:`Table %s `. In general, technical documentation will explain how to use a particular component, whereas scientific documentation provides more in-depth information on the science involved in specific component files. .. _list_of_documentation: @@ -97,26 +97,24 @@ A list of available component documentation is shown in :numref:`Table %s `__ forum provides online support for UFS users and developers to post questions and exchange information. When users are running into difficulties running the workflow, this is the place to post! Users can expect an initial response within two business days. +The SRW App's `GitHub Discussions `__ forum provides online support for UFS users and developers to post questions and exchange information. When users encounter difficulties running the workflow, this is the place to post! Users can expect an initial response within two business days. When posting a question, it is recommended that users provide the following information: * The platform or system being used (e.g., Hera, Orion, MacOS, Linux) -* The version of the SRW Application being used (e.g., ``develop``, ``release/public-v2.1.0``). (To determine this, users can run ``git branch``, and the name of the branch with an asterisk ``*`` in front of it is the name of the branch they are working on). Note that the version of the application being used and the version of the documentation being used should match, or users will run into difficulties. +* The version of the SRW Application being used (e.g., ``develop``, ``release/public-v2.1.0``). (To determine this, users can run ``git branch``, and the name of the branch with an asterisk ``*`` in front of it is the name of the branch they are working on.) Note that the version of the application being used and the version of the documentation being used should match, or users will run into difficulties. * Stage of the application when the issue appeared (i.e., configuration, build/compilation, or forecast run) -* Configuration file +* Configuration file contents * Error message or screenshot * Current shell (e.g., bash, csh) and modules loaded * Compiler + MPI combination being used @@ -149,18 +151,18 @@ When posting a question, it is recommended that users provide the following info Bug Reports ------------- -If users have identified a bug in the system, they can report it as a `GitHub Issue `__. For new users, the best approach is typically to ask about problems in `GitHub Discussions `__ first, since many "bugs" do not require a code change --- instead, the user is unfamiliar with the system an may have misunderstood some component of the system, which is then causing problems. +If users have identified a bug in the system, they can report it as a `GitHub Issue `__. For new users, the best approach is typically to ask about problems in `GitHub Discussions `__ first, since many "bugs" do not require a code change/fix --- instead, the user is unfamiliar with the system and may have misunderstood some component of the system or the instructions, which is then causing problems. Asking for assistance in a `GitHub Discussion `__ post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code the requires someone to file a `GitHub Issue `__. -Feature Requests ------------------- +Feature Requests and Enhancements +----------------------------------- -Users who want to request the addition of a new feature can file a `GitHub Issue `__ and add (or request that a code manager add) the ``EPIC Support Requested`` label. These feature requests will be forwarded to the Earth Prediction Innovation Center (EPIC) management team for prioritization and eventual addition to the SRW App. +Users who want to request the addition of a new feature can file a `GitHub Issue `__ and add (or request that a code manager add) the ``EPIC Support Requested`` label. These feature requests will be forwarded to the Earth Prediction Innovation Center (`EPIC `__) management team for prioritization and eventual addition to the SRW App. Community Contributions ------------------------- -The UFS community is encouraged to contribute to the development effort of all related -utilities, model code, and infrastructure. As described above, users can post issues in the SRW App and related GitHub repositories to report bugs or to announce upcoming contributions to the code base. Contributions to the `ufs-srweather-app `__ repository should follow the guidelines contained in the `SRW App Contributor's Guide `__. For code to be accepted into the authoritative repositories, users must follow the code management rules of each UFS component repository. These rules are usually outlined in the User's Guide (see :numref:`Table %s `) or wiki for each respective repository (see :numref:`Table %s `). +The UFS community is encouraged to contribute to the development efforts of all related +utilities, model code, and infrastructure. As described above, users can post issues in the SRW App to report bugs or to announce upcoming contributions to the code base. Additionally, users can file issues in component repositories for contributions that directly concern those repositories. Contributions to the `ufs-srweather-app `__ repository should follow the guidelines contained in the `SRW App Contributor's Guide `__. For code to be accepted into a component repository, users must follow the code management rules of that component's authoritative repository. These rules are usually outlined in the User's Guide (see :numref:`Table %s `) or GitHub wiki for each respective repository (see :numref:`Table %s `). Future Direction ================= diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 176e797a40..07741a9f1e 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -754,9 +754,9 @@ Description of Workflow Tasks .. _WorkflowTasksFig: .. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW_wflow_flowchart.png - :alt: Flowchart of the workflow tasks. If the make_grid, make_orog, and make_sfc_climo tasks are toggled off, they will not be run. If toggled on, make_grid, make_orog, and make_sfc_climo will run consecutively by calling the corresponding exregional script in the scripts directory. The get_ics, get_lbcs, make_ics, make_lbcs, and run_fcst tasks call their respective exregional scripts. The run_post task will run, and if METplus verification tasks have been configured, those will run during post-processing by calling their exregional scripts. + :alt: Flowchart of the default workflow tasks. If the make_grid, make_orog, and make_sfc_climo tasks are toggled off, they will not be run. If toggled on, make_grid, make_orog, and make_sfc_climo will run consecutively by calling the corresponding exregional script in the scripts directory. The get_ics, get_lbcs, make_ics, make_lbcs, and run_fcst tasks call their respective exregional scripts. The run_post task will run, and if METplus verification tasks have been configured, those will run during post-processing by calling their exregional scripts. - *Flowchart of the Workflow Tasks* + *Flowchart of the Default Workflow Tasks* The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``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 ``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. diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/index.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/index.rst index 2323bef3b9..f272c6e220 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/index.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/index.rst @@ -1,4 +1,4 @@ -Tinkering with Workflow Details +Tinkering With Workflow Details ================================== .. toctree:: From a8f0b81b713d3b9ec2d27a409f95f856727d130a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 9 Aug 2023 22:23:58 -0400 Subject: [PATCH 065/116] minor details --- .../source/BackgroundInfo/Introduction.rst | 6 +++--- .../source/BackgroundInfo/TechnicalOverview.rst | 6 +++++- .../source/BuildingRunningTesting/AQM.rst | 6 +++--- .../source/BuildingRunningTesting/BuildSRW.rst | 2 -- .../source/TinkeringWWflowDetails/.DS_Store | Bin 6148 -> 0 bytes 5 files changed, 11 insertions(+), 9 deletions(-) delete mode 100644 docs/UsersGuide/source/TinkeringWWflowDetails/.DS_Store diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 27f8b568f2..c7a3a25715 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -136,7 +136,7 @@ User Support and Contributions to Development Questions ----------- -The SRW App's `GitHub Discussions `__ forum provides online support for UFS users and developers to post questions and exchange information. When users encounter difficulties running the workflow, this is the place to post! Users can expect an initial response within two business days. +The SRW App's `GitHub Discussions `__ forum provides online support for UFS users and developers to post questions and exchange information. When users encounter difficulties running the workflow, this is the place to post. Users can expect an initial response within two business days. When posting a question, it is recommended that users provide the following information: @@ -151,12 +151,12 @@ When posting a question, it is recommended that users provide the following info Bug Reports ------------- -If users have identified a bug in the system, they can report it as a `GitHub Issue `__. For new users, the best approach is typically to ask about problems in `GitHub Discussions `__ first, since many "bugs" do not require a code change/fix --- instead, the user is unfamiliar with the system and may have misunderstood some component of the system or the instructions, which is then causing problems. Asking for assistance in a `GitHub Discussion `__ post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code the requires someone to file a `GitHub Issue `__. +If users have identified a bug in the system, they can report it as a `GitHub Issue `__. For new users, the best approach is typically to ask about problems in `GitHub Discussions `__ first, since many "bugs" do not require a code change/fix --- instead, the user is unfamiliar with the system and may have misunderstood some component of the system or the instructions, which is causing them problems. Asking for assistance in a `GitHub Discussion `__ post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code the requires the user to file a `GitHub Issue `__. Feature Requests and Enhancements ----------------------------------- -Users who want to request the addition of a new feature can file a `GitHub Issue `__ and add (or request that a code manager add) the ``EPIC Support Requested`` label. These feature requests will be forwarded to the Earth Prediction Innovation Center (`EPIC `__) management team for prioritization and eventual addition to the SRW App. +Users who want to request a feature enhancement or the addition of a new feature can file a `GitHub Issue `__ and add (or request that a code manager add) the ``EPIC Support Requested`` label. These feature requests will be forwarded to the Earth Prediction Innovation Center (`EPIC `__) management team for prioritization and eventual addition to the SRW App. Community Contributions ------------------------- diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index fb9a42dfd6..17c41e0c26 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -19,7 +19,7 @@ The instructions in this documentation assume that users have certain background * Familiarity with LINUX/UNIX systems * Command line basics * System configuration knowledge (e.g., compilers, environment variables, paths, etc.) -* Numerical Weather Prediction (concepts of parameterizations: physical, microphysical, convective) +* Numerical Weather Prediction (e.g., concepts of parameterizations: physical, microphysical, convective) * Meteorology (in particular, meteorology at the scales being predicted: 25km, 13km, and 3km resolutions) Additional background knowledge in the following areas could be helpful: @@ -158,7 +158,11 @@ The ``ufs-srweather-app`` :term:`umbrella repository` is an NCO-compliant reposi ├── (lib) ├── manage_externals ├── modulefiles + │ ├── build__.lua + │ └── wflow_.lua ├── parm + │ ├── wflow + │ └── FV3LAM_wflow.xml ├── (share) ├── scripts ├── sorc diff --git a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst index b86786e17a..b295b2df44 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/AQM.rst @@ -119,10 +119,10 @@ The community AQM configuration assumes that users have :term:`HPSS` access and USE_USER_STAGED_EXTRN_FILES: true EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/data -On Hera, users can find :term:`ICs/LBCs` at ``/scratch2/NCEPDEV/naqfc/RRFS_CMAQ/GFS_DATA/gfs.20230217/{hh}/atmos``. +On Level 1 systems, users can find :term:`ICs/LBCs` in the usual :ref:`input data locations ` under ``FV3GFS/netcdf/2023021700`` and ``FV3GFS/netcdf/2023021706``. -.. COMMENT: Get data locations!!! Add data to the SRW NODD bucket. - Users can find the data required for the community experiment in the `NOAA Global Forecast System Data Bucket `__. --> bucket is empty. +.. COMMENT: Add data to the SRW NODD bucket. Is it on NOAA Cloud? + Users can find the data required for the community experiment in the `UFS SRW App Data Bucket `__. Users may also wish to change :term:`cron`-related parameters in ``config.yaml``. In the ``config.aqm.community.yaml`` file, which was copied into ``config.yaml``, cron is used for automatic submission and resubmission of the workflow: diff --git a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst index c75b623b24..b54b97a156 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst @@ -295,8 +295,6 @@ After running ``devbuild.sh``, the executables listed in :numref:`Table %s 1EVcg1w*X?ZBX1u;EFVxyw5RSA)6Wvf@K>T>Z8y~Pz#yX?Lb>z8FX9Gv5;~0m0);?FTEbq0D zSH&4;x#J2lTyYIuoD-F=1*{ocpO&>;oB?OR8TcIr*t1pE)(zb{1I~amFl9i$4+&K< zjhGvTPX|pn0uak|2jN(M4>c!=m`2PEd50pFO0-moM+~ua`jZ%!M$8Q@9TE>85@(ip zLXj{#>n9-`k{Y^o2AqLe23G8{s{Ma|`T2h~$*-INXW(BkAm!$1v%yD-y>;&4wAUuo qOR9>-<%ZJ~4niwtthVB9Y7qJp9T3xqxgk9i{}Bi@xN!!4l!15ug?5(! From 6d309544e65beb5d5559fdfb533f930bad8ebcad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 9 Aug 2023 22:29:52 -0400 Subject: [PATCH 066/116] fix typo --- .../UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst index 65a5bc9bee..4ea8f7052d 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst @@ -69,7 +69,7 @@ The ``tasks`` Subsection ``task_*``: This is a section header to add a task. The task name will be whatever the section key has defined after the first underscore. For example, ``task_run_fcst`` will be named ``run_fcst`` in the resulting workflow. More information about defining a task is included :ref:`below `. -``metatask_*``: This is a section header to add a metatask. The metatask name will be whatever the section key has defined after the first underscore. For example ``“``metatask_run_ensemble`` will be named ``run_ensemble`` in the resulting workflow. More information about defining a metatask is included :ref:`below `. +``metatask_*``: This is a section header to add a metatask. The metatask name will be whatever the section key has defined after the first underscore. For example ``metatask_run_ensemble`` will be named ``run_ensemble`` in the resulting workflow. More information about defining a metatask is included :ref:`below `. .. _defining_tasks: From 0ea850a7044511bbd7efdcc2b0f89d849c603f4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 10 Aug 2023 16:59:45 -0400 Subject: [PATCH 067/116] revert changes to align w/v2.1.0 stable code --- docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst index cf270611db..533f6e7fb2 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst @@ -110,11 +110,7 @@ where ``/path/to/ufs-srweather-app/ush`` is replaced by the actual path to the ` Then, edit the configuration file (``config.yaml``) to include the variables and values in the sample configuration excerpt below (variables not listed below do not need to be changed or removed). Users must be sure to substitute values in ``<>`` with values appropriate to their system. .. note:: -<<<<<<< HEAD:docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst Users working on a `Level 1 platform `__ do not need to add or update the following variables: ``MET_INSTALL_DIR``, ``METPLUS_PATH``, ``MET_BIN_EXEC``, ``CCPA_OBS_DIR``, ``MRMS_OBS_DIR``, and ``NDAS_OBS_DIR``. -======= - Variables ``CCPA_OBS_DIR``, ``MRMS_OBS_DIR``, and ``NDAS_OBS_DIR`` are set in the ./ush/machine/.yaml configuration. Variables ``MET_INSTALL_DIR``, ``METPLUS_PATH``, ``MET_BIN_EXEC`` are set in modulefiles for met/xx.x.x and metplus/x.x.x, when the modules are loaded in ./modulefiles/tasks//run_vx.local (run_vx.local.lua modulefile) ->>>>>>> f2abb865ce4e380e824dcd450e4a2ac511052bca:docs/UsersGuide/source/VXCases.rst .. code-block:: console @@ -122,7 +118,6 @@ Then, edit the configuration file (``config.yaml``) to include the variables and ACCOUNT: platform: MODEL: FV3_GFS_v16_SUBCONUS_3km -<<<<<<< HEAD:docs/UsersGuide/source/BuildingRunningTesting/VXCases.rst MET_INSTALL_DIR: /path/to/met/x.x.x # Example: MET_INSTALL_DIR: /contrib/met/10.1.1 METPLUS_PATH: /path/to/METplus/METplus-x.x.x # Example: METPLUS_PATH: /contrib/METplus/METplus-4.1.1 # Add MET_BIN_EXEC variable to config.yaml @@ -130,8 +125,6 @@ Then, edit the configuration file (``config.yaml``) to include the variables and CCPA_OBS_DIR: /path/to/Indy-Severe-Weather/obs_data/ccpa/proc MRMS_OBS_DIR: /path/to/Indy-Severe-Weather/obs_data/mrms/proc NDAS_OBS_DIR: /path/to/Indy-Severe-Weather/obs_data/ndas/proc -======= ->>>>>>> f2abb865ce4e380e824dcd450e4a2ac511052bca:docs/UsersGuide/source/VXCases.rst workflow: EXPT_SUBDIR: DATE_FIRST_CYCL: '2019061500' From ab6d093d5356836b034111db0c31dda00a6f8386 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 11 Aug 2023 10:32:13 -0400 Subject: [PATCH 068/116] add prdgen def --- docs/UsersGuide/source/Reference/FAQ.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/Reference/FAQ.rst b/docs/UsersGuide/source/Reference/FAQ.rst index c6d52faa26..be5dfcc3b1 100644 --- a/docs/UsersGuide/source/Reference/FAQ.rst +++ b/docs/UsersGuide/source/Reference/FAQ.rst @@ -88,7 +88,7 @@ The ``/parm/wflow`` directory contains several ``YAML`` files that configure dif * - post.yaml - Post-processing tasks * - prdgen.yaml - - + - Horizontal map projection processor that creates smaller domain products from the larger domain created by the UPP. * - prep.yaml - Pre-processing tasks * - verify_det.yaml @@ -98,8 +98,6 @@ The ``/parm/wflow`` directory contains several ``YAML`` files that configure dif * - verify_pre.yaml - Verification pre-processing tasks -.. COMMENT: What does prdgen.yaml do? - The default workflow task groups are set in ``parm/wflow/default_workflow.yaml`` and include ``prep.yaml``, ``coldstart.yaml``, and ``post.yaml``. Changing this list of task groups in the user configuration file (``config.yaml``) will override the default and run only the task groups listed. For example, to omit :term:`cycle-independent` tasks and run plotting tasks, users would delete ``prep.yaml`` from the list of tasks and add ``plot.yaml``: .. code-block:: console From 95f717974d7ed8dcdbd812bdf20cb69b7a74e75e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 14 Aug 2023 18:55:33 -0400 Subject: [PATCH 069/116] rm mention of any required file structure for *_OBS_DIR paths --- .../source/TinkeringWWflowDetails/ConfigWorkflow.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst index 0f56413560..0ffb4e1e2f 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst @@ -141,7 +141,7 @@ METplus Parameters ``CCPA_OBS_DIR``: (Default: "") 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 :term:`HPSS` (if the user has access) via the ``get_obs_ccpa`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). - METplus configuration files require the use of a 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. In NCO mode, this path must be defined as ``//ccpa/proc``. METplus is configured to verify 01-, 03-, 06-, and 24-h accumulated precipitation using hourly CCPA files. + METplus configuration files require the use of a 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. 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) for dates up until 2021-05-04. The script to pull the CCPA data from the NOAA HPSS (``scripts/exregional_get_verif_obs.sh``) has an example of how to account for this and organize the data into a more intuitive format. @@ -149,13 +149,13 @@ METplus Parameters ``NOHRSC_OBS_DIR``: (Default: "") User-specified location of top-level directory where NOHRSC 06- and 24-hour snowfall accumulation files (available every 6 and 12 hours respectively) 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 :term:`HPSS` (if the user has access) via the ``get_obs_nohrsc`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). - METplus configuration files require the use of a predetermined directory structure and file names. If the NOHRSC files are user-provided, they need to follow the anticipated naming structure: ``{YYYYMMDD}/sfav2_CONUS_{AA}h_{YYYYMMDD}{HH}_grid184.grb2``, where AA is the 2-digit accumulation duration, and 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 ``NOHRSC_OBS_DIR`` directory. In NCO mode, this path must be defined as ``//nohrsc/proc``. METplus is configured to verify 06-, and 24-h accumulated precipitation using NOHRSC files. + METplus configuration files require the use of a predetermined directory structure and file names. If the NOHRSC files are user-provided, they need to follow the anticipated naming structure: ``{YYYYMMDD}/sfav2_CONUS_{AA}h_{YYYYMMDD}{HH}_grid184.grb2``, where AA is the 2-digit accumulation duration, and 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 ``NOHRSC_OBS_DIR`` directory. METplus is configured to verify 06-, and 24-h accumulated precipitation using NOHRSC files. .. note:: Due to limited availability of NOHRSC observation data on NOAA HPSS, and the likelihood that snowfall acumulation verification will not be desired outside of winter cases, this verification option is currently not present in the workflow by default. In order to use it, the verification environment variable VX_FIELDS should be updated to include ``ASNOW``. This will allow the related workflow tasks to be run. ``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 :term:`HPSS` (if the user has access) via the ``get_obs_mrms`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. Please note, in NCO mode, this path must be defined as ``//mrms/proc``. + 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 :term:`HPSS` (if the user has access) via the ``get_obs_mrms`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. 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 `. @@ -163,7 +163,7 @@ METplus Parameters METplus is configured to look for a MRMS composite reflectivity file for the valid time of the forecast being verified, which is why the minutes and seconds of the filename are hard-coded as "0000". Because MRMS composite reflectivity files do not typically match the valid time exactly, a script (``ush/mrms_pull_topofhour.py``) is called from within the MRMS task that identifies and renames the MRMS file nearest to the valid time to match the valid time of the forecast. This script can also be called separately for staging data independently of the workflow. ``NDAS_OBS_DIR``: (Default: "") - User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``get_obs_ndas`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. Please note, in NCO mode, this path must be defined as ``//ndas/proc``. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. + User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``get_obs_ndas`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. METplus configuration files require the use of predetermined file names. Therefore, if the NDAS files are user-provided, they need to follow the anticipated naming structure: ``prepbufr.ndas.{YYYYMMDDHH}``, where YYYYMMDDHH is as described in the note :ref:`above `. The script to pull the NDAS data from the NOAA HPSS (``scripts/exregional_get_verif_obs.sh``) has an example of how to rename the NDAS data into a more intuitive format with the valid time listed in the file name. From a6860453fdab68119a34a8c3caae0078a2e93bb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 15 Aug 2023 16:40:30 -0400 Subject: [PATCH 070/116] rm mentions of GSI/rrfs-utl --- .../source/BackgroundInfo/Components.rst | 14 ---- .../BuildingRunningTesting/BuildSRW.rst | 80 +------------------ 2 files changed, 1 insertion(+), 93 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Components.rst b/docs/UsersGuide/source/BackgroundInfo/Components.rst index 67ee606ffb..d49ff3767d 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Components.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Components.rst @@ -83,20 +83,6 @@ The NOAA Emission and eXchange Unified System (NEXUS) is an emissions processing For more information on NEXUS, visit the GitHub repository at https://github.com/noaa-oar-arl/NEXUS. -Gridpoint Statistical Interpolation (GSI) -============================================ - -The Gridpoint Statistical Interpolation (GSI) system is a variational :term:`data assimilation` (DA) system that provides 3DVar DA capabilities for the SRW App. It takes a set of observations along with an initial 6-hour forecast from the SRW App and generates an "analysis," which combines the forecast results with observational data to generate a starting point for a new regional forecast. - -GSI is also capable of providing 3D ensemble-variational (3DEnVar) DA, as well as 4D (hourly) variational (4DVar) and ensemble-variational (4DEnVar) DA, but these features have not yet been incorporated into the SRW App. - -In the future, GSI may be phased out in favor of :term:`JEDI`, and the UFS community welcomes contributions that will facilitate this shift! In the meantime, users can find more information about GSI on GitHub at https://github.com/NOAA-EMC/GSI. - -RRFS Utilities -================ - -The Rapid Refresh Forecast System (RRFS) Utilities (rrfs_utl) are a set of tools that that perform tasks required for implementing RRFS capabilities in the SRW App. For example, rrfs_utl performs preprocessing for lightning data, METAR cloud observations, NASA LaRC cloud products, and the NSSL radar reflectivity mosaic. It also provides cloud analysis for the FV3 dycore and radar reflectivity to temperature tendency conversions. For more information on RRFS Utilities, visit the GitHub repository at https://github.com/NOAA-GSL/rrfs_utl or see :numref:`Table %s ` for a detailed description of executables. - .. _uwtools: Unified Workflow Tools diff --git a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst index b54b97a156..fd7291f546 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst @@ -211,27 +211,7 @@ where valid values are ``intel`` or ``gnu``. 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. -If users want to build the optional ``GSI`` and ``rrfs_utl`` components for :term:`RRFS` capabilities, they can pass the ``gsi`` and ``rrfs_utils`` arguments to ``devbuild.sh``. For example: - -.. code-block:: console - - ./devbuild.sh -p=hera gsi rrfs_utils - -.. note:: - RRFS capabilities are currently build-only features. They are not yet available for use at runtime. - -.. COMMENT: Is this still true? - -The last few lines of the RRFS console output should be: - -.. code-block:: console - - [100%] Built target RRFS_UTILS - Install the project... - -- Install configuration: "RELEASE" - -- Installing: /path/to/ufs-srweather-app/exec/ufs_srweather_app.settings - -After running ``devbuild.sh``, the executables listed in :numref:`Table %s ` should appear in the ``ufs-srweather-app/exec`` directory. If users choose to build the ``GSI`` and ``rrfs_utils`` components, the executables listed in :numref:`Table %s ` will also appear there. If the ``devbuild.sh`` build method does not work, or if users are not on a supported machine, they will have to manually set up the environment and build the SRW App binaries with CMake as described in :numref:`Section %s `. +After running ``devbuild.sh``, the executables listed in :numref:`Table %s ` should appear in the ``ufs-srweather-app/exec`` directory. If the ``devbuild.sh`` build method does not work, or if users are not on a supported machine, they will have to manually set up the environment and build the SRW App binaries with CMake as described in :numref:`Section %s `. .. _ExecDescription: @@ -295,64 +275,6 @@ After running ``devbuild.sh``, the executables listed in :numref:`Table %s Date: Tue, 15 Aug 2023 23:32:55 -0600 Subject: [PATCH 071/116] Updates to WE2E tests --- docs/UsersGuide/source/tables/Tests.csv | 42 +++++++++++++++---------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/UsersGuide/source/tables/Tests.csv b/docs/UsersGuide/source/tables/Tests.csv index dce4a03fc0..94ca55bb03 100644 --- a/docs/UsersGuide/source/tables/Tests.csv +++ b/docs/UsersGuide/source/tables/Tests.csv @@ -2,30 +2,33 @@ yes,yes,grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta,RRFS_CONUScompact_25km,FV3_RRFS_v1beta,HRRR,RAP,2020081000,3,8,22, yes,yes,nco_grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_timeoffset_suite_GFS_v16,RRFS_CONUS_25km,FV3_GFS_v16,FV3GFS,FV3GFS,2022081012,6,10,15, yes,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v15p2,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019070100,6,7,10, -yes,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v17_p8,RRFS_CONUS_25km,FV3_GFS_v17_p8,FV3GFS,FV3GFS,2019070100,6,11,15, +yes,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v17_p8_plot,RRFS_CONUS_25km,FV3_GFS_v17_p8,FV3GFS,FV3GFS,2019070100,6,11,15, yes,yes,grid_RRFS_CONUScompact_25km_ics_HRRR_lbcs_HRRR_suite_HRRR,RRFS_CONUScompact_25km,FV3_HRRR,HRRR,HRRR,2020081000,24,26,20 yes,yes,grid_SUBCONUS_Ind_3km_ics_HRRR_lbcs_RAP_suite_WoFS_v0,SUBCONUS_Ind_3km,FV3_WoFS_v0,HRRR,RAP,2020081000,6,13,20, yes,yes,grid_RRFS_CONUS_25km_ics_NAM_lbcs_NAM_suite_GFS_v16,RRFS_CONUS_25km,FV3_GFS_v16,NAM,NAM,2021051212,6,17,25 ,yes,community,RRFS_CONUS_25km,FV3_GFS_v16,FV3GFS,FV3GFS,2019061518,12,17,, -,yes,custom_ESGgrid,*custom*,FV3_GFS_2017_gfdlmp_regional,FV3GFS,FV3GFS,2019070100,6,11,, -,yes,custom_GFDLgrid,*custom*,FV3_GFS_2017_gfdlmp,FV3GFS,FV3GFS,2019070100,6,10,19, -,yes,custom_GFDLgrid__GFDLgrid_USE_NUM_CELLS_IN_FILENAMES_eq_FALSE,*custom*,FV3_GFS_2017_gfdlmp,FV3GFS,FV3GFS,2019070100,6,11,, +,yes,custom_ESGgrid,*custom*,FV3_HRRR,FV3GFS,FV3GFS,2019070100,6,11,, +,yes,custom_ESGgrid_Central_Asia_3km,*custom*,FV3_GFS_v15_thompson_mynn_lam3km,FV3GFS,FV3GFS,2019070100,6,30,, +,yes,custom_ESGgrid_IndianOcean_6km,*custom*,FV3_RRFS_v1beta,FV3GFS,FV3GFS,2019061518,12,15,, +,yes,custom_ESGgrid_NewZealand_3km,*custom*,FV3_HRRR,FV3GFS,FV3GFS,2019061518,6,58,, +,yes,custom_ESGgrid_Peru_12km,*custom*,FV3_RAP,FV3GFS,FV3GFS,2019061500,12,18,, +,yes,custom_ESGgrid_SF_1p1km,*custom*,FV3_WoFS_v0,FV3GFS,FV3GFS,2019061500,6,173,, +,yes,custom_GFDLgrid,*custom*,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019070100,6,10,19, +,yes,custom_GFDLgrid__GFDLgrid_USE_NUM_CELLS_IN_FILENAMES_eq_FALSE,*custom*,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019070100,6,11,, ,yes,deactivate_tasks,RRFS_CONUS_25km,FV3_GFS_v15p2,*pregen*,*pregen*,2019070100,6,1,19, ,yes,grid_CONUS_25km_GFDLgrid_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16,CONUS_25km_GFDLgrid,FV3_GFS_v16,FV3GFS,FV3GFS,2019070100,6,8,20, ,yes,grid_CONUS_3km_GFDLgrid_ics_FV3GFS_lbcs_FV3GFS_suite_RRFS_v1beta,CONUS_3km_GFDLgrid,FV3_RRFS_v1beta,FV3GFS,FV3GFS,2019070100,3,260,38, -,yes,grid_RRFS_AK_13km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16,RRFS_AK_13km,FV3_GFS_v16,FV3GFS,FV3GFS,2019070100,6,135,45, +,yes,grid_RRFS_AK_13km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16_plot,RRFS_AK_13km,FV3_GFS_v16,FV3GFS,FV3GFS,2019070100,6,135,45, ,yes,grid_RRFS_AK_3km_ics_FV3GFS_lbcs_FV3GFS_suite_HRRR,RRFS_AK_3km,FV3_HRRR,FV3GFS,FV3GFS,2019070100,3,450,65, -,yes,grid_RRFS_CONUS_13km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v15p2,RRFS_CONUS_13km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019070100,6,13,17, -,yes,grid_RRFS_CONUS_13km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16,RRFS_CONUS_13km,FV3_GFS_v16,FV3GFS,FV3GFS,2019070100,6,27,18, +,yes,grid_RRFS_CONUS_13km_ics_FV3GFS_lbcs_FV3GFS_suite_RAP,RRFS_CONUS_13km,FV3_RAP,FV3GFS,FV3GFS,2019070100,6,13,17, +,yes,grid_RRFS_CONUS_13km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16_plot,RRFS_CONUS_13km,FV3_GFS_v16,FV3GFS,FV3GFS,2019070100,6,27,18, ,yes,grid_RRFS_CONUS_13km_ics_FV3GFS_lbcs_FV3GFS_suite_HRRR,RRFS_CONUS_13km,FV3_HRRR,FV3GFS,FV3GFS,2019070100,6,27,20, ,yes,grid_RRFS_CONUS_13km_ics_FV3GFS_lbcs_FV3GFS_suite_RRFS_v1beta,RRFS_CONUS_13km,FV3_RRFS_v1beta,FV3GFS,FV3GFS,2019070100,6,27,20, -,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_2017_gfdlmp_regional_plot,RRFS_CONUS_25km,FV3_GFS_2017_gfdlmp_regional,FV3GFS,FV3GFS,2019070100,6,7,20, ,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_2017_gfdlmp,RRFS_CONUS_25km,FV3_GFS_2017_gfdlmp,FV3GFS,FV3GFS,2019070112 2019070200,6,39,24, ,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16,RRFS_CONUS_25km,FV3_GFS_v16,FV3GFS,FV3GFS,2019070100,6,5,23, -,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_HRRR,RRFS_CONUS_25km,FV3_HRRR,FV3GFS,FV3GFS,2019070100,6,10,37, +,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_HRRR,RRFS_CONUS_25km,FV3_HRRR,FV3GFS,FV3GFS,2019070100,6,15,30, ,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_FV3GFS_suite_RRFS_v1beta,RRFS_CONUS_25km,FV3_RRFS_v1beta,FV3GFS,FV3GFS,2019070100,6,12,34, -,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_RAP_suite_HRRR,RRFS_CONUS_25km,FV3_HRRR,FV3GFS,RAP,2019061518,6,18,45, -,yes,grid_RRFS_CONUS_25km_ics_GSMGFS_lbcs_GSMGFS_suite_GFS_2017_gfdlmp,RRFS_CONUS_25km,FV3_GFS_2017_gfdlmp,GSMGFS,GSMGFS,2019052000,6,9,23, +,yes,grid_RRFS_CONUS_25km_ics_FV3GFS_lbcs_RAP_suite_RAP,RRFS_CONUS_25km,FV3_RAP,FV3GFS,RAP,2019061518,6,18,45, ,yes,grid_RRFS_CONUS_25km_ics_GSMGFS_lbcs_GSMGFS_suite_GFS_v15p2,RRFS_CONUS_25km,FV3_GFS_v15p2,GSMGFS,GSMGFS,2019052000,6,7,19, ,yes,grid_RRFS_CONUS_25km_ics_NAM_lbcs_NAM_suite_RRFS_v1beta,RRFS_CONUS_25km,FV3_RRFS_v1beta,NAM,NAM,2021061500,6,15,31, ,yes,grid_RRFS_CONUS_3km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v15p2,RRFS_CONUS_3km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019070100,6,250,35, @@ -38,15 +41,16 @@ yes,yes,grid_RRFS_CONUS_25km_ics_NAM_lbcs_NAM_suite_GFS_v16,RRFS_CONUS_25km,FV3_ ,yes,grid_RRFS_CONUScompact_13km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta,RRFS_CONUScompact_13km,FV3_RRFS_v1beta,HRRR,RAP,2020080100,6,25,20, ,yes,grid_RRFS_CONUScompact_25km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16,RRFS_CONUScompact_25km,FV3_GFS_v16,FV3GFS,FV3GFS,2019070100,6,10,22, ,yes,grid_RRFS_CONUScompact_3km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16,RRFS_CONUScompact_3km,FV3_GFS_v16,FV3GFS,FV3GFS,2019070100,3,285,51, -,yes,grid_RRFS_CONUScompact_3km_ics_HRRR_lbcs_RAP_suite_HRRR,RRFS_CONUScompact_3km,FV3_HRRR,HRRR,RAP,2020081000,6,340,1:00, +,yes,grid_RRFS_CONUScompact_3km_ics_HRRR_lbcs_RAP_suite_HRRR,RRFS_CONUScompact_3km,FV3_HRRR,HRRR,RAP,2020081000,6,340,60, ,yes,grid_RRFS_CONUScompact_3km_ics_HRRR_lbcs_RAP_suite_RRFS_v1beta,RRFS_CONUScompact_3km,FV3_RRFS_v1beta,HRRR,RAP,2020080100,6,335,53, -,yes,grid_RRFS_NA_13km_ics_FV3GFS_lbcs_FV3GFS_suite_RRFS_v1beta,RRFS_NA_13km,FV3_RRFS_v1beta,FV3GFS,FV3GFS,2019070100,6,100,36, +,yes,grid_RRFS_NA_13km_ics_FV3GFS_lbcs_FV3GFS_suite_FV3_RAP,RRFS_NA_13km,FV3_RAP,FV3GFS,FV3GFS,2019070100,6,100,36, ,yes,grid_SUBCONUS_Ind_3km_ics_FV3GFS_lbcs_FV3GFS_suite_WoFS_v0,SUBCONUS_Ind_3km,FV3_WoFS_v0,FV3GFS,FV3GFS,2019061500,6,14,23, ,yes,grid_SUBCONUS_Ind_3km_ics_HRRR_lbcs_HRRR_suite_HRRR,SUBCONUS_Ind_3km,FV3_HRRR,HRRR,HRRR,2020081000,3,17,23, ,yes,grid_SUBCONUS_Ind_3km_ics_NAM_lbcs_NAM_suite_GFS_v16,SUBCONUS_Ind_3km,FV3_GFS_v16,NAM,NAM,2021061500,6,13,41, ,yes,grid_SUBCONUS_Ind_3km_ics_RAP_lbcs_RAP_suite_RRFS_v1beta,SUBCONUS_Ind_3km,FV3_RRFS_v1beta,RAP,RAP,2020080103,3,20,22, ,yes,GST_release_public_v1,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019061500,48,31,35, -,yes,MET_verification_only_vx,RRFS_CONUS_25km,*none*,*none*,*none*,2019061500,6,1,08,Runs verification tasks on staged data without running the rest of the workflow +,yes,MET_ensemble_verification_only_vx,RRFS_CONUS_25km,*none*,*none*,*none*,2019061500,6,1,15,Runs ensemble verification tasks on staged data without running the rest of the workflow +,yes,MET_verification_only_vx,RRFS_CONUS_25km,*none*,*none*,*none*,2019061500,6,1,8,Runs verification tasks on staged data without running the rest of the workflow ,yes,nco,RRFS_CONUS_25km,FV3_GFS_v16,FV3GFS,FV3GFS,2022040700,6,7,20, ,yes,nco_ensemble,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019070100 2019070112 2019070200 2019070212,6,55,20, ,yes,nco_grid_RRFS_CONUS_13km_ics_FV3GFS_lbcs_FV3GFS_suite_GFS_v16,RRFS_CONUS_13km,FV3_GFS_v16,FV3GFS,FV3GFS,2019061500,6,26,20, @@ -55,16 +59,20 @@ yes,yes,grid_RRFS_CONUS_25km_ics_NAM_lbcs_NAM_suite_GFS_v16,RRFS_CONUS_25km,FV3_ ,yes,pregen_grid_orog_sfc_climo,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019070100,6,6,17, ,yes,specify_EXTRN_MDL_SYSBASEDIR_ICS_LBCS,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2021061500,6,6,19, ,yes,specify_template_filenames,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019070100,6,6,28, -,hera/jet/orion,get_from_AWS_ics_GEFS_lbcs_GEFS_fmt_grib2_2022040400_ensemble_2mems,RRFS_CONUS_3km,FV3_HRRR,GEFS,GEFS,2022040400,6,805,45, -,hera/jet/orion,get_from_NOMADS_ics_FV3GFS_lbcs_FV3GFS,RRFS_CONUS_25km,FV3_GFS_2017_gfdlmp,FV3GFS,FV3GFS,*2 days ago*,6,12,40,Retrieves online data and runs a forecast valid 00z 2 days previous to the test date +,hera/jet/orion/gaea,get_from_AWS_ics_GEFS_lbcs_GEFS_fmt_grib2_2022040400_ensemble_2mems,RRFS_CONUS_3km,FV3_HRRR,GEFS,GEFS,2022040400,6,805,45, +,hera/jet/orion/gaea,get_from_NOMADS_ics_FV3GFS_lbcs_FV3GFS,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,*2 days ago*,6,12,40,Retrieves online data and runs a forecast valid 00z 2 days previous to the test date +,hera/jet,custom_ESGgrid_Great_Lakes_snow_8km,*custom*,FV3_RAP,RAP,RAP,2023021700,6,,, ,hera/jet,get_from_HPSS_ics_FV3GFS_lbcs_FV3GFS_fmt_grib2_2019061200,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019061200,6,6,19, ,hera/jet,get_from_HPSS_ics_FV3GFS_lbcs_FV3GFS_fmt_nemsio_2019061200,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2019061200,6,10,23, ,hera/jet,get_from_HPSS_ics_FV3GFS_lbcs_FV3GFS_fmt_nemsio_2021032018,RRFS_CONUS_25km,FV3_GFS_v15p2,FV3GFS,FV3GFS,2021032018,6,10,23, ,hera/jet,get_from_HPSS_ics_FV3GFS_lbcs_FV3GFS_fmt_netcdf_2022060112_48h,RRFS_CONUS_25km,FV3_GFS_v16,FV3GFS,FV3GFS,2022060112,48,55,43, ,hera/jet,get_from_HPSS_ics_GDAS_lbcs_GDAS_fmt_netcdf_2022040400_ensemble_2mems,RRFS_CONUS_3km,FV3_HRRR,GDAS,GDAS,2022040400,6,765,48, -,hera/jet,get_from_HPSS_ics_GSMGFS_lbcs_GSMGFS,RRFS_CONUS_25km,FV3_GFS_2017_gfdlmp,GSMGFS,GSMGFS,2019052000,6,10,25, +,hera/jet,get_from_HPSS_ics_GSMGFS_lbcs_GSMGFS,RRFS_CONUS_25km,FV3_GFS_v15p2,GSMGFS,GSMGFS,2019052000,6,10,25, ,hera/jet,get_from_HPSS_ics_HRRR_lbcs_RAP,RRFS_CONUScompact_25km,FV3_HRRR,HRRR,RAP,2020080100,6,14,30, ,hera/jet,get_from_HPSS_ics_RAP_lbcs_RAP,RRFS_CONUS_25km,FV3_HRRR,RAP,RAP,2019052000,6,17,35, +,hera/jet,long_fcst,RRFS_CONUScompact_25km,FV3_RAP,FV3GFS,FV3GFS,2023060112,108,50,, +,hera/jet,MET_ensemble_verification_only_vx_time_lag,RRFS_CONUS_3km,*none*,*none*,*none*,2021050500,6,3,30, +,,aqm_grid_AQM_NA13km_suite_GFS_v16,AQM_NA_13km,FV3_GFS_v16,FV3GFS,FV3GFS,2023021700 2023021706,6,,,This is an air-quality model test that requires special compilation to run; not supported in this release ,,grid_RRFS_NA_3km_ics_FV3GFS_lbcs_FV3GFS_suite_RRFS_v1beta,RRFS_NA_3km,FV3_RRFS_v1beta,FV3GFS,FV3GFS,2019070100,3,,,The RRFS_NA_3km domain currently has segfault problems--this test is not run ,,subhourly_post,RRFS_CONUScompact_25km,FV3_RRFS_v1beta,HRRR,RAP,2020081000,3,,,Subhourly post tasks are currently broken--these tests are not run ,,subhourly_post_ensemble_2mems,RRFS_CONUScompact_25km,FV3_RRFS_v1beta,HRRR,RAP,2020081000,3,,,Subhourly post tasks are currently broken--these tests are not run From 7df67d556d9e185bd52d1219c275a842a48b3525 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 15 Aug 2023 23:33:26 -0600 Subject: [PATCH 072/116] Update WE2E testing doc umentation --- .../BuildingRunningTesting/WE2Etests.rst | 39 +++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst index 4d6131a49f..c888e64fac 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst @@ -26,6 +26,9 @@ The list of fundamental and comprehensive tests can be viewed in the ``ufs-srwea For convenience, the WE2E tests are currently grouped into the following categories (under ``ufs-srweather-app/tests/WE2E/test_configs/``): +* ``custom_grids`` + This category tests custom grids aside from those specified in ``ufs-srweather-app/ush/predef_grid_params.yaml``. These tests help ensure a wide range of domain sizes, resolutions, and locations will work as expected. These test files can also serve as examples for how to set your own custom domain. + * ``default_configs`` This category tests example config files provided for user reference. They are symbolically linked from the ``ufs-srweather-app/ush/`` directory. @@ -72,7 +75,8 @@ The test script has three required arguments: machine, account, and tests. * Users must specify the set of tests to run using the ``--tests`` or ``-t`` option. Users may pass (in order of priority): #. The name of a single test or list of tests to the test script. - #. A test suite name (e.g., "fundamental", "comprehensive", "coverage", or "all"). + #. A test suite name (e.g., "fundamental", "comprehensive", "coverage", or "all"). + #. The name of a subdirectory under ``ufs-srweather-app/tests/WE2E/test_configs/`` #. The name of a text file (full or relative path), such as ``my_tests.txt``, which contains a list of the WE2E tests to run (one per line). Users may run ``./run_WE2E_tests.py -h`` for additional (optional) usage instructions. @@ -107,7 +111,7 @@ To run the tests ``custom_ESGgrid`` and ``grid_RRFS_CONUScompact_25km_ics_FV3GFS By default, the experiment directory for a WE2E test has the same name as the test itself, and it is created in ``${HOMEdir}/../expt_dirs``, where ``HOMEdir`` is the top-level directory for the ``ufs-srweather-app`` repository (usually set to something like ``/path/to/ufs-srweather-app``). Thus, the ``custom_ESGgrid`` experiment directory would be located in ``${HOMEdir}/../expt_dirs/custom_ESGgrid``. -**A More Complex Example:** To run the fundamental suite of tests on Orion in parallel, charging computational resources to the "gsd-fv3" account, and placing all the experiment directories into a directory named ``test_set_01``, run: +**A More Complex Example:** To run the fiundamental suite of tests on Orion in parallel, charging computational resources to the "gsd-fv3" account, and placing all the experiment directories into a directory named ``test_set_01``, run: .. code-block:: @@ -247,7 +251,7 @@ One might have noticed the line during the experiment run that reads "Use ctrl-c Checking Test Status and Summary ================================= By default, ``./run_WE2E_tests.py`` will actively monitor jobs, printing to console when jobs are complete (either successfully or with a failure), and printing a summary file ``WE2E_summary_{datetime.now().strftime("%Y%m%d%H%M%S")}.txt``. -However, if the user is using the legacy crontab option (by submitting ``./run_WE2E_tests.py`` with the ``--use_cron_to_relaunch`` flag), or if the user would like to summarize one or more experiments that either are not complete or were not handled by the WE2E test scripts, this status/summary file can be generated manually using ``WE2E_summary.py``. +However, if the user is using the legacy crontab option (by submitting ``./run_WE2E_tests.py`` with the ``--launch cron`` option), or if the user would like to summarize one or more experiments that either are not complete or were not handled by the WE2E test scripts, this status/summary file can be generated manually using ``WE2E_summary.py``. In this example, an experiment was generated using the crontab option and has not yet finished running. We use the ``-e`` option to point to the experiment directory and get the current status of the experiment: @@ -290,6 +294,35 @@ We use the ``-e`` option to point to the experiment directory and get the curren As with all python scripts in the SRW App, additional options for this script can be viewed by calling with the ``-h`` argument. +The "Status" as specified by the above summary is explained below: + +* ``CREATED`` + The experiment directory has been created, but the monitor script has not yet begun submitting jobs. This is immediately overwritten at the beginning of the "monitor_jobs" function, so this status should not be seen unless the experiment has not yet been started. + +* ``SUBMITTING`` + All jobs are in status SUBMITTING or SUCCEEDED (as reported by the Rocoto workflow manager). This is a normal state; we will continue to monitor this experiment. + +* ``DYING`` + One or more tasks have died (status "DEAD"), so this experiment has had an error. We will continue to monitor this experiment until all tasks are either status DEAD or status SUCCEEDED (see next entry). + +* ``DEAD`` + One or more tasks are at status DEAD, and the rest are either DEAD or SUCCEEDED. We will no longer monitor this experiment. + +* ``ERROR`` + Could not read the rocoto database file. This will require manual intervention to solve, so we will no longer monitor this experiment. + +* ``RUNNING`` + One or more jobs are at status RUNNING, and the rest are either status QUEUED, SUBMITTED, or SUCCEEDED. This is a normal state; we will continue to monitor this experiment. + +* ``QUEUED`` + One or more jobs are at status QUEUED, and some others may be at status SUBMITTED or SUCCEEDED. This is a normal state; we will continue to monitor this experiment. + +* ``SUCCEEDED`` + All jobs are status SUCCEEDED; we will monitor for one more cycle in case there are unsubmitted jobs remaining. + +* ``COMPLETE`` + All jobs are status SUCCEEDED, and we have monitored this job for an additional cycle to ensure there are no un-submitted jobs. We will no longer monitor this experiment. + .. _WE2ETestInfoFile: From 9aaafc4cfe044161042a5b203c581ab612f01ae5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 16 Aug 2023 09:45:05 -0400 Subject: [PATCH 073/116] fix typos/formatting --- docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst index c888e64fac..9e03b451b2 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/WE2Etests.rst @@ -111,7 +111,7 @@ To run the tests ``custom_ESGgrid`` and ``grid_RRFS_CONUScompact_25km_ics_FV3GFS By default, the experiment directory for a WE2E test has the same name as the test itself, and it is created in ``${HOMEdir}/../expt_dirs``, where ``HOMEdir`` is the top-level directory for the ``ufs-srweather-app`` repository (usually set to something like ``/path/to/ufs-srweather-app``). Thus, the ``custom_ESGgrid`` experiment directory would be located in ``${HOMEdir}/../expt_dirs/custom_ESGgrid``. -**A More Complex Example:** To run the fiundamental suite of tests on Orion in parallel, charging computational resources to the "gsd-fv3" account, and placing all the experiment directories into a directory named ``test_set_01``, run: +**A More Complex Example:** To run the fundamental suite of tests on Orion in parallel, charging computational resources to the "gsd-fv3" account, and placing all the experiment directories into a directory named ``test_set_01``, run: .. code-block:: @@ -235,7 +235,7 @@ The progress of ``monitor_jobs()`` is tracked in a file ``WE2E_tests_{datetime}. Total COMPLETE 15.52 -One might have noticed the line during the experiment run that reads "Use ctrl-c to pause job submission/monitoring". The ``monitor_jobs()`` function (called automatically after all experiments are generated) is designed to be easily paused and re-started if necessary. To stop actively submitting jobs, simply quit the script using "ctrl-c" to stop the function, and a short message will appear explaining how to continue the experiment: +One might have noticed the line during the experiment run that reads "Use ctrl-c to pause job submission/monitoring". The ``monitor_jobs()`` function (called automatically after all experiments are generated) is designed to be easily paused and re-started if necessary. To stop actively submitting jobs, simply quit the script using ``ctrl-c`` to stop the function, and a short message will appear explaining how to continue the experiment: .. code-block:: console @@ -243,7 +243,6 @@ One might have noticed the line during the experiment run that reads "Use ctrl-c Use ctrl-c to pause job submission/monitoring ^C - User interrupted monitor script; to resume monitoring jobs run: ./monitor_jobs.py -y=WE2E_tests_20230418174042.yaml -p=1 From 51d735066722619284e18c97780078b8b6cf11ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 16 Aug 2023 10:13:02 -0400 Subject: [PATCH 074/116] update # of CCPP suites --- docs/UsersGuide/source/Reference/FAQ.rst | 5 +++-- .../source/TinkeringWWflowDetails/ConfigWorkflow.rst | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/Reference/FAQ.rst b/docs/UsersGuide/source/Reference/FAQ.rst index be5dfcc3b1..61e63edd63 100644 --- a/docs/UsersGuide/source/Reference/FAQ.rst +++ b/docs/UsersGuide/source/Reference/FAQ.rst @@ -30,7 +30,7 @@ See :numref:`Section %s ` and/or :numref:`Section %s `. @@ -247,7 +248,7 @@ Then, users can configure a new experiment by updating the environment variables How can I add a physics scheme (e.g., YSU PBL) to the UFS SRW App? ==================================================================== -At this time, there are ten physics suites available in the SRW App, :ref:`four of which are fully supported `. However, several additional physics schemes are available in the UFS Weather Model (WM) and can be enabled in the SRW App. The CCPP Scientific Documentation details the various `namelist options `__ available in the UFS WM, including physics schemes, and also includes an `overview of schemes and suites `__. +At this time, there are ten physics suites available in the SRW App, :ref:`five of which are fully supported `. However, several additional physics schemes are available in the UFS Weather Model (WM) and can be enabled in the SRW App. The CCPP Scientific Documentation details the various `namelist options `__ available in the UFS WM, including physics schemes, and also includes an `overview of schemes and suites `__. To enable an additional physics scheme, such as the YSU PBL scheme, in the SRW App, users must modify ``ufs-srweather-app/parm/FV3.input.yml`` and set the variable corresponding to the desired physics scheme to *True* under the physics suite they would like to use (e.g., ``do_ysu = True``). It may be necessary to disable another physics scheme, too. For example, when using the YSU PBL scheme, users should disable the default SATMEDMF PBL scheme (*satmedmfvdifq*) by setting the ``satmedmf`` variable to *False* in the ``FV3.input.yml`` file. diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst index 0ffb4e1e2f..0646986db8 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst @@ -306,7 +306,7 @@ CCPP Parameter | ``"FV3_RRFS_v1beta"`` | ``"FV3_HRRR"`` | ``"FV3_WoFS_v0"`` - | ``"FV3_RAP"`` (limited support) + | ``"FV3_RAP"`` Other valid values can be found in the ``ush/valid_param_vals.yaml`` file, but users can not expect full support for these schemes. From 6b11b2b5f66854af6aa98b729a29a43ac46f6615 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 17 Aug 2023 11:38:56 -0400 Subject: [PATCH 075/116] update table of comm config vals --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index a3c5212582..f33f4b9e84 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -269,7 +269,7 @@ The user must set the specifics of their experiment configuration in a ``config. +--------------------------------+-------------------+------------------------------------+ | MACHINE | "BIG_COMPUTER" | "hera" | +--------------------------------+-------------------+------------------------------------+ - | ACCOUNT | "project_name" | "an_account" | + | ACCOUNT | "" | "an_account" | +--------------------------------+-------------------+------------------------------------+ | CCPA_OBS_DIR | "" | "" | +--------------------------------+-------------------+------------------------------------+ From 30848695ab5186c708fbdb5aebed8998ae06b580 Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Thu, 17 Aug 2023 11:50:54 -0400 Subject: [PATCH 076/116] Add task_get_obs_nohrsc to VX tasks table Co-authored-by: Michael Lueken <63728921+MichaelLueken@users.noreply.github.com> --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index a3c5212582..1a9dfe56fc 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -828,6 +828,9 @@ METplus verification tasks are described in :numref:`Table %s Date: Thu, 17 Aug 2023 11:52:58 -0400 Subject: [PATCH 077/116] Fix VX task name: metatask_PcpCombine_fcst_APCP_all_accums_all_mems Co-authored-by: Michael Lueken <63728921+MichaelLueken@users.noreply.github.com> --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 1a9dfe56fc..ded66116f5 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -822,7 +822,7 @@ METplus verification tasks are described in :numref:`Table %s Date: Thu, 17 Aug 2023 11:54:31 -0400 Subject: [PATCH 078/116] Add VX task to table: metatask_PcpCombine_fcst_ASNOW_all_accums_all_mems Co-authored-by: Michael Lueken <63728921+MichaelLueken@users.noreply.github.com> --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index ded66116f5..146753ecf3 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -825,6 +825,9 @@ METplus verification tasks are described in :numref:`Table %s Date: Thu, 17 Aug 2023 11:57:08 -0400 Subject: [PATCH 079/116] Add VX task to table: metatask_GenEnsProd_EnsembleStat_NOHRSC Co-authored-by: Michael Lueken <63728921+MichaelLueken@users.noreply.github.com> --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 146753ecf3..bc86838876 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -844,6 +844,9 @@ METplus verification tasks are described in :numref:`Table %s
    ` (formerly *VX_ENSGRID_[REFC|RETOP]*) - ``verify_ens.yaml`` From 389ab119ed6fa13fc2416cd61a3c0ee1d5268a32 Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Thu, 17 Aug 2023 13:24:23 -0400 Subject: [PATCH 080/116] Fix VX task table: metatask_GridStat_NOHRSC_ensmeanprob_all_accums Co-authored-by: Michael Lueken <63728921+MichaelLueken@users.noreply.github.com> --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index bc86838876..4fdd77d3bc 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -855,6 +855,9 @@ METplus verification tasks are described in :numref:`Table %s
    ` (formerly *VX_ENSGRID_PROB_[REFC|RETOP]*) - ``verify_ens.yaml`` From e2138b3e949358755223b70968f7821c31b6646b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 17 Aug 2023 13:28:02 -0400 Subject: [PATCH 081/116] rm GSI from Glossary --- docs/UsersGuide/source/Reference/Glossary.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/UsersGuide/source/Reference/Glossary.rst b/docs/UsersGuide/source/Reference/Glossary.rst index a860486038..8a61939d18 100644 --- a/docs/UsersGuide/source/Reference/Glossary.rst +++ b/docs/UsersGuide/source/Reference/Glossary.rst @@ -108,9 +108,6 @@ Glossary GRIB2 The second version of the World Meterological Organization's (WMO) standard for distributing gridded data. - GSI - `Gridpoint Statistical Interpolation `__ (GSI) is a variational data assimilation system, designed to be flexible, state-of-art, and run efficiently on various parallel computing platforms. It supports :term:`RRFS` features. GSI code is publicly available `on GitHub `__, and fix file data is publicly available `here `__. - GSL NOAA `Global Systems Laboratory `__ is one of ten NOAA Research laboratories and is located in Boulder, Colorado. Its research improves environmental prediction models, develops state-of-the-science decision support tools and visualization systems, and uses high-performance computing technology to support a Weather-Ready Nation. From 15eb7ae3bed537bfe41235dd162e4f216730b9c8 Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Thu, 17 Aug 2023 13:31:37 -0400 Subject: [PATCH 082/116] fix typo Co-authored-by: Michael Lueken <63728921+MichaelLueken@users.noreply.github.com> --- docs/UsersGuide/source/Reference/RocotoInfo.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/Reference/RocotoInfo.rst b/docs/UsersGuide/source/Reference/RocotoInfo.rst index 0aee6efda7..d7da7a16f1 100644 --- a/docs/UsersGuide/source/Reference/RocotoInfo.rst +++ b/docs/UsersGuide/source/Reference/RocotoInfo.rst @@ -150,7 +150,7 @@ where * ``-c`` is the cycle to query in YYYYMMDDHHmm format. * ``-t`` is the task name (e.g., ``make_grid``, ``get_extrn_ics``, ``run_fcst_mem000``). -The cycle and task names appear in the first and second columns of the table output by ``rocotostat``. Users will need to include the absolute or relative path to the worflow XML and database files when running the command from another directory. +The cycle and task names appear in the first and second columns of the table output by ``rocotostat``. Users will need to include the absolute or relative path to the workflow XML and database files when running the command from another directory. A specific example is: From c18f2b51f71c07d8f8c483e4375f82a452c8bc17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Thu, 17 Aug 2023 13:33:19 -0400 Subject: [PATCH 083/116] minor edits --- .../UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst index 0646986db8..4fa1fea891 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst @@ -139,7 +139,7 @@ METplus Parameters * ``SS`` refers to the two-digit valid seconds of the hour ``CCPA_OBS_DIR``: (Default: "") - 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 :term:`HPSS` (if the user has access) via the ``get_obs_ccpa`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). + 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 :term:`HPSS` (if the user has access) via the ``get_obs_ccpa`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). METplus configuration files require the use of a 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. METplus is configured to verify 01-, 03-, 06-, and 24-h accumulated precipitation using hourly CCPA files. From a242b3b0cdbaef949506f49c5580de2a27457bb9 Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Fri, 25 Aug 2023 08:42:26 -0400 Subject: [PATCH 084/116] Update RRFS mention in Intro Co-authored-by: Christina Holt <56881914+christinaholtNOAA@users.noreply.github.com> --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index c7a3a25715..e15b3c42e4 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -11,7 +11,7 @@ The UFS includes `multiple applications ` for a detailed summary of updates that came in ahead of the v2.1.0 release. * Support for the :term:`UPP` inline post option (see :ref:`here `) From 640397480757636d057acf9e90ba0f946b9b81d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 25 Aug 2023 09:55:45 -0400 Subject: [PATCH 085/116] minor cholt edits --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 4 ++-- docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index e15b3c42e4..3ee81d0c4e 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -36,8 +36,8 @@ Background Information Building, Running, and Testing the SRW App -------------------------------------------- - * :numref:`Section %s: Quick Start Guide ` is designed for use on `Level 1 systems `__ or as an overview of the workflow. - * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers run on a broad range of systems and come with SRW App prerequisites already installed. + * :numref:`Section %s: Quick Start Guide ` is designed for use on `Level 1 platforms `__ or as an overview of the workflow. + * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers can run on a broad range of systems and come with SRW App prerequisites already installed. * :numref:`Section %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. * :numref:`Section %s: Running the SRW App ` provides a *detailed* explanation of how to run the SRW App after it has been built/compiled. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. * :numref:`Section %s: Testing the SRW App ` explains how to run workflow end-to-end (WE2E) tests to ensure that new developments do not break the current workflow. diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index 17c41e0c26..2b1b00c5c5 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -25,7 +25,7 @@ The instructions in this documentation assume that users have certain background 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 +* Programming (particularly Python and bash scripting) 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 From a24e66364dc0c972d5582529f70bfded697a96f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 25 Aug 2023 12:18:20 -0400 Subject: [PATCH 086/116] update I/O NOMADS mention to S3 bucket --- .../source/TinkeringWWflowDetails/InputOutputFiles.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst index 273af8ac91..e179219e7a 100644 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst +++ b/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst @@ -19,8 +19,8 @@ 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 timespan for data availability), - * Pulled from the NOAA High Performance Storage System (HPSS) during the workflow execution (requires user access), or + * Pulled from the `SRW App Data Bucket `__, + * Pulled from the NOAA High Performance Storage System (:term:`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. From 40c794b2f7267e15055ca07422cd059cc7d119f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 25 Aug 2023 12:42:32 -0400 Subject: [PATCH 087/116] remove stray Run ch from PR 883 & fix table formatting --- .../source/BuildingRunningTesting/RunSRW.rst | 2 +- docs/UsersGuide/source/RunSRW.rst | 1253 ----------------- 2 files changed, 1 insertion(+), 1254 deletions(-) delete mode 100644 docs/UsersGuide/source/RunSRW.rst diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index a66b23f1e0..62cff71913 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -825,7 +825,7 @@ METplus verification tasks are described in :numref:`Table %s `. These steps are also applicable to containerized versions of the SRW App and assume that the user has completed all of :numref:`Section %s `. - -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 16 physics suite (FV3_GFS_v16 :term:`CCPP`), and :term:`FV3`-based GFS raw external model data for initialization. - -.. attention:: - - The SRW Application has `four levels of support `__. The steps described in this chapter will work most smoothly on preconfigured (Level 1) systems. This chapter can also serve as a starting point for running the SRW App on other systems (including generic Linux/Mac systems), but the user may need to perform additional troubleshooting. - - -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. Once the SRW App has been built, as described in :numref:`Chapter %s `, the steps to run a forecast are as follows: - - #. :ref:`Download and stage data ` - #. :ref:`Optional: Configure a new grid ` - #. :ref:`Generate a regional workflow experiment ` - - * :ref:`Load the python environment for the regional workflow ` - * :ref:`Set the experiment configuration parameters ` - * :ref:`Optional: Plot the output ` - * :ref:`Optional: Configure METplus Verification Suite ` - - #. :ref:`Run the regional workflow ` - -.. _AppOverallProc: - -.. figure:: _static/SRW_run_process.png - :alt: Flowchart describing the SRW App workflow steps. - - *Overall Layout of the SRW App Workflow* - -.. _Data: - -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 systems, the data required to run SRW App tests are already available in the following locations: - -.. _DataLocations: -.. table:: Data Locations for Level 1 Systems - - +--------------+------------------------------------------------------------------------------+ - | Machine | File location | - +==============+==============================================================================+ - | Cheyenne | /glade/work/epicufsrt/contrib/UFS_SRW_data/develop/input_model_data/ | - +--------------+------------------------------------------------------------------------------+ - | Gaea | /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/develop/input_model_data/ | - +--------------+------------------------------------------------------------------------------+ - | Hera | /scratch1/NCEPDEV/nems/role.epic/UFS_SRW_data/develop/input_model_data/ | - +--------------+------------------------------------------------------------------------------+ - | Jet | /mnt/lfs4/HFIP/hfv3gfs/role.epic/UFS_SRW_data/develop/input_model_data/ | - +--------------+------------------------------------------------------------------------------+ - | NOAA Cloud | /contrib/EPIC/UFS_SRW_data/develop/input_model_data/ | - +--------------+------------------------------------------------------------------------------+ - | Orion | /work/noaa/epic-ps/role-epic-ps/UFS_SRW_data/develop/input_model_data/ | - +--------------+------------------------------------------------------------------------------+ - | WCOSS2 | /lfs/h2/emc/lam/noscrub/UFS_SRW_App/develop/input_model_data/ | - +--------------+------------------------------------------------------------------------------+ - -For Level 2-4 systems, the data must be added to the user's system. Detailed instructions on how to add the data can be found in :numref:`Section %s `. Sections :numref:`%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 the four predefined grids 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 `. 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 custom predefined grid should refer to :numref:`Section %s ` for instructions. At a minimum, these users will need to add the new grid name to the ``valid_param_vals.yaml`` file and add the corresponding grid-specific parameters in the ``predef_grid_params.yaml`` file. - -.. _PredefinedGrids: - -.. table:: Predefined Grids Supported 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 | - +----------------------+-------------------+--------------------------------+ - | SUBCONUS_Ind_3km | ESG grid | lambert_conformal | - +----------------------+-------------------+--------------------------------+ - - -.. _GenerateForecast: - -Generate the Forecast Experiment -================================= -Generating the forecast experiment requires three steps: - -#. :ref:`Load the python environment for the regional workflow ` -#. :ref:`Set experiment configuration 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 reflect their machine configuration if they are working on a Level 2-4 platform. Information in :numref:`Chapter %s: Configuring the Workflow ` can help with this. - -.. _SetUpPythonEnv: - -Load the Conda/Python Environment for the Regional Workflow --------------------------------------------------------------- - -The workflow requires Python3 installed using conda, with the additional packages built in a separate conda evironment named ``regional_workflow``. This environment has the following additional packages: ``PyYAML``, ``Jinja2``, ``f90nml``, ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``. This conda/Python environment has already been set up on Level 1 platforms and can be activated in the following way: - -.. code-block:: console - - source - module use - module load wflow_ - -where ```` refers to a valid machine name (see :numref:`Section %s `). - -.. note:: - If users source the lmod-setup file on a system that doesn't need it, it will not cause any problems (it will simply do a ``module purge``). - -A brief recipe for building the regional workflow environment on a Linux or Mac system can be found in :numref:`Section %s `. - -The ``wflow_`` modulefile will then output instructions to activate the regional workflow. The user should run the commands specified in the modulefile output. The command may vary from system to system. For example, if the output says: - -.. code-block:: console - - Please do the following to activate conda: - > conda activate regional_workflow - -then the user should run ``conda activate regional_workflow``. This activates the ``regional_workflow`` conda environment, and the user typically sees ``(regional_workflow)`` in front of the Terminal prompt at this point. - -Preparing the Workflow Environment on Non-Level 1 Systems -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users on non-Level 1 systems can copy one of the provided ``wflow_`` files and use it as a template to create a ``wflow_`` file that works for their system. The ``wflow_macos`` and ``wflow_linux`` template modulefiles are provided in the ``modulefiles`` directory. Modifications are required to provide paths for python, miniconda modules, module loads, conda initialization, and the path for user's ``regional_workflow`` conda environment. After making modifications to a ``wflow_`` file, users can run the commands from :numref:`Step %s ` above to activate the regional workflow. - -.. note:: - ``conda`` needs to be initialized before running ``conda activate regional_workflow`` command. Depending on the user's system and login setup, this may be accomplished in a variety of ways. Conda initialization usually involves the following command: ``source /etc/profile.d/conda.sh``, where ```` is the base conda installation directory. - -.. _ExptConfig: - -Set Experiment Configuration Parameters ------------------------------------------- - -Each experiment requires certain basic information to run (e.g., date, grid, physics suite). This information is specified in ``config_defaults.yaml`` and in the user-specified ``config.yaml`` file. When generating a new experiment, the SRW App first reads and assigns default values from ``config_defaults.yaml``. Then, it reads and (re)assigns variables from the user's custom ``config.yaml`` file. - -For background info on ``config_defaults.yaml``, read :numref:`Section %s `, or jump to :numref:`Section %s ` to continue configuring the experiment. - -.. _DefaultConfigSection: - -Default configuration: ``config_defaults.yaml`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. note:: - This section provides background information on available parameters and how the SRW App uses the ``config_defaults.yaml`` file. It is informative, but users do not need to modify ``config_defaults.yaml`` to run the out-of-the-box case for the SRW App. Therefore, users may skip to :numref:`Step %s ` to continue configuring their experiment. - -Configuration parameters in the ``config_defaults.yaml`` 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.yaml`` file. Any settings provided in ``config.yaml`` will override the settings in ``config_defaults.yaml``. 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 ``config_defaults.yaml`` file comments and in :numref:`Chapter %s `. - -.. _ConfigVarsDefault: - -.. table:: Configuration variables specified in the config_defaults.yaml script - - +-----------------------------+-----------------------------------------------------------------------+ - | **Group Name** | **Configuration variables** | - +=============================+=======================================================================+ - | User | RUN_ENVIR, MACHINE, MACHINE_FILE, ACCOUNT | - +-----------------------------+-----------------------------------------------------------------------+ - | Platform | WORKFLOW_MANAGER, NCORES_PER_NODE, BUILD_MOD_FN, WFLOW_MOD_FN, | - | | BUILD_VER_FN, RUN_VER_FN, SCHED, DOMAIN_PREGEN_BASEDIR, | - | | ENV_INIT_SCRIPTS_FPS, PRE_TASK_CMDS, PARTITION_DEFAULT, QUEUE_DEFAULT,| - | | PARTITION_HPSS, QUEUE_HPSS, PARTITION_FCST, QUEUE_FCST, | - | | RUN_CMD_UTILS, RUN_CMD_FCST, RUN_CMD_POST, SLURM_NATIVE_CMD, | - | | MODEL, CCPA_OBS_DIR, | - | | MRMS_OBS_DIR, NDAS_OBS_DIR, NOHRSC_OBS_DIR | - +-----------------------------+-----------------------------------------------------------------------+ - | Workflow | WORKFLOW_ID, USE_CRON_TO_RELAUNCH, CRON_RELAUNCH_INTVL_MNTS, | - | | EXPT_BASEDIR, EXPT_SUBDIR, EXEC_SUBDIR, DOT_OR_USCORE, | - | | EXPT_CONFIG_FN, CONSTANTS_FN, RGNL_GRID_NML_FN, | - | | FV3_NML_BASE_SUITE_FN, FV3_NML_YAML_CONFIG_FN, FV3_NML_BASE_ENS_FN, | - | | FV3_EXEC_FN, DIAG_TABLE_TMPL_FN, FIELD_TABLE_TMPL_FN, | - | | DATA_TABLE_TMPL_FN, MODEL_CONFIG_TMPL_FN, NEMS_CONFIG_TMPL_FN, | - | | FCST_MODEL, WFLOW_XML_FN, GLOBAL_VAR_DEFNS_FN, | - | | EXTRN_MDL_VAR_DEFNS_FN, WFLOW_LAUNCH_SCRIPT_FN, WFLOW_LAUNCH_LOG_FN, | - | | CCPP_PHYS_SUITE, GRID_GEN_METHOD, DATE_FIRST_CYCL, DATE_LAST_CYCL, | - | | INCR_CYCL_FREQ, FCST_LEN_HRS, GET_OBS, MAXTRIES_VX_ENSGRID_PROB_REFC, | - | | PREEXISTING_DIR_METHOD, VERBOSE, DEBUG, COMPILER | - +-----------------------------+-----------------------------------------------------------------------+ - | NCO | envir, NET, model_ver, RUN, OPSROOT | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_grid | GRID_DIR, ESGgrid_LON_CTR, ESGgrid_LAT_CTR, | - | | ESGgrid_DELX, ESGgrid_DELY, ESGgrid_NX, ESGgrid_NY, ESGgrid_PAZI, | - | | ESGgrid_WIDE_HALO_WIDTH, GFDLgrid_LON_T6_CTR, GFDLgrid_LAT_T6_CTR, | - | | GFDLgrid_NUM_CELLS, GFDLgrid_STRETCH_FAC, GFDLgrid_REFINE_RATIO, | - | | GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G, GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G, | - | | GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G, GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G, | - | | GFDLgrid_USE_NUM_CELLS_IN_FILENAMES | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_orog | KMP_AFFINITY_MAKE_OROG, OMP_NUM_THREADS_MAKE_OROG | - | | OMP_STACKSIZE_MAKE_OROG, OROG_DIR | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_sfc_climo | KMP_AFFINITY_MAKE_SFC_CLIMO, OMP_NUM_THREADS_MAKE_SFC_CLIMO, | - | | OMP_STACKSIZE_MAKE_SFC_CLIMO, SFC_CLIMO_DIR | - +-----------------------------+-----------------------------------------------------------------------+ - | task_get_extrn_ics | EXTRN_MDL_NAME_ICS, EXTRN_MDL_ICS_OFFSET_HRS, FV3GFS_FILE_FMT_ICS, | - | | EXTRN_MDL_SYSBASEDIR_ICS, USE_USER_STAGED_EXTRN_FILES, | - | | EXTRN_MDL_SOURCE_BASEDIR_ICS, EXTRN_MDL_FILES_ICS, | - | | EXTRN_MDL_FILES_ICS, EXTRN_MDL_FILES_ICS, EXTRN_MDL_DATA_STORES, | - | | NOMADS, NOMADS_file_type | - +-----------------------------+-----------------------------------------------------------------------+ - | task_get_extrn_lbcs | EXTRN_MDL_NAME_LBCS, | - | | LBC_SPEC_INTVL_HRS, EXTRN_MDL_LBCS_OFFSET_HRS, FV3GFS_FILE_FMT_LBCS, | - | | EXTRN_MDL_SYSBASEDIR_LBCS, USE_USER_STAGED_EXTRN_FILES, | - | | EXTRN_MDL_SOURCE_BASEDIR_LBCS, EXTRN_MDL_FILES_LBCS, | - | | EXTRN_MDL_DATA_STORE, NOMADS, NOMADS_file_type | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_ics | KMP_AFFINITY_MAKE_ICS, OMP_NUM_THREADS_MAKE_ICS, | - | | OMP_STACKSIZE_MAKE_ICS, USE_FVCOM, FVCOM_WCSTART, FVCOM_DIR, | - | | FVCOM_FILE | - +-----------------------------+-----------------------------------------------------------------------+ - | task_make_lbcs | KMP_AFFINITY_MAKE_LBCS, OMP_NUM_THREADS_MAKE_LBCS, | - | | OMP_STACKSIZE_MAKE_LBCS | - +-----------------------------+-----------------------------------------------------------------------+ - | task_run_fcst | KMP_AFFINITY_RUN_FCST, OMP_NUM_THREADS_RUN_FCST, | - | | OMP_STACKSIZE_RUN_FCST, DT_ATMOS, RESTART_INTERVAL, WRITE_DOPOST, | - | | LAYOUT_X, LAYOUT_Y, BLOCKSIZE, QUILTING, PRINT_ESMF, | - | | WRTCMP_write_groups, WRTCMP_write_tasks_per_group, | - | | 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, PREDEF_GRID_NAME, USE_MERRA_CLIMO, | - | | SFC_CLIMO_FIELDS, FIXgsm, FIXaer, FIXlut, TOPO_DIR, | - | | SFC_CLIMO_INPUT_DIR, SYMLINK_FIX_FILES, 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 | - +-----------------------------+-----------------------------------------------------------------------+ - | task_run_post | KMP_AFFINITY_RUN_POST, OMP_NUM_THREADS_RUN_POST, | - | | OMP_STACKSIZE_RUN_POST, SUB_HOURLY_POST, DT_SUB_HOURLY_POST_MNTS, | - | | USE_CUSTOM_POST_CONFIG_FILE, CUSTOM_POST_CONFIG_FP, | - | | POST_OUTPUT_DOMAIN_NAME | - +-----------------------------+-----------------------------------------------------------------------+ - | Global | USE_CRTM, CRTM_DIR, DO_ENSEMBLE, NUM_ENS_MEMBERS, | - | | NEW_LSCALE, DO_SHUM, ISEED_SHUM, SHUM_MAG, SHUM_LSCALE, SHUM_TSCALE, | - | | SHUM_INT, DO_SPPT, ISEED_SPPT, SPPT_MAG, SPPT_LOGIT, SPPT_LSCALE, | - | | SPPT_TSCALE, SPPT_INT, SPPT_SFCLIMIT, USE_ZMTNBLCK, DO_SKEB, | - | | ISEED_SKEB, SKEB_MAG, SKEB_LSCALE, SKEP_TSCALE, SKEB_INT, SKEBNORM, | - | | SKEB_VDOF, DO_SPP, ISEED_SPP, SPP_VAR_LIST, SPP_MAG_LIST, SPP_LSCALE, | - | | SPP_TSCALE, SPP_SIGTOP1, SPP_SIGTOP2, SPP_STDDEV_CUTOFF, DO_LSM_SPP, | - | | LSM_SPP_TSCALE, LSM_SPP_LSCALE, ISEED_LSM_SPP, LSM_SPP_VAR_LIST, | - | | LSM_SPP_MAG_LIST, HALO_BLEND | - +-----------------------------+-----------------------------------------------------------------------+ - -.. _UserSpecificConfig: - -User-specific configuration: ``config.yaml`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The user must specify certain basic experiment configuration information in a ``config.yaml`` file located in the ``ufs-srweather-app/ush`` directory. Two example templates are provided in that directory: ``config.community.yaml`` and ``config.nco.yaml``. The first file is a minimal example for creating and running an experiment in *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 is fully supported for this release. The operational/NCO mode is typically used by developers at the Environmental Modeling Center (:term:`EMC`) and at the Global Systems Laboratory (:term:`GSL`) working on pre-implementation testing for the Rapid Refresh Forecast System (RRFS). :numref:`Table %s ` compares the configuration variables that appear in the ``config.community.yaml`` with their default values in ``config_default.yaml``. - -.. _ConfigCommunity: - -.. table:: Configuration variables specified in the config.community.yaml script - - +--------------------------------+-------------------+------------------------------------+ - | **Parameter** | **Default Value** | **config.community.yaml Value** | - +================================+===================+====================================+ - | RUN_ENVIR | "nco" | "community" | - +--------------------------------+-------------------+------------------------------------+ - | MACHINE | "BIG_COMPUTER" | "hera" | - +--------------------------------+-------------------+------------------------------------+ - | ACCOUNT | "project_name" | "an_account" | - +--------------------------------+-------------------+------------------------------------+ - | MODEL | "" | "FV3_GFS_v16_CONUS_25km" | - +--------------------------------+-------------------+------------------------------------+ - | CCPA_OBS_DIR | "" | "" | - +--------------------------------+-------------------+------------------------------------+ - | NOHRSC_OBS_DIR | "" | "" | - +--------------------------------+-------------------+------------------------------------+ - | MRMS_OBS_DIR | "" | "" | - +--------------------------------+-------------------+------------------------------------+ - | NDAS_OBS_DIR | "" | "" | - +--------------------------------+-------------------+------------------------------------+ - | EXPT_SUBDIR | "" | "test_community" | - +--------------------------------+-------------------+------------------------------------+ - | CCPP_PHYS_SUITE | "FV3_GFS_v16" | "FV3_GFS_v16" | - +--------------------------------+-------------------+------------------------------------+ - | DATE_FIRST_CYCL | "YYYYMMDDHH" | '2019061518' | - +--------------------------------+-------------------+------------------------------------+ - | DATE_LAST_CYCL | "YYYYMMDDHH" | '2019061518' | - +--------------------------------+-------------------+------------------------------------+ - | FCST_LEN_HRS | 24 | 12 | - +--------------------------------+-------------------+------------------------------------+ - | PREEXISTING_DIR_METHOD | "delete" | "rename" | - +--------------------------------+-------------------+------------------------------------+ - | VERBOSE | true | true | - +--------------------------------+-------------------+------------------------------------+ - | COMPILER | "intel" | "intel" | - +--------------------------------+-------------------+------------------------------------+ - | EXTRN_MDL_NAME_ICS | "FV3GFS" | "FV3GFS" | - +--------------------------------+-------------------+------------------------------------+ - | FV3GFS_FILE_FMT_ICS | "nemsio" | "grib2" | - +--------------------------------+-------------------+------------------------------------+ - | EXTRN_MDL_NAME_LBCS | "FV3GFS" | "FV3GFS" | - +--------------------------------+-------------------+------------------------------------+ - | FV3GFS_FILE_FMT_LBCS | "nemsio" | "grib2" | - +--------------------------------+-------------------+------------------------------------+ - | LBC_SPEC_INTVL_HRS | 6 | 6 | - +--------------------------------+-------------------+------------------------------------+ - | WTIME_RUN_FCST | "04:30:00" | "02:00:00" | - +--------------------------------+-------------------+------------------------------------+ - | QUILTING | true | true | - +--------------------------------+-------------------+------------------------------------+ - | PREDEF_GRID_NAME | "" | "RRFS_CONUS_25km" | - +--------------------------------+-------------------+------------------------------------+ - | DO_ENSEMBLE | false | false | - +--------------------------------+-------------------+------------------------------------+ - | NUM_ENS_MEMBERS | 1 | 2 | - +--------------------------------+-------------------+------------------------------------+ - - -To get started, make a copy of ``config.community.yaml``. From the ``ufs-srweather-app`` directory, run: - -.. code-block:: console - - cd /path/to/ufs-srweather-app/ush - cp config.community.yaml config.yaml - -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. - -.. note:: - - Users who have a previous configuration using the former shell-script-based can convert their ``config.sh`` file to a ``config.yaml`` file by running: - - .. code-block:: console - - ./config_utils.py -c $PWD/config.sh -t $PWD/config_defaults.yaml -o yaml >config.yaml - - Use caution when upgrading your experiment in this way, as many intervening changes in the workflow have occurred since the python changeover. - -Next, users should edit the new ``config.yaml`` file to customize it for their machine. At a minimum, users must change the ``MACHINE`` and ``ACCOUNT`` variables. Then, they can choose a name for the experiment directory by setting ``EXPT_SUBDIR``. If users have pre-staged initialization data for the experiment, they can 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``. If the modulefile used to set up the build environment in :numref:`Section %s ` uses a GNU compiler, check that the line ``COMPILER: "gnu"`` appears in the ``workflow:`` section of the ``config.yaml`` file. On platforms where Rocoto and :term:`cron` are available, users can automate resubmission of their experiment workflow by adding the following lines to the ``workflow:`` section of the ``config.yaml`` file: - -.. code-block:: console - - USE_CRON_TO_RELAUNCH: true - CRON_RELAUNCH_INTVL_MNTS: 3 - -.. note:: - - Generic Linux and MacOS users should refer to :numref:`Section %s ` for additional details on configuring an experiment and python environment. - -Detailed information on additional parameter options can be viewed in :numref:`Chapter %s: Configuring the Workflow `. Additionally, information about the four predefined Limited Area Model (LAM) Grid options can be found in :numref:`Chapter %s: Limited Area Model (LAM) Grids `. - -On Level 1 systems, the following fields typically need to be updated or added to the appropriate section of the ``config.yaml`` file in order to run the out-of-the-box SRW App case: - -.. code-block:: console - - user: - MACHINE: hera - ACCOUNT: an_account - workflow: - EXPT_SUBDIR: test_community - task_get_extrn_ics: - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_ICS: "/path/to/UFS_SRW_App/develop/input_model_data///" - task_get_extrn_lbcs: - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_LBCS: "/path/to/UFS_SRW_App/develop/input_model_data///" - -where: - * ``MACHINE`` refers to a valid machine name (see :numref:`Section %s ` for options). - * ``ACCOUNT`` refers to a valid account name. Not all systems require a valid account name, but most do. - - .. hint:: - - 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. - - * ``EXPT_SUBDIR`` is changed to an experiment name of the user's choice. - * ```` is the path to the SRW App data on the user's machine (see :numref:`Section %s `). - * ```` refers to a subdirectory containing the experiment data from a particular model. Valid values on Level 1 systems correspond to the valid values for ``EXTRN_MDL_NAME_ICS`` and ``EXTRN_MDL_NAME_LBCS`` (see :numref:`Chapter %s ` for options). - * ```` refers to one of 3 possible data formats: ``grib2``, ``nemsio``, or ``netcdf``. - * ```` refers to a subdirectory containing data for the :term:`cycle` date (in YYYYMMDDHH format). - -.. note:: - - On ``JET``, users should also add ``PARTITION_DEFAULT: xjet`` and ``PARTITION_FCST: xjet`` to the ``platform:`` section of the ``config.yaml`` file. - -For example, to run the out-of-the-box experiment on Gaea, add or modify variables in the ``user``, ``workflow``, ``task_get_extrn_ics``, and ``task_get_extrn_lbcs`` sections of ``config.yaml`` (unmodified variables are not shown in this example): - - .. code-block:: - - user: - MACHINE: gaea - ACCOUNT: hfv3gfs - workflow: - EXPT_SUBDIR: run_basic_srw - task_get_extrn_ics: - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_ICS: /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/develop/input_model_data/FV3GFS/grib2/2019061518 - EXTRN_MDL_DATA_STORES: disk - task_get_extrn_lbcs: - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_LBCS: /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/develop/input_model_data/FV3GFS/grib2/2019061518 - EXTRN_MDL_DATA_STORES: disk - -To determine whether the ``config.yaml`` file adjustments are valid, users can run the following script from the ``ush`` directory: - -.. code-block:: console - - ./config_utils.py -c $PWD/config.yaml -v $PWD/config_defaults.yaml - -A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yaml`` file with problems will output a ``FAILURE`` message describing the problem. For example: - -.. code-block:: console - - INVALID ENTRY: EXTRN_MDL_FILES_ICS=[] - FAILURE - -.. note:: - - The regional workflow must be loaded for the ``config_utils.py`` script to validate the ``config.yaml`` file. - -Valid values for configuration variables should be consistent with those in the ``ush/valid_param_vals.yaml`` script. In addition, various sample configuration files can be found within the subdirectories of ``tests/WE2E/test_configs``. - -To configure an experiment and python environment for a general Linux or Mac system, see the :ref:`next section `. To configure an experiment to run METplus verification tasks, see :numref:`Section %s `. Otherwise, skip to :numref:`Section %s ` to generate the workflow. - -.. _PlotOutput: - -Plotting Configuration (optional) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -An optional Python plotting task (PLOT_ALLVARS) can be activated in the workflow to generate plots for the :term:`FV3`-:term:`LAM` post-processed :term:`GRIB2` -output over the :term:`CONUS`. It generates graphics plots for a number of variables, including: - - * 2-m temperature - * 2-m dew point temperature - * 10-m winds - * 250 hPa winds - * Accumulated precipitation - * Composite reflectivity - * Surface-based :term:`CAPE`/:term:`CIN` - * Max/Min 2-5 km updraft helicity - * Sea level pressure (SLP) - -.. COMMENT: * 500 hPa heights, winds, and vorticity --> seems to be omitted? Why? - -This workflow task can produce both plots from a single experiment and difference plots that compare the same cycle from two experiments. When plotting the difference, the two experiments must be on the same domain and available for -the same cycle starting date/time and forecast hours. Other parameters may differ (e.g., the experiments may use different physics suites). - -.. _Cartopy: - -Cartopy Shapefiles -````````````````````` - -The Python plotting tasks require a path to the directory where the Cartopy Natural Earth shapefiles are located. The medium scale (1:50m) cultural and physical shapefiles are used to create coastlines and other geopolitical borders on the map. On `Level 1 `__ systems, this path is already set in the system's machine file using the variable ``FIXshp``. Users on other systems will need to download the shapefiles and update the path of ``$FIXshp`` in the machine file they are using (e.g., ``$SRW/ush/machine/macos.yaml`` for a generic MacOS system, where ``$SRW`` is the path to the ``ufs-srweather-app`` directory). The subset of shapefiles required for the plotting task can be obtained from the `SRW Data Bucket `__. The full set of medium-scale (1:50m) Cartopy shapefiles can be downloaded `here `__. - -Task Configuration -````````````````````` - -Users will need to add or modify certain variables in ``config.yaml`` to run the plotting task(s). At a minimum, to activate the ``plot_allvars`` tasks, users must add it to the default list of ``taskgroups`` under the ``rocoto: tasks:`` section. - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/plot.yaml"]|include }}' - -Users may also wish to adjust the start, end, and increment value for the plotting task. For example: - -.. code-block:: console - - task_plot_allvars: - PLOT_FCST_START: 0 - PLOT_FCST_INC: 6 - PLOT_FCST_END: 12 - -If the user chooses not to set these values, the default values will be used (see :numref:`Section %s `). - -.. note:: - If a forecast starts at 18h, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. - -When plotting output from a single experiment, no further adjustments are necessary. The output files (in ``.png`` format) will be located in the experiment directory under the ``$CDATE/postprd`` subdirectory where ``$CDATE`` -corresponds to the cycle date and hour in YYYYMMDDHH format (e.g., ``2019061518``). - -Plotting the Difference Between Two Experiments -"""""""""""""""""""""""""""""""""""""""""""""""""" - -When plotting the difference between two experiments (``expt1`` and ``expt2``), users must set the ``COMOUT_REF`` template variable in ``expt2``'s ``config.yaml`` file to point at forecast output from the ``expt1`` directory. For example, in *community* mode, users can set ``COMOUT_REF`` as follows in the ``expt2`` configuration file: - -.. code-block:: console - - task_plot_allvars: - COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd' - -This will ensure that ``expt2`` can produce a difference plot comparing ``expt1`` and ``expt2``. In *community* mode, using default directory names and settings, ``$COMOUT_REF`` will resemble ``/path/to/expt_dirs/test_community/2019061518/postprd``. Additional details on the plotting variables are provided in :numref:`Section %s `. - -The output files (in ``.png`` format) will be located in the ``postprd`` directory for the experiment. - -.. _LinuxMacEnvConfig: - -User-Specific Configuration on a Generic Linux/MacOS System -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The configuration process for Linux and MacOS systems is similar to the process for other systems, but it requires a few extra steps. - -.. note:: - Examples in this subsection presume that the user is running in the Terminal with a bash shell environment. If this is not the case, users will need to adjust the commands to fit their command line application and shell environment. - -.. _MacMorePackages: - -Install/Upgrade Mac-Specific Packages -```````````````````````````````````````` -MacOS requires the installation of a few additional packages and, possibly, an upgrade to bash. Users running on MacOS should execute the following commands: - -.. code-block:: console - - bash --version - brew install bash # or: brew upgrade bash - brew install coreutils - brew gsed # follow directions to update the PATH env variable - -.. _LinuxMacVEnv: - -Creating a *conda* Environment on Linux and Mac -`````````````````````````````````````````````````` - -Users need to create a conda ``regional_workflow`` environment. The environment can be stored in a local path, which could be a default location or a user-specified location (e.g. ``$HOME/condaenv/venvs/`` directory). (To determine the default location, use the ``conda info`` command, and look for the ``envs directories`` list.) A brief recipe for creating a virtual conda environment on non-Level 1 platforms: - -.. code-block:: console - - conda create --name regional_workflow python= - conda activate regional_workflow - conda install -c conda-forge f90nml - conda install jinja2 - conda install pyyaml - # install packages for graphics environment - conda install scipy - conda install matplotlib - conda install -c conda-forge pygrib - conda install cartopy - # verify the packages installed - conda list - conda deactivate - -where ```` is a numeric version (e.g. ``3.9.12``) in the conda base installation resulting from the query ``python3 --version``. - -.. _LinuxMacExptConfig: - -Configuring an Experiment on General Linux and MacOS Systems -`````````````````````````````````````````````````````````````` - -**Optional: Install Rocoto** - -.. note:: - Users may `install Rocoto `__ if they want to make use of a workflow manager to run their experiments. However, this option has not yet been tested on MacOS and has had limited testing on general Linux plaforms. - - -**Configure the SRW App:** - -Configure an experiment using a template. Copy the contents of ``config.community.yaml`` into ``config.yaml``: - -.. code-block:: console - - cd /path/to/ufs-srweather-app/ush - cp config.community.yaml config.yaml - -In the ``config.yaml`` file, set ``MACHINE: macos`` or ``MACHINE: linux``, and modify the account and experiment info. For example: - -.. code-block:: console - - user: - RUN_ENVIR: community - MACHINE: macos - ACCOUNT: user - workflow: - EXPT_SUBDIR: test_community - PREEXISTING_DIR_METHOD: rename - VERBOSE: true - COMPILER: gnu - task_get_extrn_ics: - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/input_model_data/FV3GFS/grib2/2019061518 - EXTRN_MDL_DATA_STORES: disk - task_get_extrn_lbcs: - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/input_model_data/FV3GFS/grib2/2019061518 - EXTRN_MDL_DATA_STORES: disk - task_run_fcst: - PREDEF_GRID_NAME: RRFS_CONUS_25km - QUILTING: true - -Due to the limited number of processors on MacOS systems, users must also configure the domain decomposition parameters directly in the section of the ``predef_grid_params.yaml`` file pertaining to the grid they want to use. Domain decomposition needs to take into account the number of available CPUs and configure the variables ``LAYOUT_X``, ``LAYOUT_Y``, and ``WRTCMP_write_tasks_per_group`` accordingly. - -The example below is for systems with 8 CPUs: - -.. code-block:: console - - task_run_fcst: - LAYOUT_X: 3 - LAYOUT_Y: 2 - WRTCMP_write_tasks_per_group: 2 - -.. note:: - The number of MPI processes required by the forecast will be equal to ``LAYOUT_X`` * ``LAYOUT_Y`` + ``WRTCMP_write_tasks_per_group``. - -For a machine with 4 CPUs, the following domain decomposition could be used: - -.. code-block:: console - - task_run_fcst: - LAYOUT_X: 3 - LAYOUT_Y: 1 - WRTCMP_write_tasks_per_group: 1 - -**Configure the Machine File** - -Configure a ``macos.yaml`` or ``linux.yaml`` machine file in ``ufs-srweather-app/ush/machine`` based on the number of CPUs (``NCORES_PER_NODE``) in the system (usually 8 or 4 in MacOS; varies on Linux systems). Job scheduler (``SCHED``) options can be viewed :ref:`here `. Users must also set the path to the fix file directories. - -.. code-block:: console - - platform: - # Architecture information - WORKFLOW_MANAGER: none - NCORES_PER_NODE: 8 - SCHED: none - # Run commands for executables - RUN_CMD_FCST: 'mpirun -np ${PE_MEMBER01}' - RUN_CMD_POST: 'mpirun -np 4' - RUN_CMD_SERIAL: time - RUN_CMD_UTILS: 'mpirun -np 4' - # Commands to run at the start of each workflow task. - PRE_TASK_CMDS: '{ ulimit -a; }' - - task_make_orog: - # Path to location of static input files used by the make_orog task - TOPO_DIR: path/to/FIXgsm/files - - task_make_sfc_climo: - # Path to location of static surface climatology input fields used by sfc_climo_gen - SFC_CLIMO_INPUT_DIR: path/to/FIXgsm/files - - task_run_fcst: - FIXaer: /path/to/FIXaer/files - FIXgsm: /path/to/FIXgsm/files - FIXlut: /path/to/FIXlut/files - - data: - # Used by setup.py to set the values of EXTRN_MDL_SOURCE_BASEDIR_ICS and EXTRN_MDL_SOURCE_BASEDIR_LBCS - FV3GFS: /Users/username/DATA/UFS/FV3GFS - -The ``data:`` section of the machine file can point to various data sources that the user has pre-staged on disk. For example: - -.. code-block:: console - - data: - FV3GFS: - nemsio: /Users/username/DATA/UFS/FV3GFS/nemsio - grib2: /Users/username/DATA/UFS/FV3GFS/grib2 - netcdf: /Users/username/DATA/UFS/FV3GFS/netcdf - RAP: /Users/username/DATA/UFS/RAP/grib2 - HRRR: /Users/username/DATA/UFS/HRRR/grib2 - -This can be helpful when conducting multiple experiments with different types of data. - -.. _VXConfig: - -Configure METplus Verification Suite (Optional) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users who want to use the METplus verification suite to evaluate their forecasts need to add additional information to their ``ush/machine/.yaml`` or ``config.yaml`` file. Other users may skip to the :ref:`next section `. - -.. note:: - If METplus users update their METplus installation, they must update the module load statements in ``ufs-srweather-app/modulefiles/tasks//run_vx.local`` file to correspond to their system's updated installation: - - .. code-block:: console - - module use -a - module load met/ - module load metplus/ - -.. note:: - PRELIMINARY CHANGES, NEEDS TO BE UPDATE IN A SECTION BELOW: for the recent changes in develop, there are several verify_*.yaml files, verify_pre.yaml, verify_ens.yaml, verify_det.yaml. Documentation below still mentions a single `veryfy.yaml` file. - -To use METplus verification, MET and METplus modules need to be installed. To turn on verification tasks in the workflow, include the ``parm/wflow/verify.yaml`` file in the ``rocoto: tasks: taskgroups:`` section of ``config.yaml``. - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' - -The ``verify.yaml`` file includes the definitions of several common verification tasks by default. They are independent of each other, so users may want to turn some off 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 `. - -To turn off a task, simply include its entry from ``verify.yaml`` as an empty YAML entry. For example, to turn off PointStat tasks: - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' - metatask_vx_ens_member: - metatask_PointStat_mem#mem#: - - -More information about configuring the ``rocoto:`` section can be found in :numref:`Section %s `. - -If users have access to NOAA :term:`HPSS` but have not pre-staged the data, the default ``verify.yaml`` taskgroup will activate the tasks, and the workflow will attempt to download the appropriate data from NOAA HPSS. In this case, 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 `__. - -Users who have already staged the observation data needed for METplus (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data and turn off the corresponding task by including them with no entry in ``config.yaml``. - -.. code-block:: console - - platform: - CCPA_OBS_DIR: /path/to/UFS_SRW_App/develop/obs_data/ccpa/proc - NOHRSC_OBS_DIR: /path/to/UFS_SRW_App/develop/obs_data/nohrsc/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 - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml", "parm/wflow/verify.yaml"]|include }}' - task_get_obs_ccpa: - task_get_obs_nohrsc: - task_get_obs_mrms: - task_get_obs_ndas: - - - -.. _GenerateWorkflow: - -Generate the Regional Workflow -------------------------------------------- - -Run the following command from the ``ufs-srweather-app/ush`` directory to generate the workflow: - -.. code-block:: console - - ./generate_FV3LAM_wflow.py - -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 if users have the Rocoto workflow manager installed on their system. - -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.py`` runs the ``setup.py`` script to set the configuration parameters. Second, it symlinks the time-independent (fix) files and other necessary data input files from their location to the experiment directory (``$EXPTDIR``). Third, it creates the input namelist file ``input.nml`` based on the ``input.nml.FV3`` file in the ``parm`` 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.py`` script reads three other configuration scripts in order: (1) ``config_defaults.yaml`` (:numref:`Section %s `), (2) ``config.yaml`` (:numref:`Section %s `), and (3) ``set_predef_grid_params.py``. 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 ``config_defaults.yaml`` and ``config.yaml`` in :numref:`Step %s `. The settings for these paths can also be viewed in the console output from the ``./generate_FV3LAM_wflow.py`` script or in the ``log.generate_FV3LAM_wflow`` file, which can be found in ``$EXPTDIR``. - -.. _WorkflowGeneration: - -.. figure:: _static/SRW_regional_workflow_gen.png - :alt: Flowchart of the workflow generation process. Scripts are called in the following order: source_util_funcs.sh (which calls bash_utils), then set_FV3nml_sfc_climo_filenames.py, set_FV3nml_ens_stoch_seeds.py, create_diag_table_file.py, and setup.py. setup.py calls several scripts: set_cycle_dates.py, set_grid_params_GFDLgrid.py, set_grid_params_ESGgrid.py, link_fix.py, set_ozone_param.py, set_thompson_mp_fix_files.py, config_defaults.yaml, config.yaml, and valid_param_vals.yaml. Then, it sets a number of variables, including FIXgsm, TOPO_DIR, and SFC_CLIMO_INPUT_DIR variables. Next, set_predef_grid_params.py is called, and the FIXam and FIXLAM directories are set, along with the forecast input files. The setup script also calls set_extrn_mdl_params.py, sets the GRID_GEN_METHOD with HALO, checks various parameters, and generates shell scripts. Then, the workflow generation script produces a YAML configuration file and generates the actual Rocoto workflow XML file from the template file (by calling uwtools set_template). The workflow generation script checks the crontab file and, if applicable, copies certain fix files to the experiment directory. Then, it copies templates of various input files to the experiment directory and sets parameters for the input.nml file. Finally, it generates the workflow. Additional information on each step appears in comments within each script. - - *Experiment Generation Description* - -.. _WorkflowTaskDescription: - -Description of Workflow Tasks --------------------------------- - -.. note:: - 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 baseline 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 removing the ``prep.yaml`` file from the default ``taskgroups`` entry in the ``config.yaml`` file before running the ``generate_FV3LAM_wflow.py`` script: - -.. code-block:: console - - rocoto: - tasks: - taskgroups: '{{ ["parm/wflow/coldstart.yaml", "parm/wflow/post.yaml"]|include }}' - -.. _WorkflowTasksFig: - -.. figure:: _static/SRW_wflow_flowchart.png - :alt: Flowchart of the workflow tasks. If the make_grid, make_orog, and make_sfc_climo tasks are toggled off, they will not be run. If toggled on, make_grid, make_orog, and make_sfc_climo will run consecutively by calling the corresponding exregional script in the scripts directory. The get_ics, get_lbcs, make_ics, make_lbcs, and run_fcst tasks call their respective exregional scripts. The run_post task will run, and if METplus verification tasks have been configured, those will run during post-processing by calling their exregional scripts. - - *Flowchart of the Workflow Tasks* - - -The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``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 ``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:: Baseline Workflow Tasks in the SRW App - - +----------------------+------------------------------------------------------------+ - | **Workflow Task** | **Task Description** | - +======================+============================================================+ - | 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. Only | - | | needs to be run once per experiment. | - +----------------------+------------------------------------------------------------+ - | make_sfc_climo | Pre-processing task to generate surface climatology files. | - | | Only needs to be run once per experiment. | - +----------------------+------------------------------------------------------------+ - | get_extrn_ics | Cycle-specific task to obtain external data for the | - | | initial conditions (ICs) | - +----------------------+------------------------------------------------------------+ - | get_extrn_lbcs | Cycle-specific task to obtain external data for the | - | | lateral boundary conditions (LBCs) | - +----------------------+------------------------------------------------------------+ - | make_ics | Generate initial conditions from the external data | - +----------------------+------------------------------------------------------------+ - | make_lbcs | Generate LBCs from the external data | - +----------------------+------------------------------------------------------------+ - | run_fcst | Run the forecast model (UFS Weather Model) | - +----------------------+------------------------------------------------------------+ - | run_post | Run the post-processing tool (UPP) | - +----------------------+------------------------------------------------------------+ - -In addition to the baseline tasks described in :numref:`Table %s ` above, users may choose to run some or all of the METplus verification tasks. These tasks are described in :numref:`Table %s ` below. - -.. _VXWorkflowTasksTable: - -.. table:: Verification (VX) Workflow Tasks in the SRW App - - +-----------------------+------------------------------------------------------------+ - | **Workflow Task** | **Task Description** | - +=======================+============================================================+ - | GET_OBS_CCPA | Retrieves and organizes hourly :term:`CCPA` data from NOAA | - | | HPSS. Can only be run if ``verify_pre.yaml`` is included | - | | in a ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | GET_OBS_NOHRSC | Retrieves and organizes hourly :term:`NOHRSC` data from | - | | NOAA HPSS. Can only be run if ``verify_pre.yaml`` is | - | | included in a ``tasksgroups`` list *and* user has access | - | | to NOAA :term:`HPSS` data. ``ASNOW`` should also be added | - | | to the ``VX_FIELDS`` list. | - +-----------------------+------------------------------------------------------------+ - | GET_OBS_NDAS | Retrieves and organizes hourly :term:`NDAS` data from NOAA | - | | HPSS. Can only be run if ``verify_pre.yaml`` is included | - | | in a ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | GET_OBS_MRMS | Retrieves and organizes hourly :term:`MRMS` composite | - | | reflectivity and :term:`echo top` data from NOAA HPSS. Can | - | | only be run if ``verify_pre.yaml`` is included in a | - | | ``tasksgroups`` list *and* user has access to NOAA | - | | :term:`HPSS` data. | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT | Runs METplus grid-to-grid verification for 1-h accumulated | - | | precipitation | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_REFC | Runs METplus grid-to-grid verification for composite | - | | reflectivity | - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_RETOP | Runs METplus grid-to-grid verification for :term:`echo top`| - +-----------------------+------------------------------------------------------------+ - | VX_GRIDSTAT_##h | Runs METplus grid-to-grid verification for 3-h, 6-h, and | - | | 24-h (i.e., daily) accumulated precipitation. Valid values | - | | for ``##`` are ``03``, ``06``, and ``24``. | - +-----------------------+------------------------------------------------------------+ - | VX_POINTSTAT | Runs METplus grid-to-point verification for surface and | - | | upper-air variables | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID | Runs METplus grid-to-grid ensemble verification for 1-h | - | | accumulated precipitation. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_REFC | Runs METplus grid-to-grid ensemble verification for | - | | composite reflectivity. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_RETOP | Runs METplus grid-to-grid ensemble verification for | - | | :term:`echo top`. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_##h | Runs METplus grid-to-grid ensemble verification for 3-h, | - | | 6-h, and 24-h (i.e., daily) accumulated precipitation. | - | | Valid values for ``##`` are ``03``, ``06``, and ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | 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 | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | 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 | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_MEAN_##h | Runs METplus grid-to-grid verification for ensemble mean | - | | 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation. | - | | Valid values for ``##`` are ``03``, ``06``, and ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_##h | Runs METplus grid-to-grid verification for 3-h, 6-h, and | - | | 24h (i.e., daily) accumulated precipitation probabilistic | - | | output. Valid values for ``##`` are ``03``, ``06``, and | - | | ``24``. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_REFC | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for composite reflectivity. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSGRID_PROB_RETOP | Runs METplus grid-to-grid verification for ensemble | - | | probabilities for :term:`echo top`. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT | Runs METplus grid-to-point ensemble verification for | - | | surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT_MEAN | Runs METplus grid-to-point verification for ensemble mean | - | | surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - | VX_ENSPOINT_PROB | Runs METplus grid-to-point verification for ensemble | - | | probabilities for surface and upper-air variables. | - | | Can only be run if ``DO_ENSEMBLE: true`` and | - | | ``verify_ensgrid.yaml`` is included in a ``taskgroups`` | - | | list. | - +-----------------------+------------------------------------------------------------+ - - -.. _Run: - -Run the Workflow -======================= - -The workflow can be run using the Rocoto workflow manager (see :numref:`Section %s `) or using standalone wrapper scripts (see :numref:`Section %s `). - -.. attention:: - - If users are running the SRW App on a system that does not have Rocoto installed (e.g., `Level 3 & 4 `__ systems, such as MacOS or generic Linux systems), they should follow the process outlined in :numref:`Section %s ` instead of the instructions in this section. - - -.. _UseRocoto: - -Run the Workflow Using Rocoto --------------------------------- - -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, 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 three ways to run the workflow with Rocoto: (1) automation via crontab (2) by calling the ``launch_FV3LAM_wflow.sh`` script, and (3) by manually issuing the ``rocotorun`` command. - -.. 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 - - export EXPTDIR=// - -If the login shell is csh/tcsh, it can be set using: - -.. code-block:: console - - setenv EXPTDIR // - - -.. _Automate: - -Automated Option -^^^^^^^^^^^^^^^^^^^ - -The simplest way to run the Rocoto workflow is to automate the process using a job scheduler such as :term:`Cron`. For automatic resubmission of the workflow at regular intervals (e.g., every 3 minutes), the user can add the following commands to their ``config.yaml`` file *before* generating the experiment: - -.. code-block:: console - - USE_CRON_TO_RELAUNCH: true - CRON_RELAUNCH_INTVL_MNTS: 3 - -This will automatically add an appropriate entry to the user's :term:`cron table` and launch the workflow. Alternatively, the user can add a crontab entry manually using the ``crontab -e`` command. As mentioned in :numref:`Section %s `, the last line of output from ``./generate_FV3LAM_wflow.py`` (starting with ``*/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 - - */3 * * * * cd && ./launch_FV3LAM_wflow.sh called_from_cron="TRUE" - -where ```` is changed to correspond to the user's ``$EXPTDIR``. 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 * * * *`` (or ``CRON_RELAUNCH_INTVL_MNTS: 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 * * * *`` (or ``CRON_RELAUNCH_INTVL_MNTS: 3``) is the preferred option for cron jobs on non-NOAA Cloud systems. - -To check the experiment progress: - -.. code-block:: console - - 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:: - - 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. - -.. _Success: - -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 - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ========================================================================================================== - 201906151800 make_grid 4953154 SUCCEEDED 0 1 5.0 - 201906151800 make_orog 4953176 SUCCEEDED 0 1 26.0 - 201906151800 make_sfc_climo 4953179 SUCCEEDED 0 1 33.0 - 201906151800 get_extrn_ics 4953155 SUCCEEDED 0 1 2.0 - 201906151800 get_extrn_lbcs 4953156 SUCCEEDED 0 1 2.0 - 201906151800 make_ics 4953184 SUCCEEDED 0 1 16.0 - 201906151800 make_lbcs 4953185 SUCCEEDED 0 1 71.0 - 201906151800 run_fcst 4953196 SUCCEEDED 0 1 1035.0 - 201906151800 run_post_f000 4953244 SUCCEEDED 0 1 5.0 - 201906151800 run_post_f001 4953245 SUCCEEDED 0 1 4.0 - ... - 201906151800 run_post_f012 4953381 SUCCEEDED 0 1 7.0 - -If users choose to run METplus verification tasks as part of their experiment, the output above will include additional lines after ``run_post_f012``. The output will resemble the following but may be significantly longer when using ensemble verification: - -.. code-block:: console - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ========================================================================================================== - 201906151800 make_grid 30466134 SUCCEEDED 0 1 5.0 - ... - 201906151800 run_post_f012 30468271 SUCCEEDED 0 1 7.0 - 201906151800 run_gridstatvx 30468420 SUCCEEDED 0 1 53.0 - 201906151800 run_gridstatvx_refc 30468421 SUCCEEDED 0 1 934.0 - 201906151800 run_gridstatvx_retop 30468422 SUCCEEDED 0 1 1002.0 - 201906151800 run_gridstatvx_03h 30468491 SUCCEEDED 0 1 43.0 - 201906151800 run_gridstatvx_06h 30468492 SUCCEEDED 0 1 29.0 - 201906151800 run_gridstatvx_24h 30468493 SUCCEEDED 0 1 20.0 - 201906151800 run_pointstatvx 30468423 SUCCEEDED 0 1 670.0 - - -Launch the Rocoto Workflow Using a Script -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users who prefer not to automate their experiments can run the Rocoto workflow using the ``launch_FV3LAM_wflow.sh`` script provided. Simply call it without any arguments from the experiment directory: - -.. code-block:: console - - cd $EXPTDIR - ./launch_FV3LAM_wflow.sh - -This script creates a log file named ``log.launch_FV3LAM_wflow`` in ``$EXPTDIR`` or appends information to the file if it already exists. The launch script also creates the ``log/FV3LAM_wflow.log`` file, which shows Rocoto task information. Check the end of the log file periodically to see how the experiment is progressing: - -.. code-block:: console - - 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 40 log.launch_FV3LAM_wflow - -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 similar to this: - -.. code-block:: console - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ====================================================================================================== - 201906151800 make_grid druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 make_orog - - - - - - 201906151800 make_sfc_climo - - - - - - 201906151800 get_extrn_ics druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 get_extrn_lbcs druby://hfe01:33728 SUBMITTING - 0 0.0 - 201906151800 make_ics - - - - - - 201906151800 make_lbcs - - - - - - 201906151800 run_fcst - - - - - - 201906151800 run_post_00 - - - - - - 201906151800 run_post_01 - - - - - - 201906151800 run_post_02 - - - - - - 201906151800 run_post_03 - - - - - - 201906151800 run_post_04 - - - - - - 201906151800 run_post_05 - - - - - - 201906151800 run_post_06 - - - - - - - Summary of workflow status: - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - - 0 out of 1 cycles completed. - 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 task can be found in the task log files located in ``$EXPTDIR/log``. - -The workflow run is complete when all tasks have "SUCCEEDED", and the ``rocotostat`` command outputs a table similar to the one :ref:`above `. - - -.. _RocotoManualRun: - -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 manually. 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, users can load a modified ``wflow_`` modulefile, or they can use a variant on the following commands to load the Rocoto module: - -.. code-block:: console - - module use - module load rocoto - -Some systems may require a version number (e.g., ``module load rocoto/1.3.3``) - -**Run the Rocoto Workflow** - -After loading Rocoto, ``cd`` to the experiment directory and call ``rocotorun`` 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 - - cd $EXPTDIR - 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 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: - -.. code-block:: console - - cd $EXPTDIR/log - vi make_grid.log - -.. 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. - - -.. _RunUsingStandaloneScripts: - -Run the Workflow Using Stand-Alone Scripts ---------------------------------------------- - -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. - -.. attention:: - - When working on an HPC system, users should allocate a compute node prior to running their experiment. The proper command will depend on the system's resource manager, but some guidance is offered in :numref:`Section %s `. It may be necessay to reload the regional workflow (see :numref:`Section %s `). It may also be necessary to load the ``build__`` scripts as described in :numref:`Section %s `. - -#. ``cd`` into the experiment directory. For example, from ``ush``, presuming default directory settings: - - .. code-block:: console - - cd ../../expt_dirs/test_community - -#. 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 ``ush`` 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/ush/wrappers/* . - -#. Set the ``OMP_NUM_THREADS`` variable. - - .. code-block:: console - - export OMP_NUM_THREADS=1 - -#. 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 - -Each task should finish with error code 0. For example: - -.. code-block:: console - - End exregional_get_extrn_mdl_files.sh at Wed Nov 16 18:08:19 UTC 2022 with error code 0 (time elapsed: 00:00:01) - -Check the batch script output file in your experiment directory for a “SUCCESS” message near the end of the file. - -.. _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. For a brief description of tasks, see :numref:`Table %s `. - - +------------+------------------------+----------------+----------------------------+ - | **Stage/** | **Task Run Script** | **Number of** | **Wall Clock Time (H:mm)** | - | | | **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) | - +------------+------------------------+----------------+----------------------------+ - -Users can access log files for specific tasks in the ``$EXPTDIR/log`` directory. To see how the experiment is progressing, users can also check the end of the ``log.launch_FV3LAM_wflow`` file from the command line: - -.. code-block:: console - - tail -n 40 log.launch_FV3LAM_wflow - -.. 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 HPC systems can be viewed in :numref:`Section %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). From 79ef60220f863ae1fb9b6c5b17fa770585536a6a Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Fri, 25 Aug 2023 12:47:28 -0400 Subject: [PATCH 088/116] Update 18h to 18 UTC Co-authored-by: Christina Holt <56881914+christinaholtNOAA@users.noreply.github.com> --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 62cff71913..6cd3344bcf 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -592,7 +592,7 @@ Users may also wish to adjust the start, end, and increment value for the plotti If the user chooses not to set these values, the default values will be used (see :numref:`Section %s ` for defaults). .. note:: - If a forecast starts at 18h, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. + If a forecast starts at 18 UTC, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. When plotting output from a single experiment, no further adjustments are necessary. The output files (in ``.png`` format) will be located in the experiment directory under the ``$CDATE/postprd`` subdirectory where ``$CDATE`` corresponds to the cycle date and hour in YYYYMMDDHH format (e.g., ``2019061518``). From 82202e1375e8737e9cb4ab6f4df55caa92d7abfb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 25 Aug 2023 12:48:08 -0400 Subject: [PATCH 089/116] rm stray RRFS/gsi mentions --- docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index 2b1b00c5c5..36e0ee26c1 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -126,10 +126,6 @@ The :term:`umbrella repository` for the SRW Application is named ``ufs-srweather - https://github.com/NOAA-EMC/AQM-utils * - Repository for NEXUS - https://github.com/noaa-oar-arl/NEXUS - * - Repository for Gridpoint Statistical Interpolation (GSI) - - https://github.com/NOAA-EMC/GSI - * - Repository for Rapid Refresh Forecast System (RRFS) Utilities - - https://github.com/NOAA-GSL/rrfs_utl * - Repository for the Unified Workflow (UW) Toolkit - https://github.com/ufs-community/workflow-tools @@ -167,8 +163,6 @@ The ``ufs-srweather-app`` :term:`umbrella repository` is an NCO-compliant reposi ├── scripts ├── sorc │ ├── CMakeLists.txt - │ ├── (gsi) - │ ├── (rrfs_utl) │ ├── (UPP) │ │ ├── parm │ │ └── sorc From 0eba803edcfb0cb7cc81ff7b8d587ad5cdaa7b25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 25 Aug 2023 12:54:22 -0400 Subject: [PATCH 090/116] expand list of supported components --- docs/UsersGuide/source/BackgroundInfo/Components.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Components.rst b/docs/UsersGuide/source/BackgroundInfo/Components.rst index d49ff3767d..fd362ec691 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Components.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Components.rst @@ -9,7 +9,8 @@ The SRW Application assembles a variety of components, including: * Pre-processor Utilities & Initial Conditions * UFS Weather Forecast Model * Unified Post Processor -* Visualization Examples +* METplus Verification Suite +* Unified Workflow Tools * Build System and Workflow These components are documented within this User's Guide and supported through the `GitHub Discussions `__ forum. From 5a8eb8dfe1d78e58e89d80c6fdff772647eae4ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 25 Aug 2023 13:19:50 -0400 Subject: [PATCH 091/116] update notes in Container ch --- .../source/BuildingRunningTesting/ContainerQuickstart.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index 521dbdba4a..80b2c096fd 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -65,7 +65,7 @@ Build the Container ------------------------ .. hint:: - If a ``singularity: command not found`` error message appears in any of the following steps, try running: ``module load singularity``. + If a ``singularity: command not found`` error message appears when working on Level 1 platforms, try running: ``module load singularity``. Level 1 Systems ^^^^^^^^^^^^^^^^^^ @@ -89,7 +89,8 @@ On most Level 1 systems, a container named ``ubuntu20.04-intel-srwapp-develop.im +--------------+--------------------------------------------------------+ .. note:: - Singularity is not available on Gaea, and therefore container use is not supported on Gaea. + * Singularity is not available on Gaea, and therefore container use is not supported on Gaea. + * The NOAA Cloud containers are accessible only to those with EPIC resources. Users can simply set an environment variable to point to the container: @@ -418,7 +419,7 @@ If a task goes DEAD, it will be necessary to restart it according to the instruc :wq enter -.. COMMENT: Check the crontab command to reflect python workflow.s +.. COMMENT: Check the crontab command to reflect python workflow. where: From 1c8c3b9bb560bd21438584aa2cd6c387f458bd2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 25 Aug 2023 13:30:36 -0400 Subject: [PATCH 092/116] QS and container QS updates --- .../source/BuildingRunningTesting/ContainerQuickstart.rst | 8 +------- .../source/BuildingRunningTesting/Quickstart.rst | 2 +- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index 80b2c096fd..ebc0d0a145 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -408,18 +408,12 @@ For users who do not have Rocoto installed, see :numref:`Section %s `. To determine what caused the task to go DEAD, users should view the log file for the task in ``$EXPTDIR/log/``, where ```` refers to the name of the task's log file. After fixing the problem and clearing the DEAD task, it is sometimes necessary to reinitialize the crontab. Users can copy-paste the crontab command from the bottom of the ``$EXPTDIR/log.generate_FV3LAM_wflow`` file into the crontab: +If a task goes DEAD, it will be necessary to restart it according to the instructions in :numref:`Section %s `. To determine what caused the task to go DEAD, users should view the log file for the task in ``$EXPTDIR/log/``, where ```` refers to the name of the task's log file. After fixing the problem and clearing the DEAD task, it is sometimes necessary to reinitialize the crontab. Run ``crontab -e`` to open your configured editor. Inside the editor, copy-paste the crontab command from the bottom of the ``$EXPTDIR/log.generate_FV3LAM_wflow`` file into the crontab: .. code-block:: console crontab -e - i */3 * * * * cd /path/to/expt_dirs/test_community && ./launch_FV3LAM_wflow.sh called_from_cron="TRUE" - esc - :wq - enter - -.. COMMENT: Check the crontab command to reflect python workflow. where: diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst index 8a6fd5ec12..cbbf1d216f 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst @@ -94,6 +94,6 @@ 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 - The workflow must be relaunched regularly and repeatedly until the log output includes a ``Workflow status: SUCCESS`` message indicating that the experiment has finished. + The workflow must be relaunched regularly and repeatedly until the log output includes a ``Workflow status: SUCCESS`` message indicating that the experiment has finished. The :term:`cron` utility may be used to automate repeated runs. The last section of the log messages from running ``./generate_FV3LAM_wflow.py`` instruct users how to use that functionality. Users may also refer to :numref:`Section %s ` for instructions. Optionally, users may :ref:`configure their own grid `, instead of using a predefined grid, and/or :ref:`plot the output ` of their experiment(s). From 0d0257da7eceb466bd906a14c97bb23fb1df1926 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Fri, 25 Aug 2023 13:43:24 -0400 Subject: [PATCH 093/116] rm package list; add uwtools env instructions --- .../source/BuildingRunningTesting/RunSRW.rst | 36 ++++++++++--------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 6cd3344bcf..17ce887552 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -111,7 +111,7 @@ The first two steps depend on the platform being used and are described here for Load the Conda/Python Environment ------------------------------------ -The SRW App workflow is often referred to as the *regional workflow* because it runs experiments on a regional scale (unlike the *global workflow* used in other applications). The SRW App workflow requires installation of Python3 using conda; it also requires additional packages (``PyYAML``, ``Jinja2``, ``f90nml``, ``scipy``, ``matplotlib``, ``pygrib``, and ``cartopy``) built in a separate conda evironment named ``workflow_tools``. On Level 1 systems, a ``workflow_tools`` environment already exists, and users merely need to load the environment. On Level 2-4 systems, users must create and then load the environment. The process for each is described in detail below. +The SRW App workflow is often referred to as the *regional workflow* because it runs experiments on a regional scale (unlike the *global workflow* used in other applications). The SRW App workflow requires installation of Python3 using conda; it also requires additional packages built in a separate conda evironment named ``workflow_tools``. On Level 1 systems, a ``workflow_tools`` environment already exists, and users merely need to load the environment. On Level 2-4 systems, users must create and then load the environment. The process for each is described in detail below. .. _Load-WF-L1: @@ -184,25 +184,29 @@ MacOS requires the installation of a few additional packages and, possibly, an u Creating the ``workflow_tools`` Environment on Linux and Mac OS """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -On generic Mac and Linux systems, users need to create a conda ``workflow_tools`` environment. The environment can be stored in a local path, which could be a default location or a user-specified location (e.g., ``$HOME/condaenv/venvs/`` directory). (To determine the default location, use the ``conda info`` command, and look for the ``envs directories`` list.) The following is a brief recipe for creating a virtual conda environment on non-Level 1 platforms: +On generic Mac and Linux systems, users need to create a conda ``workflow_tools`` environment. The environment can be stored in a local path, which could be a default location or a user-specified location (e.g., ``$HOME/condaenv/venvs/`` directory). (To determine the default location, use the ``conda info`` command, and look for the ``envs directories`` list.) The following is a brief recipe for creating a virtual conda environment on non-Level 1 platforms. It uses the aarch64 (64-bit ARM) Miniforge for Linux and installs into $HOME/conda. Adjust as necessary for your target system. .. code-block:: console - conda create --name workflow_tools python= + wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh + bash Miniforge3-Linux-aarch64.sh -bfp ~/conda + rm Miniforge3-Linux-aarch64.sh + source ~/conda/etc/profile.d/conda.sh + conda activate + conda install -y conda-build conda-verify + cd path/to/your/workflow-tools/clone + conda build recipe + conda create -y -n workflow_tools -c local uwtools conda activate workflow_tools - conda install -c conda-forge f90nml - conda install jinja2 - conda install pyyaml - # install packages for graphics environment - conda install scipy - conda install matplotlib - conda install -c conda-forge pygrib - conda install cartopy - # verify the packages installed - conda list - conda deactivate - -where ```` is a numeric version (e.g., ``3.9.12``) in the conda base installation resulting from the query ``python3 --version``. + +In future shells, you can activate and use this environment with: + +.. code-block:: console + + source ~/conda/etc/profile.d/conda.sh + conda activate uwtools + +See the `workflow-tools respository `__ for additional documentation. Modify a ``wflow_`` File `````````````````````````````````````` From 31cc9efae548e7e519e5c542e7de99c4c8f62191 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 28 Aug 2023 10:21:25 -0400 Subject: [PATCH 094/116] clarify re EXPTDIR --- docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst index cbbf1d216f..6f9512f5fe 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst @@ -81,7 +81,7 @@ For a detailed explanation of how to build and run the SRW App on any supported ./generate_FV3LAM_wflow.py - #. Run the workflow. There are several methods available for this step, which are discussed in :numref:`Section %s `. One possible method is summarized below. It requires the :ref:`Rocoto Workflow Manager `. + #. Run the workflow from the experiment directory (``$EXPTDIR``). There are several methods available for this step, which are discussed in :numref:`Section %s `. One possible method is summarized below. It requires the :ref:`Rocoto Workflow Manager `. .. code-block:: console From 629186bb876e794dd62923f8c2b966e30219344f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 28 Aug 2023 10:27:52 -0400 Subject: [PATCH 095/116] rm confusing csh ref --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 17ce887552..2851d2454b 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -1109,18 +1109,20 @@ The SRW App workflow can be run using standalone shell scripts in cases where th When working on an HPC system, users should allocate a compute node prior to running their experiment. The proper command will depend on the system's resource manager, but some guidance is offered in :numref:`Section %s `. It may be necessary to reload the ``build__`` scripts (see :numref:`Section %s `) and the workflow environment (see :numref:`Section %s `). +.. note:: + Examples in this subsection presume that the user is running in the Terminal with a bash shell environment. If this is not the case, users will need to adjust the commands to fit their command line application and shell environment. + #. ``cd`` into the experiment directory. For example, from ``ush``, presuming default directory settings: .. code-block:: console cd ../../expt_dirs/test_community -#. Set the environment variable ``$EXPTDIR`` for either bash or csh, respectively: +#. Set the environment variable ``$EXPTDIR``: .. code-block:: console export EXPTDIR=`pwd` - setenv EXPTDIR `pwd` #. Copy the wrapper scripts from the ``ush`` directory into the experiment directory. Each workflow task has a wrapper script that sets environment variables and runs the job script. From 4713c3e7bdeccf71349306007c3953837a43c3de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Mon, 28 Aug 2023 10:49:14 -0400 Subject: [PATCH 096/116] clarify bash/csh env commands --- docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst | 2 ++ docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst index fd7291f546..babe2c6c7b 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst @@ -79,7 +79,9 @@ The cloned repository contains the configuration files and sub-directories shown .. code-block:: console + # In a bash shell, run: export SRW=$HOME/ufs-srweather-app + # In a csh shell, run: setenv SRW $HOME/ufs-srweather-app .. _FilesAndSubDirs: diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 2851d2454b..90b6003ae4 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -126,11 +126,11 @@ The ``workflow_tools`` conda/Python environment has already been set up on Level .. code-block:: console - source /path/to/etc/lmod-setup.sh/OR/lmod-setup.csh + source /path/to/etc/lmod-setup.sh module use /path/to/modulefiles module load wflow_ -where ```` refers to a valid machine name (see :numref:`Section %s ` for ``MACHINE`` options). +where ```` refers to a valid machine name (see :numref:`Section %s ` for ``MACHINE`` options). In a csh shell environment, users should replace ``lmod-setup.sh`` with ``lmod-setup.csh``. .. note:: If users source the lmod-setup file on a system that doesn't need it, it will not cause any problems (it will simply do a ``module purge``). @@ -905,7 +905,7 @@ Optionally, an environment variable can be set to navigate to the experiment dir export EXPTDIR=/path/to/experiment/directory -If the login shell is csh/tcsh, it can be set using: +If the login shell is csh/tcsh, it can instead be set using: .. code-block:: console From 9837c979e00240a552dc08dabe0ccfab8df9db6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 09:47:27 -0400 Subject: [PATCH 097/116] minor fixes --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 2 +- docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst | 2 +- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 3ee81d0c4e..fbf33b0787 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -37,7 +37,7 @@ Building, Running, and Testing the SRW App -------------------------------------------- * :numref:`Section %s: Quick Start Guide ` is designed for use on `Level 1 platforms `__ or as an overview of the workflow. - * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers can run on a broad range of systems and come with SRW App prerequisites already installed. + * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers may be run on a broad range of systems and come with SRW App prerequisites already installed. * :numref:`Section %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. * :numref:`Section %s: Running the SRW App ` provides a *detailed* explanation of how to run the SRW App after it has been built/compiled. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. * :numref:`Section %s: Testing the SRW App ` explains how to run workflow end-to-end (WE2E) tests to ensure that new developments do not break the current workflow. diff --git a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst index 6f9512f5fe..df5a61b1ef 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/Quickstart.rst @@ -81,7 +81,7 @@ For a detailed explanation of how to build and run the SRW App on any supported ./generate_FV3LAM_wflow.py - #. Run the workflow from the experiment directory (``$EXPTDIR``). There are several methods available for this step, which are discussed in :numref:`Section %s `. One possible method is summarized below. It requires the :ref:`Rocoto Workflow Manager `. + #. Run the workflow from the experiment directory (``$EXPTDIR``). By default, the path to this directory is ``${EXPT_BASEDIR}/${EXPT_SUBDIR}`` (see :numref:`Section %s ` for more detail). There are several methods for running the workflow, which are discussed in :numref:`Section %s `. One possible method is summarized below. It requires the :ref:`Rocoto Workflow Manager `. .. code-block:: console diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index 90b6003ae4..d7d002c6fe 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -196,7 +196,7 @@ On generic Mac and Linux systems, users need to create a conda ``workflow_tools` conda install -y conda-build conda-verify cd path/to/your/workflow-tools/clone conda build recipe - conda create -y -n workflow_tools -c local uwtools + conda create -y -n workflow_tools -c local workflow_tools conda activate workflow_tools In future shells, you can activate and use this environment with: From 1a8459558b40e3b3939d35a6990157eedd06cfde Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Tue, 29 Aug 2023 12:17:55 -0400 Subject: [PATCH 098/116] Update RunSRW to rm $PWD in config_utils cmd Co-authored-by: Michael Kavulich --- docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst index d7d002c6fe..0d45322897 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/RunSRW.rst @@ -405,7 +405,7 @@ To determine whether the ``config.yaml`` file adjustments are valid, users can r .. code-block:: console - ./config_utils.py -c $PWD/config.yaml -v $PWD/config_defaults.yaml -k "(?\!rocoto\b)" + ./config_utils.py -c config.yaml -v config_defaults.yaml -k "(?\!rocoto\b)" A correct ``config.yaml`` file will output a ``SUCCESS`` message. A ``config.yaml`` file with problems will output a ``FAILURE`` message describing the problem. For example: From e606bdab5926bc38c751cac105f8c339eaef894d Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Tue, 29 Aug 2023 12:39:09 -0400 Subject: [PATCH 099/116] Update Intro QS Description Co-authored-by: Michael Kavulich --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index fbf33b0787..a432c1a15f 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -36,7 +36,7 @@ Background Information Building, Running, and Testing the SRW App -------------------------------------------- - * :numref:`Section %s: Quick Start Guide ` is designed for use on `Level 1 platforms `__ or as an overview of the workflow. + * :numref:`Section %s: Quick Start Guide ` is an overview of the workflow, and gives instructions for its use on `Level 1 platforms `__. * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers may be run on a broad range of systems and come with SRW App prerequisites already installed. * :numref:`Section %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. * :numref:`Section %s: Running the SRW App ` provides a *detailed* explanation of how to run the SRW App after it has been built/compiled. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. From 109b88c50fb2e1fb9f7cbd229231c47de1c33dcf Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Tue, 29 Aug 2023 12:44:29 -0400 Subject: [PATCH 100/116] Update CQS crosslink Co-authored-by: Michael Kavulich --- .../source/BuildingRunningTesting/ContainerQuickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index ebc0d0a145..c27e9f648b 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -218,7 +218,7 @@ Users can run ``exit`` to exit the shell. 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 systems, the data required to run SRW App tests are already available as long as the bind argument (starting with ``-B``) in :numref:`Step %s ` included the directory with the input model data. See :numref:`Table %s ` for Level 1 data locations. For Level 2-4 systems, the data must be added manually by the user. In general, users can download fix file data and experiment data (:term:`ICs/LBCs`) from the `SRW App Data Bucket `__ and then untar it: +The SRW App requires input files to run. These include static datasets, initial and boundary condition files, and model configuration files. On Level 1 systems, the data required to run SRW App tests are already available as long as the bind argument (starting with ``-B``) in :numref:`Step %s ` included the directory with the input model data. See :numref:`Table %s ` for Level 1 data locations. For Level 2-4 systems, the data must be added manually by the user. In general, users can download fix file data and experiment data (:term:`ICs/LBCs`) from the `SRW App Data Bucket `__ and then untar it: .. code-block:: console From a6fb29d60d6f0d5c8c7ccfc11ca5b6e6c0fca003 Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Tue, 29 Aug 2023 12:51:07 -0400 Subject: [PATCH 101/116] Update instructions on providing error msg Co-authored-by: Michael Kavulich --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index a432c1a15f..25811f5596 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -144,7 +144,7 @@ When posting a question, it is recommended that users provide the following info * The version of the SRW Application being used (e.g., ``develop``, ``release/public-v2.1.0``). (To determine this, users can run ``git branch``, and the name of the branch with an asterisk ``*`` in front of it is the name of the branch they are working on.) Note that the version of the application being used and the version of the documentation being used should match, or users will run into difficulties. * Stage of the application when the issue appeared (i.e., configuration, build/compilation, or forecast run) * Configuration file contents -* Error message or screenshot +* Full error message (preferably in text form rather than a screenshot) * Current shell (e.g., bash, csh) and modules loaded * Compiler + MPI combination being used From 92aea33d8eae726ff6166786e02ef7954f814a15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 13:12:00 -0400 Subject: [PATCH 102/116] update software prereqs --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 2 +- .../UsersGuide/source/BackgroundInfo/TechnicalOverview.rst | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 25811f5596..04ff2979d6 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -36,7 +36,7 @@ Background Information Building, Running, and Testing the SRW App -------------------------------------------- - * :numref:`Section %s: Quick Start Guide ` is an overview of the workflow, and gives instructions for its use on `Level 1 platforms `__. + * :numref:`Section %s: Quick Start Guide ` is an overview of the workflow and gives instructions for its use on `Level 1 platforms `__. * :numref:`Section %s: Container-Based Quick Start Guide ` explains how to run the SRW Application in a container. Containers may be run on a broad range of systems and come with SRW App prerequisites already installed. * :numref:`Section %s: Building the SRW App ` provides a *detailed* explanation of how to build the SRW App. * :numref:`Section %s: Running the SRW App ` provides a *detailed* explanation of how to run the SRW App after it has been built/compiled. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow. diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index 36e0ee26c1..27749054a6 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -64,12 +64,11 @@ The UFS SRW Application has been designed so that any sufficiently up-to-date ma * git v2.12+ -* curl - -* wget - * Lmod +* wget + + * Only required for retrieving data using ``retrieve_data.py``. If data is prestaged, *wget* is not required. If data is retrieved using other means, *curl* may be used as an alternative. 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: From edb8531a7eef186fa6287701e2cccee9d9917bf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 13:35:57 -0400 Subject: [PATCH 103/116] update ESMF SCRIP abbrev --- docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst index babe2c6c7b..4ba8073df5 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/BuildSRW.rst @@ -273,7 +273,7 @@ After running ``devbuild.sh``, the executables listed in :numref:`Table %s Date: Tue, 29 Aug 2023 13:42:36 -0400 Subject: [PATCH 104/116] link to j-jobs in glossary --- docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index 27749054a6..dc9268ca70 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -201,7 +201,7 @@ SRW App SubDirectories +=========================+====================================================+ | docs | Repository documentation | +-------------------------+----------------------------------------------------+ - | jobs | J-job scripts launched by Rocoto | + | jobs | :term:`J-job` scripts launched by Rocoto | +-------------------------+----------------------------------------------------+ | modulefiles | Files used to load modules needed for building and | | | running the workflow | From 0d95dcc75dcbd875ec20f6bed1f44b9f528c72b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 13:51:39 -0400 Subject: [PATCH 105/116] update instructions on filing GitHub issues --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 04ff2979d6..26a8abab55 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -151,7 +151,11 @@ When posting a question, it is recommended that users provide the following info Bug Reports ------------- -If users have identified a bug in the system, they can report it as a `GitHub Issue `__. For new users, the best approach is typically to ask about problems in `GitHub Discussions `__ first, since many "bugs" do not require a code change/fix --- instead, the user is unfamiliar with the system and may have misunderstood some component of the system or the instructions, which is causing them problems. Asking for assistance in a `GitHub Discussion `__ post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code the requires the user to file a `GitHub Issue `__. +If users (especially new users) believe they have identified a bug in the system, it is recommended that they first ask about the problem in `GitHub Discussions `__, since many "bugs" do not require a code change/fix --- instead, the user may be unfamiliar with the system and/or may have misunderstood some component of the system or the instructions, which is causing the problem. Asking for assistance in a `GitHub Discussion `__ post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code. + +Users are also encouraged to search `open issues `__ to see if their bug has already been identified. + +If there is a genuine bug, and there is no open issue to address it, users can report the bug by filing a `GitHub Issue `__. Feature Requests and Enhancements ----------------------------------- From 705ea1584bf6b3fc2a74682d79467f430201e2c0 Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Tue, 29 Aug 2023 14:10:52 -0400 Subject: [PATCH 106/116] Update Intro info on QS Co-authored-by: Michael Kavulich --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 26a8abab55..f51a96bf03 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -48,7 +48,7 @@ Building, Running, and Testing the SRW App .. hint:: * To get started with the SRW App, it is recommended that users try one of the following options: - #. View :numref:`Section %s: Quick Start Guide ` for a quick overview of the workflow steps. + #. View :numref:`Section %s: Quick Start Guide ` for a quick overview of the workflow steps. Especially helpful for users with access to a `Level 1 platform `__. #. To build the application in a container, which provides a more uniform work environment, users can refer to :numref:`Section %s: Container-Based Quick Start Guide `. #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Section %s: Building the SRW App ` and :numref:`Section %s: Running the SRW App `. From 3823a3c26a771906cc35abfa76622e808404064b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 14:21:55 -0400 Subject: [PATCH 107/116] rm redundant umbrella repo def --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 6 +----- docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst | 2 +- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 26a8abab55..7c12e56fab 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -151,11 +151,7 @@ When posting a question, it is recommended that users provide the following info Bug Reports ------------- -If users (especially new users) believe they have identified a bug in the system, it is recommended that they first ask about the problem in `GitHub Discussions `__, since many "bugs" do not require a code change/fix --- instead, the user may be unfamiliar with the system and/or may have misunderstood some component of the system or the instructions, which is causing the problem. Asking for assistance in a `GitHub Discussion `__ post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code. - -Users are also encouraged to search `open issues `__ to see if their bug has already been identified. - -If there is a genuine bug, and there is no open issue to address it, users can report the bug by filing a `GitHub Issue `__. +If users (especially new users) believe they have identified a bug in the system, it is recommended that they first ask about the problem in `GitHub Discussions `__, since many "bugs" do not require a code change/fix --- instead, the user may be unfamiliar with the system and/or may have misunderstood some component of the system or the instructions, which is causing the problem. Asking for assistance in a `GitHub Discussion `__ post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code. Users are also encouraged to search `open issues `__ to see if their bug has already been identified. If there is a genuine bug, and there is no open issue to address it, users can report the bug by filing a `GitHub Issue `__. Feature Requests and Enhancements ----------------------------------- diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index dc9268ca70..ba5b6f3a78 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -103,7 +103,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 tags the appropriate versions of the external repositories associated with the SRW App (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. The SRW Application uses the ``manage_externals`` tool and a configuration file called ``Externals.cfg``, to pull in the appropriate versions of the external repositories associated with the SRW App (see :numref:`Table %s `). .. _top_level_repos: From 1201e24e431faa5fb8062e721162b154be371c32 Mon Sep 17 00:00:00 2001 From: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com> Date: Tue, 29 Aug 2023 14:24:42 -0400 Subject: [PATCH 108/116] Update intro w/user support recs Co-authored-by: Michael Kavulich --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 5a4630e5f8..493cb1a890 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -142,7 +142,7 @@ When posting a question, it is recommended that users provide the following info * The platform or system being used (e.g., Hera, Orion, MacOS, Linux) * The version of the SRW Application being used (e.g., ``develop``, ``release/public-v2.1.0``). (To determine this, users can run ``git branch``, and the name of the branch with an asterisk ``*`` in front of it is the name of the branch they are working on.) Note that the version of the application being used and the version of the documentation being used should match, or users will run into difficulties. -* Stage of the application when the issue appeared (i.e., configuration, build/compilation, or forecast run) +* Stage of the application when the issue appeared (i.e., configuration, build/compilation, or name of a workflow task) * Configuration file contents * Full error message (preferably in text form rather than a screenshot) * Current shell (e.g., bash, csh) and modules loaded From 09e10caebe86f41e4001e9b9aef01f4ba9fc0467 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 15:16:27 -0400 Subject: [PATCH 109/116] rm note re container binding on Jet --- .../source/BuildingRunningTesting/ContainerQuickstart.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index c27e9f648b..7f5704fd96 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -181,10 +181,6 @@ Copy ``stage-srw.sh`` from the container to the local working directory: singularity exec -B /:/ $img cp /opt/ufs-srweather-app/container-scripts/stage-srw.sh . -.. COMMENT: Is this still the case? Seems to work better on mnt than lfs now... - .. hint:: - On Jet, users may need to bind to an ``/lfs`` directory (e.g., ``/lfs4``) rather than ``/mnt``. - If the command worked properly, ``stage-srw.sh`` should appear in the local directory. 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 ``-B /:/`` argument before the name of the container. In general, it is recommended that the local base directory and container directory have the same name. For example, if the host system's top-level directory is ``/user1234``, the user can create a ``user1234`` directory in the writable container sandbox and then bind it: .. code-block:: console From 4261f08d24b7a22945be1d373b336b91d8ac37f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 15:53:31 -0400 Subject: [PATCH 110/116] Update container docs w/Apptainer info --- .../BuildingRunningTesting/ContainerQuickstart.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index 7f5704fd96..2a564f5c84 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -4,7 +4,7 @@ Container-Based Quick Start Guide ==================================== -This Container-Based Quick Start Guide will help users build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a `Singularity `__ container. The :term:`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:`MPIs `, and package versions available. Installation via Singularity container reduces this variability and allows for a smoother SRW App build experience. +This Container-Based Quick Start Guide will help users build and run the "out-of-the-box" case for the Unified Forecast System (:term:`UFS`) Short-Range Weather (SRW) Application using a `Singularity/Apptainer `__ container. The :term:`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:`MPIs `, and package versions available. Installation via container reduces this variability and allows for a smoother SRW App build experience. The basic "out-of-the-box" 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. @@ -23,13 +23,17 @@ Prerequisites Users must have an **Intel** compiler and :term:`MPI` (available for free `here `__) in order to run the SRW App in the container provided using the method described in this chapter. Additionally, it is recommended that users install the `Rocoto workflow manager `__ on their system in order to take advantage of automated workflow options. Although it is possible to run an experiment without Rocoto, and some tips are provided, the only fully-supported and tested container option assumes that Rocoto is pre-installed. -Install Singularity -^^^^^^^^^^^^^^^^^^^^^^^ +Install Singularity/Apptainer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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. +.. note:: + + As of November 2021, the Linux-supported version of Singularity has been `renamed ` to *Apptainer*. Apptainer has maintained compatibility with Singularity, so ``singularity`` commands should work with either Singularity or Apptainer (see compatibility details `here `__.) + +To build and run the SRW App using a Singularity/Apptainer container, first install the software according to the `Apptainer Installation Guide `__. This will include the installation of all dependencies. .. warning:: - Docker containers can only be run with root privileges, and users cannot have root privileges on :term:`HPCs `. Therefore, it is not possible to build the SRW App, which uses the HPC-Stack, inside a Docker container on an HPC system. However, a Singularity image may be built directly from a Docker image for use on the system. + Docker containers can only be run with root privileges, and users cannot have root privileges on :term:`HPCs `. Therefore, it is not possible to build the SRW App, which uses the spack-stack, inside a Docker container on an HPC system. However, a Singularity/Apptainer image may be built directly from a Docker image for use on the system. .. COMMENT: Update reference to HPC-Stack --> spack-stack? From 6e55e60f928bb4a74b71f96c7f97c269e84d3b77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 15:59:10 -0400 Subject: [PATCH 111/116] fix j-job xref --- docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst index ba5b6f3a78..a179d535e1 100644 --- a/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst +++ b/docs/UsersGuide/source/BackgroundInfo/TechnicalOverview.rst @@ -201,7 +201,7 @@ SRW App SubDirectories +=========================+====================================================+ | docs | Repository documentation | +-------------------------+----------------------------------------------------+ - | jobs | :term:`J-job` scripts launched by Rocoto | + | jobs | :term:`J-job ` scripts launched by Rocoto | +-------------------------+----------------------------------------------------+ | modulefiles | Files used to load modules needed for building and | | | running the workflow | From a4ca1d04ea6d3d4e954f101cb1e0c73ba5f8e236 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Tue, 29 Aug 2023 16:04:27 -0400 Subject: [PATCH 112/116] fix link --- .../source/BuildingRunningTesting/ContainerQuickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index 2a564f5c84..d783da9528 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -28,7 +28,7 @@ Install Singularity/Apptainer .. note:: - As of November 2021, the Linux-supported version of Singularity has been `renamed ` to *Apptainer*. Apptainer has maintained compatibility with Singularity, so ``singularity`` commands should work with either Singularity or Apptainer (see compatibility details `here `__.) + As of November 2021, the Linux-supported version of Singularity has been `renamed `__ to *Apptainer*. Apptainer has maintained compatibility with Singularity, so ``singularity`` commands should work with either Singularity or Apptainer (see compatibility details `here `__.) To build and run the SRW App using a Singularity/Apptainer container, first install the software according to the `Apptainer Installation Guide `__. This will include the installation of all dependencies. From 61515b8ccd00644a31cc75f282f0d786977991e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 30 Aug 2023 09:39:14 -0400 Subject: [PATCH 113/116] Change name of Ch 3 to 'Customizing the Workflow' --- .../source/BackgroundInfo/Introduction.rst | 6 +- .../TinkeringWWflowDetails/ConfigWorkflow.rst | 1238 ----------------- .../TinkeringWWflowDetails/DefineWorkflow.rst | 241 ---- .../InputOutputFiles.rst | 396 ------ .../TinkeringWWflowDetails/LAMGrids.rst | 204 --- .../TinkeringWWflowDetails/TemplateVars.rst | 77 - .../source/TinkeringWWflowDetails/index.rst | 12 - docs/UsersGuide/source/index.rst | 2 +- 8 files changed, 4 insertions(+), 2172 deletions(-) delete mode 100644 docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst delete mode 100644 docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst delete mode 100644 docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst delete mode 100644 docs/UsersGuide/source/TinkeringWWflowDetails/LAMGrids.rst delete mode 100644 docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst delete mode 100644 docs/UsersGuide/source/TinkeringWWflowDetails/index.rst diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index 493cb1a890..ea8e697fe0 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -24,7 +24,7 @@ UFS Development Team. (2022, Nov. 17). Unified Forecast System (UFS) Short-Range User's Guide Organization ============================ -The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Tinkering With Workflow Details*; and *Reference*. +The SRW Application documentation is organized into four sections: *Background Information*; *Building, Running, and Testing the SRW App*; *Customizing the Workflow*; and *Reference*. Background Information ------------------------- @@ -52,8 +52,8 @@ Building, Running, and Testing the SRW App #. To build the application in a container, which provides a more uniform work environment, users can refer to :numref:`Section %s: Container-Based Quick Start Guide `. #. For detailed instructions on building and running the SRW App, users can refer to :numref:`Section %s: Building the SRW App ` and :numref:`Section %s: Running the SRW App `. -Tinkering with Workflow Details ---------------------------------- +Customizing the Workflow +--------------------------- * :numref:`Section %s: Workflow Parameters ` documents all of the user-configurable experiment parameters that can be set in the user configuration file (``config.yaml``). * :numref:`Section %s: Input & Output Files ` describes application input and output files, as well as information on where to get publicly available data. diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst deleted file mode 100644 index 4fa1fea891..0000000000 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/ConfigWorkflow.rst +++ /dev/null @@ -1,1238 +0,0 @@ -.. _ConfigWorkflow: - -================================================================================================ -Workflow Parameters: Configuring the Workflow in ``config.yaml`` and ``config_defaults.yaml`` -================================================================================================ -To create the experiment directory and workflow when running the SRW Application, the user must create an experiment configuration file (usually named ``config.yaml``). This file contains experiment-specific information, such as forecast dates, grid and physics suite choices, data directories, and other relevant settings. To help the user, two sample configuration files have been included in the ``ush`` directory: ``config.community.yaml`` and ``config.nco.yaml``. The first is for running experiments in *community* mode (``RUN_ENVIR`` set to "community"), and the second is for running experiments in *nco* mode (``RUN_ENVIR`` set to "nco"). The content of these files can be copied into ``config.yaml`` and used as the starting point from which to generate a variety of experiment configurations for the SRW App. Note that for this release, only *community* mode is supported. - -There is an extensive list of experiment parameters that a user can set when configuring the experiment. Not all of these parameters need to be set explicitly by the user in ``config.yaml``. If a user does not define a variable in the ``config.yaml`` script, its value in ``config_defaults.yaml`` will be used, or the value will be reset depending on other parameters, such as the platform (``MACHINE``) selected for the experiment. - -.. note:: - The ``config_defaults.yaml`` file contains the full list of experiment parameters that a user may set in ``config.yaml``. The user cannot set parameters in ``config.yaml`` that are not initialized in ``config_defaults.yaml``, with the notable exception in the ``rocoto`` section, described in :numref:`Chapter %s `. - -The following is a list of the parameters in the ``config_defaults.yaml`` file. For each parameter, the default value and a brief description is provided. - -.. _user: - -USER Configuration Parameters -================================= - -If non-default parameters are selected for the variables in this section, they should be added to the ``user:`` section of the ``config.yaml`` file. - -``RUN_ENVIR``: (Default: "nco") - This variable determines the workflow mode. The user can choose between two options: "nco" and "community". The "nco" mode uses a directory structure that mimics what is used in operations at NOAA/NCEP Central Operations (NCO) and at the NOAA/NCEP/Environmental Modeling Center (EMC), which works with NCO on pre-implementation testing. Specifics of the conventions used in "nco" mode can be found in the following `WCOSS Implementation Standards `__ document: - - | NCEP Central Operations - | WCOSS Implementation Standards - | January 19, 2022 - | Version 11.0.0 - - Setting ``RUN_ENVIR`` to "community" is recommended in most cases for users who are not planning to implement their code into operations at NCO. Valid values: ``"nco"`` | ``"community"`` - -``MACHINE``: (Default: "BIG_COMPUTER") - The machine (a.k.a. platform or system) on which the workflow will run. Currently supported platforms are listed on the `SRW App Wiki page `__. When running the SRW App on any ParellelWorks/NOAA Cloud system, use "NOAACLOUD" regardless of the underlying system (AWS, GCP, or Azure). Valid values: ``"HERA"`` | ``"ORION"`` | ``"JET"`` | ``"CHEYENNE"`` | ``"GAEA"`` | ``"NOAACLOUD"`` | ``"STAMPEDE"`` | ``"ODIN"`` | ``"MACOS"`` | ``"LINUX"`` | ``"SINGULARITY"`` | ``"WCOSS2"`` - - .. hint:: - Users who are NOT on a named, supported Level 1 or 2 platform will need to set the ``MACHINE`` variable to ``LINUX`` or ``MACOS``; to combine use of a Linux or MacOS platform with the Rocoto workflow manager, users will also need to set ``WORKFLOW_MANAGER: "rocoto"`` in the ``platform:`` section of ``config.yaml``. This combination will assume a Slurm batch manager when generating the XML. - -``MACHINE_FILE``: (Default: "") - Path to a configuration file with machine-specific settings. If none is provided, ``setup.py`` will attempt to set the path to a configuration file for a supported platform. - -``ACCOUNT``: (Default: "project_name") - The account under which users submit jobs to the queue on the specified ``MACHINE``. To determine an appropriate ``ACCOUNT`` field for `Level 1 `__ systems, users may run the ``groups`` command, which will return a list of projects that the user has permissions for. Not all of the listed projects/groups have an HPC allocation, but those that do are potentially valid account names. On some systems, the ``saccount_params`` command will display additional account details. - -.. _PlatformConfig: - -PLATFORM Configuration Parameters -===================================== - -If non-default parameters are selected for the variables in this section, they should be added to the ``platform:`` section of the ``config.yaml`` file. - -``WORKFLOW_MANAGER``: (Default: "none") - The workflow manager to use (e.g., "rocoto"). This is set to "none" by default, but if the machine name is set to a platform that supports Rocoto, this will be overwritten and set to "rocoto." If set explicitly to "rocoto" along with the use of the ``MACHINE: "LINUX"`` target, the configuration layer assumes a Slurm batch manager when generating the XML. Valid values: ``"rocoto"`` | ``"none"`` - -``NCORES_PER_NODE``: (Default: "") - The number of cores available per node on the compute platform. Set for supported platforms in ``setup.py``, but it is now also configurable for all platforms. - -``BUILD_MOD_FN``: (Default: "") - Name of an alternative build module file to use if running on an unsupported platform. It is set automatically for supported machines. - -``WFLOW_MOD_FN``: (Default: "") - Name of an alternative workflow module file to use if running on an unsupported platform. It is set automatically for supported machines. - -``BUILD_VER_FN``: (Default: "") - File name containing the version of the modules used for building the app. Currently, WCOSS2 only uses this file. - -``RUN_VER_FN``: (Default: "") - File name containing the version of the modules used for running the app. Currently, WCOSS2 only uses this file. - -.. _sched: - -``SCHED``: (Default: "") - The job scheduler to use (e.g., Slurm) on the specified ``MACHINE``. Leaving this an empty string allows the experiment generation script to set it automatically depending on the machine the workflow is running on. Valid values: ``"slurm"`` | ``"pbspro"`` | ``"lsf"`` | ``"lsfcray"`` | ``"none"`` - -``SCHED_NATIVE_CMD``: (Default: "") - Allows an extra parameter to be passed to the job scheduler (Slurm or PBSPRO) via XML Native command. - -``DOMAIN_PREGEN_BASEDIR``: (Default: "") - For use in NCO mode only (``RUN_ENVIR: "nco"``). The base directory containing pregenerated grid, orography, and surface climatology files. This is an alternative for setting ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` individually. For the pregenerated grid specified by ``PREDEF_GRID_NAME``, these "fixed" files are located in: - - .. code-block:: console - - ${DOMAIN_PREGEN_BASEDIR}/${PREDEF_GRID_NAME} - - The workflow scripts will create a symlink in the experiment directory that will point to a subdirectory (having the same name as the experiment grid) under this directory. This variable should be set to a null string in ``config_defaults.yaml``, but it can be changed in the user-specified workflow configuration file set by ``EXPT_CONFIG_FN`` (usually ``config.yaml``). - -``PRE_TASK_CMDS``: (Default: "") - Pre-task commands such as ``ulimit`` needed by tasks. For example: ``'{ ulimit -s unlimited; ulimit -a; }'`` - -Machine-Dependent Parameters -------------------------------- -These parameters vary depending on machine. On `Level 1 and 2 `__ systems, the appropriate values for each machine can be viewed in the ``ush/machine/.sh`` scripts. To specify a value other than the default, add these variables and the desired value in the ``config.yaml`` file so that they override the ``config_defaults.yaml`` and machine default values. - -``PARTITION_DEFAULT``: (Default: "") - This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). This is the default partition to which Slurm submits workflow tasks. When a variable that designates the partition (e.g., ``PARTITION_HPSS``, ``PARTITION_FCST``; see below) is **not** specified, the task will be submitted to the default partition indicated in the ``PARTITION_DEFAULT`` variable. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"hera"`` | ``"normal"`` | ``"orion"`` | ``"sjet"`` | ``"vjet"`` | ``"kjet"`` | ``"xjet"`` | ``"workq"`` - -``QUEUE_DEFAULT``: (Default: "") - The default queue or QOS to which workflow tasks are submitted (QOS is Slurm's term for queue; it stands for "Quality of Service"). If the task's ``QUEUE_HPSS`` or ``QUEUE_FCST`` parameters (see below) are not specified, the task will be submitted to the queue indicated by this variable. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` - -``PARTITION_HPSS``: (Default: "") - This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). Tasks that get or create links to external model files are submitted to the partition specified in this variable. These links are needed to generate initial conditions (:term:`ICs`) and lateral boundary conditions (:term:`LBCs`) for the experiment. If this variable is not set or is set to an empty string, it will be (re)set to the ``PARTITION_DEFAULT`` value (if set) or to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"normal"`` | ``"service"`` | ``"workq"`` - -``QUEUE_HPSS``: (Default: "") - Tasks that get or create links to external model files are submitted to this queue, or QOS (QOS is Slurm's term for queue; it stands for "Quality of Service"). These links are needed to generate initial conditions (:term:`ICs`) and lateral boundary conditions (:term:`LBCs`) for the experiment. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev_transfer"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` - -``PARTITION_FCST``: (Default: "") - This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). The task that runs forecasts is submitted to this partition. If this variable is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"hera"`` | ``"normal"`` | ``"orion"`` | ``"sjet"`` | ``"vjet"`` | ``"kjet"`` | ``"xjet"`` | ``"workq"`` - -``QUEUE_FCST``: (Default: "") - The task that runs a forecast is submitted to this queue, or QOS (QOS is Slurm's term for queue; it stands for "Quality of Service"). If this variable is not set or set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` - -Parameters for Running Without a Workflow Manager ------------------------------------------------------ -These settings define the run commands for the platform. - -``RUN_CMD_UTILS``: (Default: "mpirun -np 1") - 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``). 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. - -``RUN_CMD_POST``: (Default: "mpirun -np 1") - The run command for post-processing (via the :term:`UPP`). Can be left blank for smaller domains, in which case UPP will run without :term:`MPI`. - - -METplus Parameters ----------------------- - -:ref:`METplus ` is a scientific verification framework that spans a wide range of temporal and spatial scales. Many of the METplus parameters are described below, but additional documentation for the METplus components is available on the `METplus website `__. - -.. _METParamNote: - -.. note:: - Where a date field is required: - * ``YYYY`` refers to the 4-digit valid year - * ``MM`` refers to the 2-digit valid month - * ``DD`` refers to the 2-digit valid day of the month - * ``HH`` refers to the 2-digit valid hour of the day - * ``mm`` refers to the 2-digit valid minutes of the hour - * ``SS`` refers to the two-digit valid seconds of the hour - -``CCPA_OBS_DIR``: (Default: "") - 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 :term:`HPSS` (if the user has access) via the ``get_obs_ccpa`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). - - METplus configuration files require the use of a 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. 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) for dates up until 2021-05-04. The script to pull the CCPA data from the NOAA HPSS (``scripts/exregional_get_verif_obs.sh``) has an example of how to account for this and organize the data into a more intuitive format. - -``NOHRSC_OBS_DIR``: (Default: "") - User-specified location of top-level directory where NOHRSC 06- and 24-hour snowfall accumulation files (available every 6 and 12 hours respectively) 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 :term:`HPSS` (if the user has access) via the ``get_obs_nohrsc`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). - - METplus configuration files require the use of a predetermined directory structure and file names. If the NOHRSC files are user-provided, they need to follow the anticipated naming structure: ``{YYYYMMDD}/sfav2_CONUS_{AA}h_{YYYYMMDD}{HH}_grid184.grb2``, where AA is the 2-digit accumulation duration, and 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 ``NOHRSC_OBS_DIR`` directory. METplus is configured to verify 06-, and 24-h accumulated precipitation using NOHRSC files. - - .. note:: - Due to limited availability of NOHRSC observation data on NOAA HPSS, and the likelihood that snowfall acumulation verification will not be desired outside of winter cases, this verification option is currently not present in the workflow by default. In order to use it, the verification environment variable VX_FIELDS should be updated to include ``ASNOW``. This will allow the related workflow tasks to be run. - -``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 :term:`HPSS` (if the user has access) via the ``get_obs_mrms`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. - - 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, which is why the minutes and seconds of the filename are hard-coded as "0000". Because MRMS composite reflectivity files do not typically match the valid time exactly, a script (``ush/mrms_pull_topofhour.py``) is called from within the MRMS task that identifies and renames the MRMS file nearest to the valid time to match the valid time of the forecast. This script can also be called separately for staging data independently of the workflow. - -``NDAS_OBS_DIR``: (Default: "") - User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``get_obs_ndas`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. - - METplus configuration files require the use of predetermined file names. Therefore, if the NDAS files are user-provided, they need to follow the anticipated naming structure: ``prepbufr.ndas.{YYYYMMDDHH}``, where YYYYMMDDHH is as described in the note :ref:`above `. The script to pull the NDAS data from the NOAA HPSS (``scripts/exregional_get_verif_obs.sh``) has an example of how to rename the NDAS data into a more intuitive format with the valid time listed in the file name. - -Test Directories ----------------------- - -These directories are used only by the ``run_WE2E_tests.py`` script, so they are not used unless the user runs a Workflow End-to-End (WE2E) test (see :numref:`Chapter %s `). Their function corresponds to the same variables without the ``TEST_`` prefix. Users typically should not modify these variables. For any alterations, the logic in the ``run_WE2E_tests.py`` script would need to be adjusted accordingly. - -``TEST_EXTRN_MDL_SOURCE_BASEDIR``: (Default: "") - This parameter allows testing of user-staged files in a known location on a given platform. This path contains a limited dataset and likely will not be useful for most user experiments. - -``TEST_PREGEN_BASEDIR``: (Default: "") - Similar to ``DOMAIN_PREGEN_BASEDIR``, this variable sets the base directory containing pregenerated grid, orography, and surface climatology files for WE2E tests. This is an alternative for setting ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` individually. - -``TEST_ALT_EXTRN_MDL_SYSBASEDIR_ICS``: (Default: "") - This parameter is used to test the mechanism that allows users to point to a data stream on disk. It sets up a sandbox location that mimics the stream in a more controlled way and tests the ability to access :term:`ICS`. - -``TEST_ALT_EXTRN_MDL_SYSBASEDIR_LBCS``: (Default: "") - This parameter is used to test the mechanism that allows users to point to a data stream on disk. It sets up a sandbox location that mimics the stream in a more controlled way and tests the ability to access :term:`LBCS`. - - -.. _workflow: - -WORKFLOW Configuration Parameters -===================================== - -If non-default parameters are selected for the variables in this section, they should be added to the ``workflow:`` section of the ``config.yaml`` file. - -.. _Cron: - -Cron-Associated Parameters ------------------------------- - -Cron is a job scheduler accessed through the command-line on UNIX-like operating systems. It is useful for automating tasks such as the ``rocotorun`` command, which launches each workflow task in the SRW App. Cron periodically checks a cron table (aka crontab) to see if any tasks are are ready to execute. If so, it runs them. - -``USE_CRON_TO_RELAUNCH``: (Default: false) - Flag that determines whether or not a line is added to the user's cron table, which calls the experiment launch script every ``CRON_RELAUNCH_INTVL_MNTS`` minutes. Valid values: ``True`` | ``False`` - -``CRON_RELAUNCH_INTVL_MNTS``: (Default: 3) - The interval (in minutes) between successive calls of the experiment launch script by a cron job to (re)launch the experiment (so that the workflow for the experiment kicks off where it left off). This is used only if ``USE_CRON_TO_RELAUNCH`` is set to true. - -.. _DirParams: - -Directory Parameters ------------------------ - -``EXPT_BASEDIR``: (Default: "") - The full path to the base directory in which the experiment directory (``EXPT_SUBDIR``) will be created. If this is not specified or if it is set to an empty string, it will default to ``${HOMEdir}/../expt_dirs``, where ``${HOMEdir}`` contains the full path to the ``ufs-srweather-app`` directory. If set to a relative path, the provided path will be appended to the default value ``${HOMEdir}/../expt_dirs``. For example, if ``EXPT_BASEDIR=some/relative/path`` (i.e. a path that does not begin with ``/``), the value of ``EXPT_BASEDIR`` used by the workflow will be ``EXPT_BASEDIR=${HOMEdir}/../expt_dirs/some/relative/path``. - -``EXPT_SUBDIR``: (Default: "") - The user-designated name of the experiment directory (*not* its full path). The full path to the experiment directory, which will be contained in the variable ``EXPTDIR``, will be: - - .. code-block:: console - - EXPTDIR="${EXPT_BASEDIR}/${EXPT_SUBDIR}" - - This parameter cannot be left as a null string. It must be set to a non-null value in the user-defined experiment configuration file (i.e., ``config.yaml``). - -``EXEC_SUBDIR``: (Default: "exec") - The name of the subdirectory of ``ufs-srweather-app`` where executables are installed. - -Pre-Processing File Separator Parameters --------------------------------------------- - -``DOT_OR_USCORE``: (Default: "_") - This variable sets the separator character(s) to use in the names of the grid, mosaic, and orography fixed files. Ideally, the same separator should be used in the names of these fixed files as in the surface climatology fixed files. Valid values: ``"_"`` | ``"."`` - - -Set File Name Parameters ----------------------------- - -``EXPT_CONFIG_FN``: (Default: "config.yaml") - Name of the user-specified configuration file for the forecast experiment. - -``CONSTANTS_FN``: (Default: "constants.yaml") - Name of the file containing definitions of various mathematical, physical, and SRW App contants. - -``RGNL_GRID_NML_FN``: (Default: "regional_grid.nml") - Name of the file containing namelist settings for the code that generates an "ESGgrid" regional grid. - -``FV3_NML_BASE_SUITE_FN``: (Default: "input.nml.FV3") - Name of the Fortran file containing the forecast model's base suite namelist (i.e., the portion of the namelist that is common to all physics suites). - -``FV3_NML_YAML_CONFIG_FN``: (Default: "FV3.input.yml") - Name of YAML configuration file containing the forecast model's namelist settings for various physics suites. - -``FV3_NML_BASE_ENS_FN``: (Default: "input.nml.base_ens") - Name of the Fortran file containing the forecast model's base ensemble namelist (i.e., the original namelist file from which each of the ensemble members' namelist files is generated). - -``FV3_EXEC_FN``: (Default: "ufs_model") - Name to use for the forecast model executable. - -``DIAG_TABLE_TMPL_FN``: (Default: "") - Name of a template file that specifies the output fields of the forecast model. The selected physics suite is appended to this file name in ``setup.py``, taking the form ``{DIAG_TABLE_TMPL_FN}.{CCPP_PHYS_SUITE}``. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``diag_table.{CCPP_PHYS_SUITE}``), and users should **not** specify a value for ``DIAG_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the names of the ``diag_table`` options in the ``ufs-srweather-app/parm`` directory. - -``FIELD_TABLE_TMPL_FN``: (Default: "") - Name of a template file that specifies the :term:`tracers ` that the forecast model will read in from the :term:`IC/LBC ` files. The selected physics suite is appended to this file name in ``setup.py``, taking the form ``{FIELD_TABLE_TMPL_FN}.{CCPP_PHYS_SUITE}``. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``field_table.{CCPP_PHYS_SUITE}``), and users should **not** specify a different value for ``FIELD_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the names of the ``field_table`` options in the ``ufs-srweather-app/parm`` directory. - -``DATA_TABLE_TMPL_FN``: (Default: "") - Name of a template file that contains the data table read in by the forecast model. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``data_table``), and users should **not** specify a different value for ``DATA_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``data_table`` in the ``ufs-srweather-app/parm`` directory. - -``MODEL_CONFIG_TMPL_FN``: (Default: "") - Name of a template file that contains settings and configurations for the :term:`NUOPC`/:term:`ESMF` main component. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``model_configure``), and users should **not** specify a different value for ``MODEL_CONFIG_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``model_configure`` in the ``ufs-srweather-app/parm`` directory. - -``NEMS_CONFIG_TMPL_FN``: (Default: "") - Name of a template file that contains information about the various :term:`NEMS` components and their run sequence. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``nems.configure``), and users should **not** specify a different value for ``NEMS_CONFIG_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``nems.configure`` in the ``ufs-srweather-app/parm`` directory. - -``FCST_MODEL``: (Default: "ufs-weather-model") - Name of forecast model. Valid values: ``"ufs-weather-model"`` | ``"fv3gfs_aqm"`` - -``WFLOW_XML_FN``: (Default: "FV3LAM_wflow.xml") - Name of the Rocoto workflow XML file that the experiment generation script creates. This file defines the workflow for the experiment. - -``GLOBAL_VAR_DEFNS_FN``: (Default: "var_defns.sh") - Name of the file (a shell script) containing definitions of the primary and secondary experiment variables (parameters). This file is sourced by many scripts (e.g., the J-job scripts corresponding to each workflow task) in order to make all the experiment variables available in those scripts. The primary variables are defined in the default configuration script (``config_defaults.yaml``) and in ``config.yaml``. The secondary experiment variables are generated by the experiment generation script. - -``EXTRN_MDL_VAR_DEFNS_FN``: (Default: "extrn_mdl_var_defns") - Name of the file (a shell script) containing the definitions of variables associated with the external model from which :term:`ICs` or :term:`LBCs` are generated. This file is created by the ``GET_EXTRN_*`` task because the values of the variables it contains are not known before this task runs. The file is then sourced by the ``MAKE_ICS`` and ``MAKE_LBCS`` tasks. - -``WFLOW_LAUNCH_SCRIPT_FN``: (Default: "launch_FV3LAM_wflow.sh") - Name of the script that can be used to (re)launch the experiment's Rocoto workflow. - -``WFLOW_LAUNCH_LOG_FN``: (Default: "log.launch_FV3LAM_wflow") - Name of the log file that contains the output from successive calls to the workflow launch script (``WFLOW_LAUNCH_SCRIPT_FN``). - -.. _CCPP_Params: - -CCPP Parameter ------------------- - -``CCPP_PHYS_SUITE``: (Default: "FV3_GFS_v16") - This parameter indicates which :term:`CCPP` (Common Community Physics Package) physics suite to use for the forecast(s). The choice of physics suite determines the forecast model's namelist file, the diagnostics table file, the field table file, and the XML physics suite definition file, which are staged in the experiment directory or the :term:`cycle` directories under it. - - .. note:: - For information on *stochastic physics* parameters, see :numref:`Section %s `. - - **Current supported settings for the CCPP parameter are:** - - | ``"FV3_GFS_v16"`` - | ``"FV3_RRFS_v1beta"`` - | ``"FV3_HRRR"`` - | ``"FV3_WoFS_v0"`` - | ``"FV3_RAP"`` - - Other valid values can be found in the ``ush/valid_param_vals.yaml`` file, but users can not expect full support for these schemes. - - -.. _GridGen: - -Grid Generation Parameters ------------------------------- - -``GRID_GEN_METHOD``: (Default: "") - This variable specifies which method to use to generate a regional grid in the horizontal plane. The values that it can take on are: - - * ``"ESGgrid"``: The "ESGgrid" method will generate a regional version of the Extended Schmidt Gnomonic (ESG) grid using the map projection developed by Jim Purser of EMC (:cite:t:`Purser_2020`). "ESGgrid" is the preferred grid option. More information on the ESG grid is available at https://github.com/ufs-community/ufs-srweather-app/wiki/Purser_UIFCW_2023.pdf. - - * ``"GFDLgrid"``: The "GFDLgrid" method first generates a "parent" global cubed-sphere grid. Then a portion from tile 6 of the global grid is used as the regional grid. This regional grid is referred to in the grid generation scripts as "tile 7," even though it does not correspond to a complete tile. The forecast is run only on the regional grid (i.e., on tile 7, not on tiles 1 through 6). Note that the "GFDLgrid" method is the legacy grid generation method. It is not supported in *all* predefined domains. - -.. attention:: - - If the experiment uses a **predefined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to the name of a valid predefined grid), then ``GRID_GEN_METHOD`` will be reset to the value of ``GRID_GEN_METHOD`` for that grid. This will happen regardless of whether ``GRID_GEN_METHOD`` is assigned a value in the experiment configuration file; any value assigned will be overwritten. - -.. note:: - - If the experiment uses a **user-defined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to a null string), then ``GRID_GEN_METHOD`` must be set in the experiment configuration file. Otherwise, the experiment generation will fail because the generation scripts check to ensure that the grid name is set to a non-empty string before creating the experiment directory. - -Forecast Parameters ----------------------- -``DATE_FIRST_CYCL``: (Default: "YYYYMMDDHH") - Starting date of the first forecast in the set of forecasts to run. Format is "YYYYMMDDHH". - -``DATE_LAST_CYCL``: (Default: "YYYYMMDDHH") - Starting date of the last forecast in the set of forecasts to run. Format is "YYYYMMDDHH". - -``INCR_CYCL_FREQ``: (Default: 24) - Increment in hours for Rocoto cycle frequency. The default is 24, which means cycl_freq=24:00:00. - -``FCST_LEN_HRS``: (Default: 24) - The length of each forecast, in integer hours. - -Pre-Existing Directory Parameter ------------------------------------- -``PREEXISTING_DIR_METHOD``: (Default: "delete") - This variable determines how to deal with pre-existing directories (resulting from previous calls to the experiment generation script using the same experiment name [``EXPT_SUBDIR``] as the current experiment). This variable must be set to one of three valid values: ``"delete"``, ``"rename"``, or ``"quit"``. The behavior for each of these values is as follows: - - * **"delete":** The preexisting directory is deleted and a new directory (having the same name as the original preexisting directory) is created. - - * **"rename":** The preexisting directory is renamed and a new directory (having the same name as the original pre-existing directory) is created. The new name of the preexisting directory consists of its original name and the suffix "_old###", where ``###`` is a 3-digit integer chosen to make the new name unique. - - * **"quit":** The preexisting directory is left unchanged, but execution of the currently running script is terminated. In this case, the preexisting directory must be dealt with manually before rerunning the script. - -Verbose Parameter ---------------------- -``VERBOSE``: (Default: true) - Flag that determines whether the experiment generation and workflow task scripts print out extra informational messages. Valid values: ``True`` | ``False`` - -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 be reset to true if it isn't already. Valid values: ``True`` | ``False`` - -Compiler ------------ - -``COMPILER``: (Default: "intel") - Type of compiler invoked during the build step. Currently, this must be set manually; it is not inherited from the build system in the ``ufs-srweather-app`` directory. Valid values: ``"intel"`` | ``"gnu"`` - - -.. _NCOModeParms: - -NCO-Specific Variables -========================= - -A standard set of environment variables has been established for *nco* mode to simplify the production workflow and improve the troubleshooting process for operational and preoperational models. These variables are only used in *nco* mode (i.e., when ``RUN_ENVIR: "nco"``). When non-default parameters are selected for the variables in this section, they should be added to the ``nco:`` section of the ``config.yaml`` file. - -.. note:: - Only *community* mode is fully supported for this release. *nco* mode is used by those at the Environmental Modeling Center (EMC) and Global Systems Laboratory (GSL) who are working on pre-implementation operational testing. Other users should run the SRW App in *community* mode. - -``envir, NET, model_ver, RUN``: - Standard environment variables defined in the NCEP Central Operations WCOSS Implementation Standards document. These variables are used in forming the path to various directories containing input, output, and workflow files. The variables are defined in the `WCOSS Implementation Standards `__ document (pp. 4-5) as follows: - - ``envir``: (Default: "para") - Set to "test" during the initial testing phase, "para" when running in parallel (on a schedule), and "prod" in production. - - ``NET``: (Default: "rrfs") - Model name (first level of ``com`` directory structure) - - ``model_ver``: (Default: "v1.0.0") - Version number of package in three digits (second level of ``com`` directory) - - ``RUN``: (Default: "rrfs") - Name of model run (third level of ``com`` directory structure). In general, same as ``$NET``. - -``OPSROOT``: (Default: "") - The operations root directory in *nco* mode. - -.. _make-grid: - -MAKE_GRID Configuration Parameters -====================================== - -Non-default parameters for the ``make_grid`` task are set in the ``task_make_grid:`` section of the ``config.yaml`` file. - -Basic Task Parameters --------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. Typically, users do not need to adjust the default values. - - ``GRID_DIR``: (Default: "") - The directory containing pre-generated grid files when the ``MAKE_GRID`` task is not meant to run. - -.. _ESGgrid: - -ESGgrid Settings -------------------- - -The following parameters must be set if using the "ESGgrid" method to generate a regional grid (i.e., when ``GRID_GEN_METHOD: "ESGgrid"``, see :numref:`Section %s `). If a different ``GRID_GEN_METHOD`` is used, these parameters will be ignored. When using a predefined grid with ``GRID_GEN_METHOD: "ESGgrid"``, the values in this section will be set automatically to the assigned values for that grid. - -``ESGgrid_LON_CTR``: (Default: "") - The longitude of the center of the grid (in degrees). - -``ESGgrid_LAT_CTR``: (Default: "") - The latitude of the center of the grid (in degrees). - -``ESGgrid_DELX``: (Default: "") - The cell size in the zonal direction of the regional grid (in meters). - -``ESGgrid_DELY``: (Default: "") - The cell size in the meridional direction of the regional grid (in meters). - -``ESGgrid_NX``: (Default: "") - The number of cells in the zonal direction on the regional grid. - -``ESGgrid_NY``: (Default: "") - The number of cells in the meridional direction on the regional grid. - -``ESGgrid_PAZI``: (Default: "") - The rotational parameter for the "ESGgrid" (in degrees). - -``ESGgrid_WIDE_HALO_WIDTH``: (Default: "") - The width (in number of grid cells) of the :term:`halo` to add around the regional grid before shaving the halo down to the width(s) expected by the forecast model. The user need not specify this variable since it is set automatically in ``set_gridparams_ESGgrid.py`` - -.. _WideHalo: - -.. note:: - A :term:`halo` is the strip of cells surrounding the regional grid; the halo is used to feed in the lateral boundary conditions to the grid. The forecast model requires **grid** files containing 3-cell- and 4-cell-wide halos and **orography** files with 0-cell- and 3-cell-wide halos. In order to generate grid and orography files with appropriately-sized halos, the grid and orography tasks create preliminary files with halos around the regional domain of width ``ESGgrid_WIDE_HALO_WIDTH`` cells. The files are then read in and "shaved" down to obtain grid files with 3-cell-wide and 4-cell-wide halos and orography files with 0-cell-wide and 3-cell-wide halos. The original halo that gets shaved down is referred to as the "wide" halo because it is wider than the 0-cell-wide, 3-cell-wide, and 4-cell-wide halos that users eventually end up with. Note that the grid and orography files with the wide halo are only needed as intermediates in generating the files with 0-cell-, 3-cell-, and 4-cell-wide halos; they are not needed by the forecast model. - -GFDLgrid Settings ---------------------- - -The following parameters must be set if using the "GFDLgrid" method to generate a regional grid (i.e., when ``GRID_GEN_METHOD: "GFDLgrid"``, see :numref:`Section %s `). If a different ``GRID_GEN_METHOD`` is used, these parameters will be ignored. When using a predefined grid with ``GRID_GEN_METHOD: "GFDLgrid"``, the values in this section will be set automatically to the assigned values for that grid. - -Note that the regional grid is defined with respect to a "parent" global cubed-sphere grid. Thus, all the parameters for a global cubed-sphere grid must be specified even though the model equations are integrated only on the regional grid. Tile 6 has arbitrarily been chosen as the tile to use to orient the global parent grid on the sphere (Earth). For convenience, the regional grid is denoted as "tile 7" even though it is embedded within tile 6 (i.e., it doesn't extend beyond the boundary of tile 6). Its exact location within tile 6 is determined by specifying the starting and ending i- and j-indices of the regional grid on tile 6, where ``i`` is the grid index in the x direction and ``j`` is the grid index in the y direction. All of this information is set in the variables below. - -``GFDLgrid_LON_T6_CTR``: (Default: "") - Longitude of the center of tile 6 (in degrees). - -``GFDLgrid_LAT_T6_CTR``: (Default: "") - Latitude of the center of tile 6 (in degrees). - -``GFDLgrid_NUM_CELLS``: (Default: "") - Number of grid cells in either of the two horizontal directions (x and y) on each of the six tiles of the parent global cubed-sphere grid. Valid values: ``48`` | ``96`` | ``192`` | ``384`` | ``768`` | ``1152`` | ``3072`` - - To give an idea of what these values translate to in terms of grid cell size in kilometers, we list below the approximate grid cell size on a uniform global grid having the specified value of ``GFDLgrid_NUM_CELLS``, where by "uniform" we mean with Schmidt stretch factor ``GFDLgrid_STRETCH_FAC: "1"`` (although in regional applications ``GFDLgrid_STRETCH_FAC`` will typically be set to a value greater than ``"1"`` to obtain a smaller grid size on tile 6): - - +---------------------+--------------------+ - | GFDLgrid_NUM_CELLS | Typical Cell Size | - +=====================+====================+ - | 48 | 200 km | - +---------------------+--------------------+ - | 96 | 100 km | - +---------------------+--------------------+ - | 192 | 50 km | - +---------------------+--------------------+ - | 384 | 25 km | - +---------------------+--------------------+ - | 768 | 13 km | - +---------------------+--------------------+ - | 1152 | 8.5 km | - +---------------------+--------------------+ - | 3072 | 3.2 km | - +---------------------+--------------------+ - - Note that these are only typical cell sizes. The actual cell size on the global grid tiles varies somewhat as we move across a tile and is also dependent on ``GFDLgrid_STRETCH_FAC``, which modifies the shape and size of the tile. - -``GFDLgrid_STRETCH_FAC``: (Default: "") - Stretching factor used in the Schmidt transformation applied to the parent cubed-sphere grid. Setting the Schmidt stretching factor to a value greater than 1 shrinks tile 6, while setting it to a value less than 1 (but still greater than 0) expands it. The remaining 5 tiles change shape as necessary to maintain global coverage of the grid. - -``GFDLgrid_REFINE_RATIO``: (Default: "") - Cell refinement ratio for the regional grid. It refers to the number of cells in either the x or y direction on the regional grid (tile 7) that abut one cell on its parent tile (tile 6). - -``GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G``: (Default: "") - i-index on tile 6 at which the regional grid (tile 7) starts. - -``GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G``: (Default: "") - i-index on tile 6 at which the regional grid (tile 7) ends. - -``GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G``: (Default: "") - j-index on tile 6 at which the regional grid (tile 7) starts. - -``GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G``: (Default: "") - j-index on tile 6 at which the regional grid (tile 7) ends. - -``GFDLgrid_USE_NUM_CELLS_IN_FILENAMES``: (Default: "") - Flag that determines the file naming convention to use for grid, orography, and surface climatology files (or, if using pregenerated files, the naming convention that was used to name these files). These files usually start with the string ``"C${RES}_"``, where ``RES`` is an integer. In the global forecast model, ``RES`` is the number of points in each of the two horizontal directions (x and y) on each tile of the global grid (defined here as ``GFDLgrid_NUM_CELLS``). If this flag is set to true, ``RES`` will be set to ``GFDLgrid_NUM_CELLS`` just as in the global forecast model. If it is set to false, we calculate (in the grid generation task) an "equivalent global uniform cubed-sphere resolution" --- call it ``RES_EQUIV`` --- and then set ``RES`` equal to it. ``RES_EQUIV`` is the number of grid points in each of the x and y directions on each tile that a global UNIFORM (i.e., stretch factor of 1) cubed-sphere grid would need to have in order to have the same average grid size as the regional grid. This is a more useful indicator of the grid size because it takes into account the effects of ``GFDLgrid_NUM_CELLS``, ``GFDLgrid_STRETCH_FAC``, and ``GFDLgrid_REFINE_RATIO`` in determining the regional grid's typical grid size, whereas simply setting ``RES`` to ``GFDLgrid_NUM_CELLS`` doesn't take into account the effects of ``GFDLgrid_STRETCH_FAC`` and ``GFDLgrid_REFINE_RATIO`` on the regional grid's resolution. Nevertheless, some users still prefer to use ``GFDLgrid_NUM_CELLS`` in the file names, so we allow for that here by setting this flag to true. - -.. _make-orog: - -MAKE_OROG Configuration Parameters -===================================== - -Non-default parameters for the ``make_orog`` task are set in the ``task_make_orog:`` section of the ``config.yaml`` file. - -``KMP_AFFINITY_MAKE_OROG``: (Default: "disabled") - Intel Thread Affinity Interface for the ``make_orog`` task. See :ref:`this note ` for more information on thread affinity. Settings for the ``make_orog`` task is disabled because this task does not use parallelized code. - -``OMP_NUM_THREADS_MAKE_OROG``: (Default: 6) - The number of OpenMP threads to use for parallel regions. - - - -``OMP_STACKSIZE_MAKE_OROG``: (Default: "2048m") - Controls the size of the stack for threads created by the OpenMP implementation. - -``OROG_DIR``: (Default: "") - The directory containing pre-generated orography files to use when the ``MAKE_OROG`` task is not meant to run. - -.. _make-sfc-climo: - -MAKE_SFC_CLIMO Configuration Parameters -=========================================== - -Non-default parameters for the ``make_sfc_climo`` task are set in the ``task_make_sfc_climo:`` section of the ``config.yaml`` file. - -``KMP_AFFINITY_MAKE_SFC_CLIMO``: (Default: "scatter") - Intel Thread Affinity Interface for the ``make_sfc_climo`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_MAKE_SFC_CLIMO``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_MAKE_SFC_CLIMO``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -``SFC_CLIMO_DIR``: (Default: "") - The directory containing pre-generated surface climatology files to use when the ``MAKE_SFC_CLIMO`` task is not meant to run. - -.. _task_get_extrn_ics: - -GET_EXTRN_ICS Configuration Parameters -========================================= - -Non-default parameters for the ``get_extrn_ics`` task are set in the ``task_get_extrn_ics:`` section of the ``config.yaml`` file. - -.. _basic-get-extrn-ics: - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``EXTRN_MDL_NAME_ICS``: (Default: "FV3GFS") - The name of the external model that will provide fields from which initial condition (IC) files, surface files, and 0-th hour boundary condition files will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` - -``EXTRN_MDL_ICS_OFFSET_HRS``: (Default: 0) - Users may wish to start a forecast using forecast data from a previous cycle of an external model. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should start from a 6-hour forecast of the GFS, then ``EXTRN_MDL_ICS_OFFSET_HRS: "6"``. - -``FV3GFS_FILE_FMT_ICS``: (Default: "nemsio") - If using the FV3GFS model as the source of the :term:`ICs` (i.e., if ``EXTRN_MDL_NAME_ICS: "FV3GFS"``), this variable specifies the format of the model files to use when generating the ICs. Valid values: ``"nemsio"`` | ``"grib2"`` | ``"netcdf"`` - -File and Directory Parameters --------------------------------- - -``USE_USER_STAGED_EXTRN_FILES``: (Default: false) - Flag that determines whether the workflow will look for the external model files needed for generating :term:`ICs` in user-specified directories (rather than fetching them from mass storage like NOAA :term:`HPSS`). Valid values: ``True`` | ``False`` - -``EXTRN_MDL_SOURCE_BASEDIR_ICS``: (Default: "") - Directory containing external model files for generating ICs. If ``USE_USER_STAGED_EXTRN_FILES`` is set to true, the workflow looks within this directory for a subdirectory named "YYYYMMDDHH", which contains the external model files specified by the array ``EXTRN_MDL_FILES_ICS``. This "YYYYMMDDHH" subdirectory corresponds to the start date and cycle hour of the forecast (see :ref:`above `). These files will be used to generate the :term:`ICs` on the native FV3-LAM grid. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. - -``EXTRN_MDL_SYSBASEDIR_ICS``: (Default: '') - A known location of a real data stream on a given platform. This is typically a real-time data stream as on Hera, Jet, or WCOSS. External model files for generating :term:`ICs` on the native grid should be accessible via this data stream. The way the full path containing these files is constructed depends on the user-specified external model for ICs (defined above in :numref:`Section %s ` ``EXTRN_MDL_NAME_ICS``). - - .. note:: - This variable must be defined as a null string in ``config_defaults.yaml`` so that if it is specified by the user in the experiment configuration file (``config.yaml``), it remains set to those values, and if not, it gets set to machine-dependent values. - -``EXTRN_MDL_FILES_ICS``: (Default: "") - Array containing templates of the file names to search for in the ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` directory. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. A single template should be used for each model file type that is used. Users may use any of the Python-style templates allowed in the ``ush/retrieve_data.py`` script. To see the full list of supported templates, run that script with the ``-h`` option. - - For example, to set FV3GFS nemsio input files: - - .. code-block:: console - - EXTRN_MDL_FILES_ICS=[ gfs.t{hh}z.atmf{fcst_hr:03d}.nemsio , - gfs.t{hh}z.sfcf{fcst_hr:03d}.nemsio ] - - To set FV3GFS grib files: - - .. code-block:: console - - EXTRN_MDL_FILES_ICS=[ gfs.t{hh}z.pgrb2.0p25.f{fcst_hr:03d} ] - -``EXTRN_MDL_DATA_STORES``: (Default: "") - A list of data stores where the scripts should look to find external model data. The list is in priority order. If disk information is provided via ``USE_USER_STAGED_EXTRN_FILES`` or a known location on the platform, the disk location will receive highest priority. Valid values: ``disk`` | ``hpss`` | ``aws`` | ``nomads`` - -NOMADS Parameters ---------------------- - -Set parameters associated with NOMADS online data. - -``NOMADS``: (Default: false) - Flag controlling whether to use NOMADS online data. Valid values: ``True`` | ``False`` - -``NOMADS_file_type``: (Default: "nemsio") - Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"`` - -.. _task_get_extrn_lbcs: - -GET_EXTRN_LBCS Configuration Parameters -========================================== - -Non-default parameters for the ``get_extrn_lbcs`` task are set in the ``task_get_extrn_lbcs:`` section of the ``config.yaml`` file. - -.. _basic-get-extrn-lbcs: - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``EXTRN_MDL_NAME_LBCS``: (Default: "FV3GFS") - The name of the external model that will provide fields from which lateral boundary condition (LBC) files (except for the 0-th hour LBC file) will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` - -``LBC_SPEC_INTVL_HRS``: (Default: "6") - The interval (in integer hours) at which LBC files will be generated. This is also referred to as the *boundary update interval*. Note that the model selected in ``EXTRN_MDL_NAME_LBCS`` must have data available at a frequency greater than or equal to that implied by ``LBC_SPEC_INTVL_HRS``. For example, if ``LBC_SPEC_INTVL_HRS`` is set to "6", then the model must have data available at least every 6 hours. It is up to the user to ensure that this is the case. - -``EXTRN_MDL_LBCS_OFFSET_HRS``: (Default: "") - Users may wish to use lateral boundary conditions from a forecast that was started earlier than the start of the forecast configured here. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should use lateral boundary conditions from the GFS started 6 hours earlier, then ``EXTRN_MDL_LBCS_OFFSET_HRS: "6"``. Note: the default value is model-dependent and is set in ``ush/set_extrn_mdl_params.py``. - -``FV3GFS_FILE_FMT_LBCS``: (Default: "nemsio") - If using the FV3GFS model as the source of the :term:`LBCs` (i.e., if ``EXTRN_MDL_NAME_LBCS: "FV3GFS"``), this variable specifies the format of the model files to use when generating the LBCs. Valid values: ``"nemsio"`` | ``"grib2"`` | ``"netcdf"`` - - -File and Directory Parameters --------------------------------- - -``USE_USER_STAGED_EXTRN_FILES``: (Default: false) - Analogous to ``USE_USER_STAGED_EXTRN_FILES`` in :term:`ICs` but for :term:`LBCs`. Flag that determines whether the workflow will look for the external model files needed for generating :term:`LBCs` in user-specified directories (rather than fetching them from mass storage like NOAA :term:`HPSS`). Valid values: ``True`` | ``False`` - -``EXTRN_MDL_SOURCE_BASEDIR_LBCS``: (Default: "") - Analogous to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` but for :term:`LBCs` instead of :term:`ICs`. - Directory containing external model files for generating LBCs. If ``USE_USER_STAGED_EXTRN_FILES`` is set to true, the workflow looks within this directory for a subdirectory named "YYYYMMDDHH", which contains the external model files specified by the array ``EXTRN_MDL_FILES_LBCS``. This "YYYYMMDDHH" subdirectory corresponds to the start date and cycle hour of the forecast (see :ref:`above `). These files will be used to generate the :term:`LBCs` on the native FV3-LAM grid. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. - -``EXTRN_MDL_SYSBASEDIR_LBCS``: (Default: '') - Same as ``EXTRN_MDL_SYSBASEDIR_ICS`` but for :term:`LBCs`. A known location of a real data stream on a given platform. This is typically a real-time data stream as on Hera, Jet, or WCOSS. External model files for generating :term:`LBCs` on the native grid should be accessible via this data stream. The way the full path containing these files is constructed depends on the user-specified external model for LBCs (defined above in :numref:`Section %s ` ``EXTRN_MDL_NAME_LBCS`` above). - - .. note:: - This variable must be defined as a null string in ``config_defaults.yaml`` so that if it is specified by the user in the experiment configuration file (``config.yaml``), it remains set to those values, and if not, it gets set to machine-dependent values. - -``EXTRN_MDL_FILES_LBCS``: (Default: "") - Analogous to ``EXTRN_MDL_FILES_ICS`` but for :term:`LBCs` instead of :term:`ICs`. Array containing templates of the file names to search for in the ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` directory. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. A single template should be used for each model file type that is used. Users may use any of the Python-style templates allowed in the ``ush/retrieve_data.py`` script. To see the full list of supported templates, run that script with the ``-h`` option. For examples, see the ``EXTRN_MDL_FILES_ICS`` variable above. - -``EXTRN_MDL_DATA_STORES``: (Default: "") - Analogous to ``EXTRN_MDL_DATA_STORES`` in :term:`ICs` but for :term:`LBCs`. A list of data stores where the scripts should look to find external model data. The list is in priority order. If disk information is provided via ``USE_USER_STAGED_EXTRN_FILES`` or a known location on the platform, the disk location will receive highest priority. Valid values: ``disk`` | ``hpss`` | ``aws`` | ``nomads`` - -NOMADS Parameters ---------------------- - -Set parameters associated with NOMADS online data. Analogus to :term:`ICs` NOMADS Parameters. - -``NOMADS``: (Default: false) - Flag controlling whether to use NOMADS online data. - -``NOMADS_file_type``: (Default: "nemsio") - Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"`` - -MAKE_ICS Configuration Parameters -====================================== - -Non-default parameters for the ``make_ics`` task are set in the ``task_make_ics:`` section of the ``config.yaml`` file. - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``KMP_AFFINITY_MAKE_ICS``: (Default: "scatter") - Intel Thread Affinity Interface for the ``make_ics`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_MAKE_ICS``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_MAKE_ICS``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -FVCOM Parameter -------------------- -``USE_FVCOM``: (Default: false) - Flag that specifies whether to update surface conditions in FV3-:term:`LAM` with fields generated from the Finite Volume Community Ocean Model (:term:`FVCOM`). If set to true, lake/sea surface temperatures, ice surface temperatures, and ice placement will be overwritten using data provided by FVCOM. Setting ``USE_FVCOM`` to true causes the executable ``process_FVCOM.exe`` in the ``MAKE_ICS`` task to run. This, in turn, modifies the file ``sfc_data.nc`` generated by ``chgres_cube`` during the ``make_ics`` task. Note that the FVCOM data must already be interpolated to the desired FV3-LAM grid. Valid values: ``True`` | ``False`` - -``FVCOM_WCSTART``: (Default: "cold") - Define if this is a "warm" start or a "cold" start. Setting this to "warm" will read in ``sfc_data.nc`` generated in a RESTART directory. Setting this to "cold" will read in the ``sfc_data.nc`` generated from ``chgres_cube`` in the ``make_ics`` portion of the workflow. Valid values: ``"cold"`` | ``"COLD"`` | ``"warm"`` | ``"WARM"`` - -``FVCOM_DIR``: (Default: "") - User-defined directory where the ``fvcom.nc`` file containing :term:`FVCOM` data already interpolated to the FV3-LAM native grid is located. The file in this directory must be named ``fvcom.nc``. - -``FVCOM_FILE``: (Default: "fvcom.nc") - Name of the file located in ``FVCOM_DIR`` that has :term:`FVCOM` data interpolated to the FV3-LAM grid. This file will be copied later to a new location, and the name will be changed to ``fvcom.nc`` if a name other than ``fvcom.nc`` is selected. - - -MAKE_LBCS Configuration Parameters -====================================== - -Non-default parameters for the ``make_lbcs`` task are set in the ``task_make_lbcs:`` section of the ``config.yaml`` file. - -``KMP_AFFINITY_MAKE_LBCS``: (Default: "scatter") - Intel Thread Affinity Interface for the ``make_lbcs`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_MAKE_LBCS``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_MAKE_LBCS``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -.. _FcstConfigParams: - -FORECAST Configuration Parameters -===================================== - -Non-default parameters for the ``run_fcst`` task are set in the ``task_run_fcst:`` section of the ``config.yaml`` file. - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``KMP_AFFINITY_RUN_FCST``: (Default: "scatter") - Intel Thread Affinity Interface for the ``run_fcst`` task. - -.. _thread-affinity: - - .. note:: - - **Thread Affinity Interface** - - "Intel's runtime library can bind OpenMP threads to physical processing units. The interface is controlled using the ``KMP_AFFINITY`` environment variable. Thread affinity restricts execution of certain threads to a subset of the physical processing units in a multiprocessor computer. Depending on the system (machine) topology, application, and operating system, thread affinity can have a dramatic effect on the application speed and on the execution speed of a program." Valid values: ``"scatter"`` | ``"disabled"`` | ``"balanced"`` | ``"compact"`` | ``"explicit"`` | ``"none"`` - - For more information, see the `Intel Development Reference Guide `__. - -``OMP_NUM_THREADS_RUN_FCST``: (Default: 2) - The number of OpenMP threads to use for parallel regions. Corresponds to the ``atmos_nthreads`` value in ``model_configure``. - -``OMP_STACKSIZE_RUN_FCST``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -.. _ModelConfigParams: - -Model Configuration Parameters ----------------------------------- - -These parameters set values in the Weather Model's ``model_configure`` file. - -``DT_ATMOS``: (Default: "") - Time step for the outermost atmospheric model loop in seconds. This corresponds to the frequency at which the physics routines and the top level dynamics routine are called. (Note that one call to the top-level dynamics routine results in multiple calls to the horizontal dynamics, :term:`tracer` transport, and vertical dynamics routines; see the `FV3 dycore scientific documentation `__ for details.) Must be set. Takes an integer value. In the SRW App, a default value for ``DT_ATMOS`` appears in the ``set_predef_grid_params.yaml`` script, but a different value can be set in ``config.yaml``. In general, the smaller the grid cell size is, the smaller this value needs to be in order to avoid numerical instabilities during the forecast. - -``RESTART_INTERVAL``: (Default: 0) - Frequency of the output restart files in hours. Using the default interval (0), restart files are produced at the end of a forecast run. When ``RESTART_INTERVAL: 1``, restart files are produced every hour with the prefix "YYYYMMDD.HHmmSS." in the ``RESTART`` directory. - -.. _InlinePost: - -``WRITE_DOPOST``: (Default: false) - Flag that determines whether to use the inline post option. The default ``WRITE_DOPOST: false`` does not use the inline post functionality, and the ``run_post`` tasks are called from outside of the Weather Model. If ``WRITE_DOPOST: true``, the ``WRITE_DOPOST`` flag in the ``model_configure`` file will be set to true, and the post-processing (:term:`UPP`) tasks will be called from within the Weather Model. This means that the post-processed files (in :term:`grib2` format) are output by the Weather Model at the same time that it outputs the ``dynf###.nc`` and ``phyf###.nc`` files. Setting ``WRITE_DOPOST: true`` turns off the separate ``run_post`` task in ``setup.py`` to avoid unnecessary computations. Valid values: ``True`` | ``False`` - -Computational Parameters ----------------------------- - -``LAYOUT_X, LAYOUT_Y``: (Default: "") - The number of :term:`MPI` tasks (processes) to use in the two horizontal directions (x and y) of the regional grid when running the forecast model. - -``BLOCKSIZE``: (Default: "") - The amount of data that is passed into the cache at a time. - -.. note:: - - In ``config_defaults.yaml`` the computational parameters are set to null strings so that: - - #. If the experiment is using a predefined grid and the user sets the parameter in the user-specified experiment configuration file (i.e., ``config.yaml``), that value will be used in the forecast(s). Otherwise, the default value for that predefined grid will be used. - #. If the experiment is *not* using a predefined grid (i.e., it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the parameter in that configuration file. Otherwise, the parameter will remain set to a null string, and the experiment generation will fail because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory. - -.. _WriteComp: - -Write-Component (Quilting) Parameters ------------------------------------------ - -.. note:: - The :term:`UPP` (called by the ``RUN_POST`` 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 use an Earth System Modeling Framework (:term:`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``. - - 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`` (meta)task cannot run because the :term:`UPP` code called by this task cannot process fields on the native grid. In that case, the ``RUN_POST`` (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. Valid values: ``True`` | ``False`` - -``PRINT_ESMF``: (Default: false) - Flag that determines whether to output extra (debugging) information from :term:`ESMF` routines. 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). Valid values: ``True`` | ``False`` - -``WRTCMP_write_groups``: (Default: 1) - The number of write groups (i.e., groups of :term:`MPI` tasks) to use in the write component. Each write group will write 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 ``WRTCMP_write_tasks_per_group`` tasks. Usually, one write group is sufficient. 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. - -``WRTCMP_write_tasks_per_group``: (Default: 20) - 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.yaml`` 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. - -``WRTCMP_cen_lat``: (Default: "") - 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 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 when running an experiment with a user-defined grid. - -**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "rotated_latlon":** - -``WRTCMP_lon_upr_rght``: (Default: "") - Longitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated longitude). - -``WRTCMP_lat_upr_rght``: (Default: "") - Latitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated latitude). - -``WRTCMP_dlon``: (Default: "") - Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated longitude). - -``WRTCMP_dlat``: (Default: "") - Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated latitude). - -**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "lambert_conformal":** - -``WRTCMP_stdlat1``: (Default: "") - First standard latitude (in degrees) in definition of Lambert conformal projection. - -``WRTCMP_stdlat2``: (Default: "") - Second standard latitude (in degrees) in definition of Lambert conformal projection. - -``WRTCMP_nx``: (Default: "") - Number of grid points in the x-coordinate of the Lambert conformal projection. - -``WRTCMP_ny``: (Default: "") - Number of grid points in the y-coordinate of the Lambert conformal projection. - -``WRTCMP_dx``: (Default: "") - Grid cell size (in meters) along the x-axis of the Lambert conformal projection. - -``WRTCMP_dy``: (Default: "") - Grid cell size (in meters) along the y-axis of the Lambert conformal projection. - -.. _PredefGrid: - -Predefined Grid Parameters ------------------------------- - -``PREDEF_GRID_NAME``: (Default: "") - This parameter indicates which (if any) predefined regional grid to use for the experiment. Setting ``PREDEF_GRID_NAME`` provides a convenient method of specifying a commonly used set of grid-dependent parameters. The predefined grid settings can be viewed in the script ``ush/set_predef_grid_params.yaml``. - - **Currently supported options:** - - | ``"RRFS_CONUS_25km"`` - | ``"RRFS_CONUS_13km"`` - | ``"RRFS_CONUS_3km"`` - | ``"SUBCONUS_Ind_3km"`` - - **Other valid values include:** - - | ``"CONUS_25km_GFDLgrid"`` - | ``"CONUS_3km_GFDLgrid"`` - | ``"EMC_AK"`` - | ``"EMC_HI"`` - | ``"EMC_PR"`` - | ``"EMC_GU"`` - | ``"GSL_HAFSV0.A_25km"`` - | ``"GSL_HAFSV0.A_13km"`` - | ``"GSL_HAFSV0.A_3km"`` - | ``"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:: - - * If ``PREDEF_GRID_NAME`` is set to a valid predefined grid name, the grid generation 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.yaml``). 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. - - * If ``PREDEF_GRID_NAME`` is set to an empty string, it implies that the user will provide the native grid parameters in the user-specified experiment configuration file (``config.yaml``). In this case, the grid generation method, the native grid parameters, the write component grid parameters, the main time step (``DT_ATMOS``), and the computational parameters (``LAYOUT_X``, ``LAYOUT_Y``, and ``BLOCKSIZE``) must be set in the configuration file. Otherwise, the values of the parameters in the default experiment configuration file (``config_defaults.yaml``) will be used. - -Aerosol Climatology Parameter ---------------------------------- - -``USE_MERRA_CLIMO``: (Default: false) - Flag that determines whether :term:`MERRA2` aerosol climatology data and lookup tables for optics properties are obtained. Valid values: ``True`` | ``False`` - - .. COMMENT: When would it be appropriate to obtain these files? - -Fixed File Parameters -------------------------- - -These parameters are associated with the fixed (i.e., static) files. On `Level 1 & 2 `__ systems, fixed files are pre-staged with paths defined in the ``setup.py`` script. Because the default values are platform-dependent, they are set to a null string in ``config_defaults.yaml``. Then these null values are overwritten in ``setup.py`` with machine-specific values or with a user-specified value from ``config.yaml``. - -``FIXgsm``: (Default: "") - System directory in which the majority of fixed (i.e., time-independent) files that are needed to run the FV3-LAM model are located. - -``FIXaer``: (Default: "") - System directory where :term:`MERRA2` aerosol climatology files are located. - -``FIXlut``: (Default: "") - System directory where the lookup tables for optics properties are located. - -``FIXshp``: (Default: "") - System directory where the graphics shapefiles are located. On Level 1 systems, these are set within the machine files. Users on other systems will need to provide the path to the directory that contains the *Natural Earth* shapefiles. - -``FIXorg``: (Default: "") - The location on disk of the static input files used by the ``make_orog`` task (i.e., ``orog.x`` and ``shave.x``). Can be the same as ``FIXgsm``. - -``FIXsfc``: (Default: "") - The location on disk of the static surface climatology input fields, used by ``sfc_climo_gen``. These files are only used if the ``MAKE_SFC_CLIMO`` task is meant to run. - -``SYMLINK_FIX_FILES``: (Default: true) - Flag that indicates whether to symlink or copy fix files to the experiment directory. - -RUN_POST Configuration Parameters -===================================== - -Non-default parameters for the ``run_post`` task are set in the ``task_run_post:`` section of the ``config.yaml`` file. - -Basic Task Parameters ---------------------------------- - -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``KMP_AFFINITY_RUN_POST``: (Default: "scatter") - Intel Thread Affinity Interface for the ``run_post`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_RUN_POST``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_RUN_POST``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - - -Subhourly Post Parameters ------------------------------ -Set parameters associated with subhourly forecast model output and post-processing. - -``SUB_HOURLY_POST``: (Default: false) - 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 valid value between 1 and 59. Valid values: ``True`` | ``False`` - -``DT_SUB_HOURLY_POST_MNTS``: (Default: 0) - Time interval in minutes between the forecast model output files (only used if ``SUB_HOURLY_POST`` is set to true). If ``SUB_HOURLY_POST`` is set to true, this needs to be set to a valid two-digit integer between 1 and 59. Note that if ``SUB_HOURLY_POST`` is set to true but ``DT_SUB_HOURLY_POST_MNTS`` is set to 0, ``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: ``0`` | ``1`` | ``2`` | ``3`` | ``4`` | ``5`` | ``6`` | ``10`` | ``12`` | ``15`` | ``20`` | ``30`` - -Customized Post Configuration Parameters --------------------------------------------- - -Set parameters for customizing the :term:`UPP`. - -``USE_CUSTOM_POST_CONFIG_FILE``: (Default: false) - Flag that determines whether a user-provided custom configuration file should be used for post-processing the model data. If this is set to true, then the workflow will use the custom post-processing (:term:`UPP`) configuration file specified in ``CUSTOM_POST_CONFIG_FP``. Otherwise, a default configuration file provided in the UPP repository will be used. Valid values: ``True`` | ``False`` - -``CUSTOM_POST_CONFIG_FP``: (Default: "") - The full path to the custom post flat file, including filename, to be used for post-processing. This is only used if ``CUSTOM_POST_CONFIG_FILE`` is set to true. - -``POST_OUTPUT_DOMAIN_NAME``: (Default: "") - Domain name (in lowercase) used to construct the names of the output files generated by the :term:`UPP`. If using a predefined grid, ``POST_OUTPUT_DOMAIN_NAME`` defaults to ``PREDEF_GRID_NAME``. If using a custom grid, ``POST_OUTPUT_DOMAIN_NAME`` must be specified by the user. The post output files are named as follows: - - .. code-block:: console - - $NET.tHHz.[var_name].f###.${POST_OUTPUT_DOMAIN_NAME}.grib2 - - Note that this variable is first changed to lower case before being used to construct the file names. - -RUN_PRDGEN Configuration Parameters -===================================== - -Non-default parameters for the ``run_prdgen`` task are set in the ``task_run_prdgen:`` section of the ``config.yaml`` file. - -Basic Task Parameters ---------------------------------- -For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. - -``KMP_AFFINITY_RUN_PRDGEN``: (Default: "scatter") - Intel Thread Affinity Interface for the ``run_prdgen`` task. See :ref:`this note ` for more information on thread affinity. - -``OMP_NUM_THREADS_RUN_PRDGEN``: (Default: 1) - The number of OpenMP threads to use for parallel regions. - -``OMP_STACKSIZE_RUN_PRDGEN``: (Default: "1024m") - Controls the size of the stack for threads created by the OpenMP implementation. - -``DO_PARALLEL_PRDGEN``: (Default: false) - Flag that determines whether to use CFP to run the product generation job in parallel. CFP is a utility that allows the user to launch a number of small jobs across nodes/cpus in one batch command. This option should be used with the ``RRFS_NA_3km`` grid and ``PPN_RUN_PRDGEN`` should be set to 22. - -``ADDNL_OUTPUT_GRIDS``: (Default: []) - Set additional output grids for wgrib2 remapping, if any. Space-separated list of strings, e.g., ( "130" "242" "clue"). Default is no additional grids. - -``TESTBED_FIELDS_FN``: (Default: "") - The file which lists grib2 fields to be extracted for testbed files. Empty string means no need to generate testbed files. - -.. _PlotVars: - -PLOT_ALLVARS Configuration Parameters -======================================== - -Typically, the following parameters must be set explicitly by the user in the configuration file (``config.yaml``) when executing the plotting tasks. - -``COMOUT_REF``: (Default: "") - The directory where the GRIB2 files from post-processing are located. In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will correspond to the location in the experiment directory where the post-processed output can be found (e.g., ``$EXPTDIR/$DATE_FIRST_CYCL/postprd``). In *nco* mode, this directory should be set to the location of the ``COMOUT`` directory and end with ``$PDY/$cyc``. For more detail on *nco* standards and directory naming conventions, see `WCOSS Implementation Standards `__ (particularly pp. 4-5). - -``PLOT_FCST_START``: (Default: 0) - The starting forecast hour for the plotting task. For example, if a forecast starts at 18h/18z, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. If a forecast starts at 18h/18z, but the user only wants plots from the 6th forecast hour on, "starting forecast hour" should be 6. - -``PLOT_FCST_INC``: (Default: 3) - Forecast hour increment for the plotting task. For example, if the user wants plots for each forecast hour, they should set ``PLOT_FCST_INC: 1``. If the user only wants plots for some of the output (e.g., every 6 hours), they should set ``PLOT_FCST_INC: 6``. - -``PLOT_FCST_END``: (Default: "") - The last forecast hour for the plotting task. For example, if a forecast run for 24 hours, and the user wants plots for each available hour of forecast output, they should set ``PLOT_FCST_END: 24``. If the user only wants plots from the first 12 hours of the forecast, the "last forecast hour" should be 12. - -``PLOT_DOMAINS``: (Default: ["conus"]) - Domains to plot. Currently supported options are ["conus"], ["regional"], or both (i.e., ["conus", "regional"]). - -Global Configuration Parameters -=================================== - -Non-default parameters for the miscellaneous tasks are set in the ``global:`` section of the ``config.yaml`` file. - -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`). :numref:`Section %s ` includes further instructions on how to do this. - -``USE_CRTM``: (Default: false) - Flag that defines whether external :term:`CRTM` coefficient files have been staged by the user in order to output synthetic satellite products available within the :term:`UPP`. If this is set to true, then the workflow will check for these files in the directory ``CRTM_DIR``. Otherwise, it is assumed that no satellite fields are being requested in the UPP configuration. Valid values: ``True`` | ``False`` - -``CRTM_DIR``: (Default: "") - This is the path to the top CRTM fix file directory. This is only used if ``USE_CRTM`` is set to true. - - -Ensemble Model Parameters ------------------------------ - -Set parameters associated with running ensembles. - -``DO_ENSEMBLE``: (Default: false) - Flag that determines whether to run a set of ensemble forecasts (for each set of specified cycles). If this is set to true, ``NUM_ENS_MEMBERS`` forecasts are run for each cycle, each with a different set of stochastic seed values. When false, a single forecast is run for each cycle. Valid values: ``True`` | ``False`` - -``NUM_ENS_MEMBERS``: (Default: 1) - The number of ensemble members to run if ``DO_ENSEMBLE`` is set to true. This variable also controls the naming of the ensemble member directories. For example, if ``NUM_ENS_MEMBERS`` is set to 8, the member directories will be named *mem1, mem2, ..., mem8*. This variable is not used unless ``DO_ENSEMBLE`` is set to true. - -.. _stochastic-physics: - -Stochastic Physics Parameters ----------------------------------- - -Set default ad-hoc stochastic physics options. For the most updated and detailed documentation of these parameters, see the `UFS Stochastic Physics Documentation `__. - -``NEW_LSCALE``: (Default: true) - Use correct formula for converting a spatial legnth scale into spectral space. - -Specific Humidity (SHUM) Perturbation Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``DO_SHUM``: (Default: false) - Flag to turn Specific Humidity (SHUM) perturbations on or off. SHUM perturbations multiply the low-level specific humidity by a small random number at each time-step. The SHUM scheme attempts to address missing physics phenomena (e.g., cold pools, gust fronts) most active in convective regions. Valid values: ``True`` | ``False`` - -``ISEED_SHUM``: (Default: 2) - Seed for setting the SHUM random number sequence. - -``SHUM_MAG``: (Default: 0.006) - Amplitudes of random patterns. Corresponds to the variable ``shum`` in ``input.nml``. - -``SHUM_LSCALE``: (Default: 150000) - Decorrelation spatial scale in meters. - -``SHUM_TSCALE``: (Default: 21600) - Decorrelation timescale in seconds. Corresponds to the variable ``shum_tau`` in ``input.nml``. - -``SHUM_INT``: (Default: 3600) - Interval in seconds to update random pattern (optional). Perturbations still get applied at every time-step. Corresponds to the variable ``shumint`` in ``input.nml``. - -.. _SPPT: - -Stochastically Perturbed Physics Tendencies (SPPT) Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -SPPT perturbs full physics tendencies *after* the call to the physics suite, unlike :ref:`SPP ` (below), which perturbs specific tuning parameters within a physics scheme. - -``DO_SPPT``: (Default: false) - Flag to turn Stochastically Perturbed Physics Tendencies (SPPT) on or off. SPPT multiplies the physics tendencies by a random number between 0 and 2 before updating the model state. This addresses error in the physics parameterizations (either missing physics or unresolved subgrid processes). It is most active in the boundary layer and convective regions. Valid values: ``True`` | ``False`` - -``ISEED_SPPT``: (Default: 1) - Seed for setting the SPPT random number sequence. - -``SPPT_MAG``: (Default: 0.7) - Amplitude of random patterns. Corresponds to the variable ``sppt`` in ``input.nml``. - -``SPPT_LOGIT``: (Default: true) - Limits the SPPT perturbations to between 0 and 2. Should be "TRUE"; otherwise the model will crash. - -``SPPT_LSCALE``: (Default: 150000) - Decorrelation spatial scale in meters. - -``SPPT_TSCALE``: (Default: 21600) - Decorrelation timescale in seconds. Corresponds to the variable ``sppt_tau`` in ``input.nml``. - -``SPPT_INT``: (Default: 3600) - Interval in seconds to update random pattern (optional parameter). Perturbations still get applied at every time-step. Corresponds to the variable ``spptint`` in ``input.nml``. - -``SPPT_SFCLIMIT``: (Default: true) - When true, tapers the SPPT perturbations to zero at the model's lowest level, which reduces model crashes. - -``USE_ZMTNBLCK``: (Default: false) - When true, do not apply perturbations below the dividing streamline that is diagnosed by the gravity wave drag, mountain blocking scheme. Valid values: ``True`` | ``False`` - - -Stochastic Kinetic Energy Backscatter (SKEB) Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``DO_SKEB``: (Default: false) - Flag to turn Stochastic Kinetic Energy Backscatter (SKEB) on or off. SKEB adds wind perturbations to the model state. Perturbations are random in space/time, but amplitude is determined by a smoothed dissipation estimate provided by the :term:`dynamical core`. SKEB addresses errors in the dynamics more active in the mid-latitudes. Valid values: ``True`` | ``False`` - -``ISEED_SKEB``: (Default: 3) - Seed for setting the SHUM random number sequence. - -``SKEB_MAG``: (Default: 0.5) - Amplitude of random patterns. Corresponds to the variable ``skeb`` in ``input.nml``. - -``SKEB_LSCALE``: (Default: 150000) - Decorrelation spatial scale in meters. - -``SKEB_TSCALE``: (Default: 21600) - Decorrelation timescale in seconds. Corresponds to the variable ``skeb_tau`` in ``input.nml``. - -``SKEB_INT``: (Default: 3600) - Interval in seconds to update random pattern (optional). Perturbations still get applied every time-step. Corresponds to the variable ``skebint`` in ``input.nml``. - -``SKEBNORM``: (Default: 1) - Patterns: - * 0-random pattern is stream function - * 1-pattern is K.E. norm - * 2-pattern is vorticity - -``SKEB_VDOF``: (Default: 10) - The number of degrees of freedom in the vertical direction for the SKEB random pattern. - - -.. _SPP: - -Parameters for Stochastically Perturbed Parameterizations (SPP) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -SPP perturbs specific tuning parameters within a physics :term:`parameterization ` (unlike :ref:`SPPT `, which multiplies overall physics tendencies by a random perturbation field *after* the call to the physics suite). Patterns evolve and are applied at each time step. Each SPP option is an array, applicable (in order) to the :term:`RAP`/:term:`HRRR`-based parameterization listed in ``SPP_VAR_LIST``. Enter each value of the array in ``config.yaml`` as shown below without commas or single quotes (e.g., ``SPP_VAR_LIST: [ "pbl" "sfc" "mp" "rad" "gwd" ]`` ). Both commas and single quotes will be added by Jinja when creating the namelist. - -.. note:: - SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which :term:`SDF` is chosen when turning this option on. Of the four supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. - -``DO_SPP``: (Default: false) - Flag to turn SPP on or off. SPP perturbs parameters or variables with unknown or uncertain magnitudes within the physics code based on ranges provided by physics experts. Valid values: ``True`` | ``False`` - -``ISEED_SPP``: (Default: [ 4, 5, 6, 7, 8 ] ) - Seed for setting the random number sequence for the perturbation pattern. - -``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"`` | ``"mp"`` - -``SPP_MAG_LIST``: (Default: [ 0.2, 0.2, 0.75, 0.2, 0.2 ] ) - SPP perturbation magnitudes used in each parameterization. Corresponds to the variable ``spp_prt_list`` in ``input.nml`` - -``SPP_LSCALE``: (Default: [ 150000.0, 150000.0, 150000.0, 150000.0, 150000.0 ] ) - Decorrelation spatial scales in meters. - -``SPP_TSCALE``: (Default: [ 21600.0, 21600.0, 21600.0, 21600.0, 21600.0 ] ) - Decorrelation timescales in seconds. Corresponds to the variable ``spp_tau`` in ``input.nml``. - -``SPP_SIGTOP1``: (Default: [ 0.1, 0.1, 0.1, 0.1, 0.1 ] ) - Controls vertical tapering of perturbations at the tropopause and corresponds to the lower sigma level at which to taper perturbations to zero. - -``SPP_SIGTOP2``: (Default: [ 0.025, 0.025, 0.025, 0.025, 0.025 ] ) - Controls vertical tapering of perturbations at the tropopause and corresponds to the upper sigma level at which to taper perturbations to zero. - -``SPP_STDDEV_CUTOFF``: (Default: [ 1.5, 1.5, 2.5, 1.5, 1.5 ] ) - Limit for possible perturbation values in standard deviations from the mean. - - -Land Surface Model (LSM) SPP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Land surface perturbations can be applied to land model parameters and land model prognostic variables. The LSM scheme is intended to address errors in the land model and land-atmosphere interactions. LSM perturbations include soil moisture content (SMC) (volume fraction), vegetation fraction (VGF), albedo (ALB), salinity (SAL), emissivity (EMI), surface roughness (ZOL) (in cm), and soil temperature (STC). Perturbations to soil moisture content (SMC) are only applied at the first time step. Only five perturbations at a time can be applied currently, but all seven are shown below. In addition, only one unique *iseed* value is allowed at the moment, and it is used for each pattern. - -The parameters below turn on SPP in Noah or RUC LSM (support for Noah MP is in progress). Please be aware of the :term:`SDF` that you choose if you wish to turn on Land Surface Model (LSM) SPP. SPP in LSM schemes is handled in the ``&nam_sfcperts`` namelist block instead of in ``&nam_sppperts``, where all other SPP is implemented. - -``DO_LSM_SPP``: (Default: false) - Turns on Land Surface Model (LSM) Stochastic Physics Parameterizations (SPP). When true, sets ``lndp_type=2``, which applies land perturbations to the selected paramaters using a newer scheme designed for data assimilation (DA) ensemble spread. LSM SPP perturbs uncertain land surface fields ("smc" "vgf" "alb" "sal" "emi" "zol" "stc") based on recommendations from physics experts. Valid values: ``True`` | ``False`` - -``LSM_SPP_TSCALE``: (Default: [ 21600, 21600, 21600, 21600, 21600, 21600, 21600 ] ) - Decorrelation timescales in seconds. - -``LSM_SPP_LSCALE``: (Default: [ 150000, 150000, 150000, 150000, 150000, 150000, 150000 ] ) - Decorrelation spatial scales in meters. - -``ISEED_LSM_SPP``: (Default: [ 9 ] ) - Seed to initialize the random perturbation pattern. - -``LSM_SPP_VAR_LIST``: (Default: [ "smc", "vgf", "alb", "sal", "emi", "zol", "stc" ] ) - Indicates which LSM variables to perturb. - -``LSM_SPP_MAG_LIST``: (Default: [ 0.017, 0.001, 0.001, 0.001, 0.001, 0.001, 0.2 ] ) - Sets the maximum random pattern amplitude for each of the LSM perturbations. - -.. _HaloBlend: - -Halo Blend Parameter ------------------------- -``HALO_BLEND``: (Default: 10) - Number of cells to use for "blending" the external solution (obtained from the :term:`LBCs`) with the internal solution from the FV3LAM :term:`dycore`. Specifically, it refers to the number of rows into the computational domain that should be blended with the LBCs. Cells at which blending occurs are all within the boundary of the native grid; they don't involve the 4 cells outside the boundary where the LBCs are specified (which is a different :term:`halo`). Blending is necessary to smooth out waves generated due to mismatch between the external and internal solutions. To shut :term:`halo` blending off, set this to zero. - diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst deleted file mode 100644 index 4ea8f7052d..0000000000 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/DefineWorkflow.rst +++ /dev/null @@ -1,241 +0,0 @@ -.. _DefineWorkflow: - -============================= -Defining an SRW App Workflow -============================= - -Many predefined workflows with optional variants exist within the Short-Range Weather Application, but the Application also includes the ability to define a new workflow from scratch. This functionality allows users to add tasks to the workflow to meet their scientific exploration needs. - -Rocoto is the primary workflow manager software used by the UFS SRW App. Rocoto workflows are defined in an XML file (``FV3LAM_wflow.xml``) based on parameters set during experiment generation. This section explains how the Rocoto XML is built using a Jinja2 template (`Jinja docs here `__) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation `__ with a few exceptions or additions outlined in this documentation. - -The Jinja2 Template -=================== - -In previous versions of the SRW Application, the Jinja2 template to create the Rocoto XML was tightly coupled to specific configuration settings of the SRW App. It was built from a limited, pre-defined set of specific tasks, defining switches for those tasks to be included or not in the rendered XML. - -Now, the Jinja2 template is entirely agnostic to SRW Application decisions and has been developed to wrap the features of Rocoto in an extensible, configurable format. - - -The ``rocoto`` section of ``config.yaml`` -========================================== -The structured YAML file that defines the Rocoto XML is meant to reflect the sections required by any Rocoto XML. That structure looks like this, with some example values filled in: - -.. code-block:: console - - rocoto: - attrs: - realtime: F - scheduler: slurm - cyclethrottle: 5 - corethrottle: - taskthrottle: - cycledefs: - groupname: - - !startstopfreq ['2022102000', ‘2023102018’, ‘06:00:00’] - groupname2: - - !startstopfreq ['2022102000', ‘2023102018’, ‘24:00:00’] - - !startstopfreq ['2022102006', ‘2023102018’, ‘24:00:00’] - entities: - foo: 1 - bar: “/some/path” - log: "" - tasks: - taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml"]|include }}' - task_*: - metatask_*: - -Under the Rocoto section, several subentries are required. They are described here using similar language as in the Rocoto documentation. - -``attrs``: Any of the attributes to the ``workflow`` tag in Rocoto. This is meant to contain a nested dictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. - -``cycledefs``: A dictionary in which each key defines a group name for a ``cycledef`` tag; the key’s value is a list of acceptable ``cycledef`` formatted strings. The PyYAML constructor ``!startstopfreq`` has been included here to help with the automated construction of a tag of that nature. The preferred option for the SRW App is to use the “start, stop, step” method. - -``entities``: A dictionary in which each key defines the name of a Rocoto entity and its value. These variables are referenceable throughout the workflow with the ``&foo;`` notation. - -``log``: The path to the log file. This corresponds to the ```` tag. - -``tasks``: This section is where the defined tasks and metatasks are created. This is the main portion of the workflow that will most commonly differ from experiment to experiment with different configurations. - -In addition to the structured YAML itself, the SRW App enables additional functionality when defining a YAML file. Often, PyYAML features are introduced and documented `here `__. In the above example, the ``!startstopfreq`` is an example of a PyYAML constructor. Supported constructors will be outlined :ref:`below `. There are also examples of using PyYAML anchors and aliases in the definition of groups of tasks in the SRW App. Please see `this documentation `__ for the behavior of PyYAML anchors and aliases. - -The use of Jinja2 templates inside the values of entries allows for the reference to other keys, mathematical operations, Jinja2 control structures, and the use of user-defined filters. Here, the ``include`` filter in the ``taskgroups`` entry is a user-defined filter. The supported filters are described in a section :ref:`below `. - -.. _tasks: - -The ``tasks`` Subsection -======================== - -``taskgroups``: This entry is not a standard Rocoto entry. It defines a set of files that will be included to build a workflow from predefined groups of tasks. The supported groups are included under ``parm/wflow`` for the SRW App, but the paths can point to any location on your local disk. The resulting order of the tasks will be in the same order as defined in this list. The syntax for the “include” is included as a Jinja2 filter. - -``task_*``: This is a section header to add a task. The task name will be whatever the section key has defined after the first underscore. For example, ``task_run_fcst`` will be named ``run_fcst`` in the resulting workflow. More information about defining a task is included :ref:`below `. - -``metatask_*``: This is a section header to add a metatask. The metatask name will be whatever the section key has defined after the first underscore. For example ``metatask_run_ensemble`` will be named ``run_ensemble`` in the resulting workflow. More information about defining a metatask is included :ref:`below `. - -.. _defining_tasks: - -Defining a Task -=============== -Each task supports any of the tags that are defined in the Rocoto documentation. Here’s an example of a task: - -.. code-block:: console - - task_make_grid: - account: '&ACCOUNT;' - command: '&LOAD_MODULES_RUN_TASK_FP; "make_grid" - attrs: - cycledefs: at_start - maxtries: '2' - envars: &default_envars - GLOBAL_VAR_DEFNS_FP: '&GLOBAL_VAR_DEFNS_FP;' - USHdir: '&USHdir;' - PDY: !cycstr "@Y@m@d" - cyc: !cycstr "@H" - subcyc: !cycstr "@M" - LOGDIR: !cycstr "&LOGDIR;" - nprocs: '{{ parent.nnodes * parent.ppn }}' - native: '{{ platform.SCHED_NATIVE_CMD }}' - nodes: '{{ nnodes }}:ppn={{ ppn }}' - nnodes: 1 - nodesize: "&NCORES_PER_NODE;" - ppn: 24 - partition: '{% if platform.get("PARTITION_DEFAULT") %}&PARTITION_DEFAULT;{% else %}None{% endif %}' - queue: '&QUEUE_DEFAULT;' - walltime: 00:20:00 - dependency: - - -The following sections are constructs of the interface, while all others are direct translations to tags available in Rocoto. Any tag that allows for attributes to the XML tag will take an ``attrs`` nested dictionary entry. - -``attrs``: Any of the attributes to the task tag in Rocoto. This is meant to be a subdictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. Attributes might include any combination of the following: cycledefs, maxtries, throttle, or final. - -``envars``: A dictionary of keys that map to variable names that will be exported for the job. These will show up as the set of ```` tags in the XML. The value will be the value of the defined variable when it is exported. - - -If the ``command`` entry is not provided, the task won’t show up in the resulting workflow. - -Defining Dependencies -===================== - -The dependency entry will be an arbitrarily deep nested dictionary of key, value pairs. Each level represents entries that must come below it in priority. This is especially relevant for logic files. If an “and” tag must apply to multiple dependencies, those dependencies are all included as a nested dictionary of dependencies. - -Because we are representing these entries as a dictionary, which requires hashable keys (no repeats at the same level), some tags may need to be differentiated where XML may not differentiate at all. In these instances, it is best practice to name them something descriptive. For example, you might have multiple “or” dependencies at the same level that could be named “or_files_exist” and “or_task_ran”. This style can be adopted whether or not differentiation is needed. - -The ``text`` entry on some dependencies is for those dependency tags that need the information to come between two flags, as in a data dependency. - -Otherwise, all dependencies follow the same naming conventions as defined in Rocoto with ``attrs`` dictionaries included to define any of the tag attributes that may be accepted by Rocoto. - -Here is an example of a complex dependency that relies on logic, task dependencies, and data dependencies: - -.. code-block:: console - - dependency: - and: - or_get_obs: # Ensure get_obs task is complete if it's turned on - not: - taskvalid: - attrs: - task: get_obs_mrms - and: - taskvalid: - attrs: - task: get_obs_mrms - taskdep: - attrs: - task: get_obs_mrms - or_do_post: &post_files_exist - and_run_post: # If post was meant to run, wait on the whole post metatask - taskvalid: - attrs: - task: run_post_mem#mem#_f000 - metataskdep: - attrs: - metatask: run_ens_post - and_inline_post: # If inline post ran, wait on the forecast task to complete - not: - taskvalid: - attrs: - task: run_post_mem#mem#_f000 - taskdep: - attrs: - task: run_fcst_mem#mem# - -Notice the use of a PyYAML anchor under the ``or_do_post`` section. If other tasks need this same section of the dependency, it can be included like this to reduce the extensive replication: - -.. code-block:: console - - dependency: - or_do_post: - <<: *post_files_exist - datadep: - text: "&CCPA_OBS_DIR;" - -The use of ``#mem#`` here is a Rocoto construct that identifies this task as a part of a metatask that is looping over ensemble members (more on metatasks below). - -.. _defining_metatasks: - -Defining a Metatask -=================== - -A metatask groups together similar tasks and allows for the definition over entries defined by ``var`` tags. To define a metatask, the ``var`` entry with a nested dictionary of keys representing the names of the metatask variables and values indicating the list of values for each iteration is required. - -Multiple var entries may be included, but each entry must have the same number of items. - -The metatask section must include at least one entry defining another metatask or a task. - -Here’s an example of a metatask section (without the task definition): - -.. code-block:: console - - metatask_run_ensemble: - var: - mem: '{% if global.DO_ENSEMBLE %}{%- for m in range(1, global.NUM_ENS_MEMBERS+1) -%}{{ "%03d "%m }}{%- endfor -%} {% else %}{{ "000"|string }}{% endif %}' - task_make_ics_mem#mem#: - -This metatask will be named “run_ensemble” and will loop over all ensemble members or just the deterministic member (“000”) if no ensemble of forecasts is meant to run. - -The ``var`` section defines the metatask variables, here only “mem”. The name of the task represents that variable using ``#mem#`` to indicate that the resulting task name might be ``make_ics_mem000`` if only a deterministic forecast is configured to run. - -When the task or the metatask is referenced in a dependency later on, do not include the ``task_`` or ``metatask_`` portions of the name. The reference to ``#mem#`` can be included if the dependency is included in a metatask that defines the variable, e.g., ``make_ics_mem#mem#``. Otherwise, you can reference a task that includes the value of the metatask var, e.g., ``make_ics_mem000``. More on this distinction is included in the Rocoto documentation. - -.. _J2filters: - -SRW-Defined Jinja2 Filters Used by YAML Interface -================================================= - -``include()`` – given a list of files to other YAML files, load their contents as a nested dictionary under the entry. - -.. _YAMLconstructors: - -SRW-Defined PyYAML Constructors Used by YAML Interface -====================================================== - -``!cycstr`` - Returns a ```` element for use in Rocoto. It does not support the “offset” attribute. - -``!startstopfreq`` – Creates a Rocoto XML-formatted string given a start, stop, and freq value in a list. - -Order of Precedence -=================== -There is a specific order of precedence imposed when the SRW App loads configuration files. - -#. Load ``config_defaults.yaml`` file. -#. Load the user’s ``config.yaml`` file. -#. Load the ``default_workflow.yaml`` file. - - * At this point, all anchors and references will be resolved. - * All PyYAML constructors will also be called for the data provided in that entry. -#. Call ``update_dict`` function to remove any null entries from default tasks using the PyYAML anchors. -#. Load all files from the ``taskgroups:`` entry from the user’s config or from the default if not overridden. This is achieved with a call to the ``extend_yaml()`` function. -#. Add the contents of the files to the ``task:`` section. -#. Update the existing workflow configuration with any user-specified entries (removing the ones that are null entries). -#. Add a ``jobname:`` entry to every task in the workflow definition section. -#. Incorporate other default configuration settings from machine files, constants, etc. into the default configuration dictionary in memory. -#. Apply all user settings last to take highest precedence. -#. Call ``extend_yaml()`` to render templates that are available. - NOTE: This is the one that is likely to trip up any settings that ``setup.py`` will make. References to other defaults that get changed during the course of validation may be rendered here earlier than desired. - -At this point, validation and updates for many other configuration settings will be made for a variety of sections. Once complete, ``extend_yaml()`` is called repeatedly, stopping only when all possible Jinja2-templated values have been rendered. - -Just before the ``rocoto:`` section is written to its own file in the experiment directory, ``clean_rocoto_dict()`` is called on that section to remove invalid dictionaries, i.e., metatasks with no tasks, tasks with no associated commands, etc. - -The ``rocoto:`` section is not included in the ``var_defns.sh`` since that file is used primarily to store settings needed at run-time. - diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst deleted file mode 100644 index e179219e7a..0000000000 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/InputOutputFiles.rst +++ /dev/null @@ -1,396 +0,0 @@ -.. _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. 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 required files, see :numref:`Section %s `. - -.. _Input: - -Input Files -=========== -The SRW Application requires numerous input files to run: static datasets (fix files -containing climatological information, terrain, and land use data), initial and boundary -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 from the `SRW App Data Bucket `__, - * Pulled from the NOAA High Performance Storage System (:term:`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 generates the SRW App workflow as described in :numref:`Section %s `, 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 `Technical Documentation `__ and `Scientific Documentation `__. - -UFS Weather Model ------------------ -The input files for the UFS Weather Model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix(ed) 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 their machine. (See :numref:`Section %s ` for instructions on staging the data on a new machine and :numref:`Section %s ` for data locations on Level 1 machines.) The workflow scripts link the static, grid, and date-specific files to 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) ----------------------------- -Documentation for the UPP input files can be found in the `UPP User's Guide -`__. - -.. _WorkflowTemplates: - -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 SRW 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.yaml`` file are assigned. - -List of Template Files -^^^^^^^^^^^^^^^^^^^^^^^^ -The template files for the SRW Application are located in the ``parm`` directory -and are shown in :numref:`Table %s `. - -.. _TemplateFiles: - -.. list-table:: Template Files for the SRW App Workflow - :widths: 20 50 - :header-rows: 1 - - * - 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 :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 :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 ``generate_FV3LAM_wflow.py``. - * - input.nml.FV3 - - Namelist file for the Weather Model. - * - model_configure - - Settings and configurations for the :term:`NUOPC`/:term:`ESMF` main component. - * - nems.configure - - :term:`NEMS` (NOAA Environmental Modeling System) configuration file. No need to change because the usual SRW App configuration is atmosphere-only, and UFS-AQM settings handle any configuration/templating required for that configuration. - * - 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 ``diag_table.[CCPP]``, ``field_table.[CCPP]``, ``input.nml.FV3``, ``model_configure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, while information on ``regional_grid.nml`` options can be found in the `UFS_UTILS Technical Documentation `__. - -Migratory Route of the Input Files in the Workflow -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:numref:`Figure %s ` shows how the input files in the template directory (``ufs-srweather-app/parm``) 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 SRW App 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 ``parm`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. - -.. _MigratoryRoute: - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW_wflow_input_path.png - :alt: Flowchart showing how information from the physics suite travels from the configuration file to the setup file to the workflow generation script to the run forecast ex-script. As this information is fed from one file to the next, file paths and variables required for workflow execution are set. - - *Migratory Route of Input Files* - -.. _OutputFiles: - -Output Files -============== - -Output files from each workflow task are written to a subdirectory within the experiment directory (``$EXPTDIR/YYYYMMDDHH``), named based on the settings in ``config.yaml``. These files may then be used as input to future tasks. - -Initial and boundary condition files ------------------------------------- -The external model data used by ``chgres_cube`` (as part of the pre-processing utilities) are located -in the experiment directory under ``$EXPTDIR/YYYYMMDDHH/EXTRN_MDL_NAME/{for_ICS/for_LBCS}``. - -.. COMMENT: This is confusing bc it sounds like these are input files, not output files. Does chgres_cube output these? In which tasks? - -Pre-processing (UFS_UTILS) --------------------------- -The files output by the other pre-processing utilities reside in the ``INPUT`` directory under the -experiment directory (``$EXPTDIR/YYYYMMDDHH/INPUT``) and consist of the following: - -* ``C403_grid.tile7.halo3.nc`` -* ``gfs_bndy.tile7.HHH.nc`` -* ``gfs_ctrl.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 User's Guide -`__. ``gfs_bndy.tile7.HHH.nc`` refers to a series of IC/LBC files where ``HHH`` is the 3-digit hour of the forecast. - -UFS Weather Model ------------------- -As stated in :numref:`Section %s `, the workflow can be run in "community" mode or "nco" mode, which determines the location and names of the output files. Weather Model output files can be in :term:`netCDF` or :term:`NEMSIO` format. The output file format is set in the ``model_configure`` file using the ``output_file`` variable (see :ref:`UFS WM Documentation `). At this time, due to limitations in the post-processing component, only netCDF output is recommended as output for the SRW Application. - -.. note:: - 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`` - -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 -`__. - -Unified Post Processor (UPP) ----------------------------- -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 ``$EXPTDIR/YYYYMMDDHH/postprd`` and have the naming convention (file->linked to): - -* ``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.yaml`` settings. - -.. _ModifyUPPOutput: - -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/sorc/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 instructions in the `UPP User's Guide `__ to make modifications to the ``fv3lam.xml`` file and to remake the flat text file, called ``postxconfig-NT-fv3lam.txt`` (default), that the UPP reads. - -After creating the new flat text file to reflect the changes, users will need to modify their ``config.yaml`` to point the workflow to the new text file. In ``config.yaml``, set the following: - -.. code-block:: console - - USE_CUSTOM_POST_CONFIG_FILE: true - CUSTOM_POST_CONFIG_FP: /path/to/custom/postxconfig-NT-fv3lam.txt - -which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If ``USE_CUSTOM_POST_CONFIG_FILE`` is set to true, but the file path is not found, then an error will occur when trying to generate the SRW Application workflow. - -After successfully generating the workflow, users may run/monitor their experiment 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 (``postxconfig-NT-fv3lam.txt``) has already been set up to output satellite products using the process described above in :numref:`Section %s`. - -Download and unpack the external files: - -.. code-block:: console - - mkdir crtm && cd crtm - wget https://github.com/NOAA-EMC/UPP/releases/download/upp_v11.0.0/fix.tar.gz - tar -xzf fix.tar.gz - -Modify the ``config.yaml`` 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 -================================== -A set of input files, including static (fix) data and raw initial and lateral boundary conditions (:term:`IC/LBCs`), 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. Therefore, users on these systems do not need to stage the fixed files manually because they have been prestaged, and the paths are set in ``ush/setup.sh``. Users on Level 3 & 4 systems can find the most recent SRW App release data in the `UFS SRW Application Data Bucket `__ by clicking on `Browse Bucket `__. - -.. _StaticFixFiles: - -Static Files --------------- - -Static files are available in the `"fix" directory `__ of the SRW App Data Bucket. Users can download the full set of fix files as a tar file: - -.. code-block:: console - - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/fix_data.tgz - tar -xzf fix_data.tgz - -Alternatively, users can download the static files individually from the `"fix" directory `__ of the SRW Data Bucket using the ``wget`` command for each required file. A list of ``wget`` commands with links is provided :ref:`here ` for the release v2.1.0 fix file data. Users will need to create an appropriate directory structure for the files when downloading them individually. The best solution is to download the files into directories that mirror the structure of the `Data Bucket `__. - -.. COMMENT: Update release file list above for next SRW release. - -The environment variables ``FIXgsm``, ``FIXorg``, and ``FIXsfc`` 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.yaml``. Add the following code to the ``task_run_fcst:`` section of the ``config.yaml`` file, and alter the variable paths accordingly: - -.. code-block:: console - - FIXgsm: /path/to/fix/fix_am - FIXorg: /path/to/fix/fix_orog - FIXsfc: /path/to/fix/sfc_climo/ - -.. _InitialConditions: - -Initial 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, GEFS, GDAS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. - -To download the model input data for the 12-hour "out-of-the-box" experiment configuration in ``config.community.yaml`` file, run: - -.. code-block:: console - - wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/gst_data.tgz - tar -xzf gst_data.tgz - -To download data for different dates, model types, and formats, users can explore the ``input_model_data`` section of the data bucket and replace the links above with ones that fetch their desired data. - -.. _ICS-LBCS: - -Initial and Lateral Boundary Condition Organization ----------------------------------------------------- - -The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` must be set in the appropriate sections of the ``config.yaml`` file: - -.. code-block:: console - - task_get_extrn_ics: - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH - task_get_extrn_lbcs: - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH - -The two ``EXTRN_MDL_SOURCE_BASEDIR_*CS`` variables describe where the :term:`IC ` and :term:`LBC ` file directories are located, respectively. For ease of reusing ``config.yaml`` across experiments, it is recommended that users set up the raw :term:`IC/LBC ` file paths to include the model name (e.g., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path/to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. - -When files are pulled from NOAA :term:`HPSS` (rather than downloaded from the data bucket), the naming convention looks something like: - -* 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`` - -* GDAS (NETCDF): - - * ICs: ``gdas.t{cycle}z.atmf{fhr}.nc`` and ``gdas.t{cycle}z.sfcf{fhr}.nc``; - * LBCs: ``gdas.t{cycle}z.atmf{fhr}.nc`` - -* 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 2- or 3-digit nth hour of the forecast (3-digits for FV3GFS/GDAS data and 2 digits for RAP/HRRR data). - -For example, a forecast using FV3GFS GRIB2 data that starts at 18h00 UTC would have a {cycle} value of 18, which is the 000th forecast hour. The LBCS file for 21h00 UTC would be named ``gfs.t18z.pgrb2.0p25.f003``. - -In some cases, it may be necessary to specify values for ``EXTRN_MDL_FILES_*CS`` variables. This is often the case with HRRR and RAP data. An example ``config.yaml`` excerpt using HRRR and RAP data appears below: - -.. code-block:: console - - task_get_extrn_ics: - EXTRN_MDL_NAME_ICS: HRRR - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_FILES_ICS: - - '{yy}{jjj}{hh}00{fcst_hr:02d}00' - task_get_extrn_lbcs: - EXTRN_MDL_NAME_LBCS: RAP - LBC_SPEC_INTVL_HRS: 3 - USE_USER_STAGED_EXTRN_FILES: true - EXTRN_MDL_FILES_LBCS: - - '{yy}{jjj}{hh}00{fcst_hr:02d}00' - -Default Initial and Lateral Boundary Conditions ------------------------------------------------ - -The default initial and lateral boundary condition files are set to be a severe weather case from June 15, 2019 (20190615) at 18 UTC. FV3GFS GRIB2 files are the default model and file format. A tar file -(``gst_data.tgz``) containing the model data for this case is available in the `UFS SRW App Data Bucket `__. - -Running the App for Different Dates ------------------------------------ -If users want to run the SRW Application for dates other than June 15-16, 2019, they will need to modify the ``config.yaml`` settings, including the ``DATE_FIRST_CYCL`` and ``DATE_LAST_CYCL`` 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. - -Staging Initial Conditions Manually ------------------------------------ -If users want to run the SRW Application with raw model files for dates other than those that -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`` (which may be the same directory). The path to these variables can be set in the ``config.yaml`` file as shown :ref:`above `. 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: - -* GFS (GRIB2 or NEMSIO) - available for the last 10 days - https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod/ -* GDAS (NETCDF) sfc files - available for the last 2 days - https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod -* NAM - available for the last 8 days - https://nomads.ncep.noaa.gov/pub/data/nccf/com/nam/prod/ -* RAP - available for the last 2 days - https://nomads.ncep.noaa.gov/pub/data/nccf/com/rap/prod/ -* HRRR - available for the last 2 days - https://nomads.ncep.noaa.gov/pub/data/nccf/com/hrrr/prod/ - -AWS S3 Data Buckets: - -* GFS: https://registry.opendata.aws/noaa-gfs-bdp-pds/ -* GEFS: https://registry.opendata.aws/noaa-gefs/ -* GDAS: https://registry.opendata.aws/noaa-gfs-bdp-pds/ -* HRRR: https://registry.opendata.aws/noaa-hrrr-pds/ (necessary fields for initializing available for dates 2015 and newer) - -Google Cloud: - -* HRRR: https://console.cloud.google.com/marketplace/product/noaa-public/hrrr - -FTP Data Repository (data for SRW Release v1.0.0 & v1.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: - -* University of Utah HRRR archive: http://home.chpc.utah.edu/~u0553130/Brian_Blaylock/cgi-bin/hrrr_download.cgi -* NAM nest archive: https://www.ready.noaa.gov/archives.php -* NAM data older than 6 months can be requested through the Archive Information Request System: https://www.ncei.noaa.gov/has/HAS.FileAppRouter?datasetname=NAM218&subqueryby=STATION&applname=&outdest=FILE -* RAP isobaric data older than 6 months can be requested through the Archive Information Request System: https://www.ncei.noaa.gov/has/HAS.FileAppRouter?datasetname=RAP130&subqueryby=STATION&applname=&outdest=FILE - -Coexistence of Multiple Files for the Same Date -------------------------------------------------- -It is recommended that users have a separate directory for each file format if they choose to store files in multiple formats (e.g., GRIB2, NEMSIO, netCDF) for the same date. For example, the directory structure for a user storing GFS GRIB2 and NEMSIO files might resemble the following: - -.. code-block:: console - - /path/to/input_model_data/FV3GFS/grib2/YYYYMMDDHH - /path/to/input_model_data/FV3GFS/nemsio/YYYYMMDDHH - -Additionally, users must set the following environment variables if they plan to use GRIB2-formatted files for FV3GFS: - -.. code-block:: console - - FV3GFS_FILE_FMT_ICS: grib2 - FV3GFS_FILE_FMT_LBCS: grib2 - -This is ONLY necessary when using FV3GFS GRIB2 files. These settings may be removed when initializing from the default NEMSIO format for 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 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. - -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/TinkeringWWflowDetails/LAMGrids.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/LAMGrids.rst deleted file mode 100644 index e4ddaa29b1..0000000000 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/LAMGrids.rst +++ /dev/null @@ -1,204 +0,0 @@ -.. _LAMGrids: - -================================================================================= -Limited Area Model (:term:`LAM`) Grids: Predefined and User-Generated Options -================================================================================= -In order to set up the workflow and generate an experiment with the SRW Application, the user -must choose between various predefined :term:`FV3`-:term:`LAM` grids or generate a user-defined grid. -At this time, full support is only provided to those using one of the four predefined -grids supported in the v2.1.0 release, but other predefined grids are available (see :numref:`Section %s ` for more detail). Preliminary information is also provided at the end of this chapter describing 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 SRW App v2.1.0 release includes four predefined limited area model (:term:`LAM`) grids. To select a supported predefined grid, the ``PREDEF_GRID_NAME`` variable within the ``task_run_fcst:`` section of the ``config.yaml`` script must be set to one of the following four options: - -* ``RRFS_CONUS_3km`` -* ``RRFS_CONUS_13km`` -* ``RRFS_CONUS_25km`` -* ``SUBCONUS_Ind_3km`` - -These four options are provided for flexibility related to compute resources and supported physics options. Other predefined grids are listed :ref:`here `. The high-resolution 3-km :term:`CONUS` grid generally requires more compute power and works well with three of the five 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 other supported physics suites: ``FV3_GFS_v16`` and ``FV3_RAP``. - -.. _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 | - | | | - | | FV3_RAP | - +-------------------+------------------+ - | RRFS_CONUS_25km | FV3_GFS_v16 | - | | | - | | FV3_RAP | - +-------------------+------------------+ - -In theory, it is possible to run any of the supported physics suites 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 (:term:`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 3-km 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 parameterizations. 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`` and ``FV3_RAP`` suites generally should *not* be used with the 3-km domain because the cumulus physics used in those physics suites is not configured to run at the 3-km resolution. - -.. _RRFS_CONUS_3km: - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_3km.sphr.native_wrtcmp.png - :alt: Map of the continental United States 3 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. - - *The boundary of the RRFS_CONUS_3km computational grid (red) and corresponding write-component grid (blue).* - -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 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 the 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 (such as HRRR or RAP data) that has a resolution similar to that of the native FV3-LAM (predefined) grid. - - -Predefined SUBCONUS Grid Over Indianapolis --------------------------------------------- - -.. _SUBCONUS_Ind_3km: - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/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 the computational grid boundaries in blue. - - *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 :term:`CONUS` centered 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: - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_13km.sphr.native_wrtcmp.png - :alt: Map of the continental United States 13 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. - - *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`` or ``FV3_RAP`` physics suites. These suites use 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 25-km and 13-km. - -Predefined 25-km Grid ------------------------- - -.. _RRFS_CONUS_25km: - -.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_25km.sphr.native_wrtcmp.png - :alt: Map of the continental United States 25 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. - - *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 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, 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 -out with the SRW App, more advanced users may wish to create their own predefined 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 (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 predefined 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. More information on the ESG grid is available `here `__. 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: - -#. 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/ush/valid_param_vals.yaml`` file. - -#. In ``ufs-srweather-app/ush/predef_grid_params.yaml``, add a stanza describing the parameters for NEW_GRID. An example of such a stanza is given :ref:`below `. For descriptions of the variables that need to be set, see Sections :numref:`%s ` and :numref:`%s `. - -To run a forecast experiment on NEW_GRID, start with a workflow configuration file for a successful experiment (e.g., ``config.community.yaml``, located in the ``ufs-srweather-app/ush`` subdirectory), and change the line for ``PREDEF_GRID_NAME`` in the ``task_run_fcst:`` section to ``NEW_GRID``: - -.. code-block:: console - - PREDEF_GRID_NAME: "NEW_GRID" - -Then, load the regional workflow python environment, specify the other experiment parameters in ``config.community.yaml``, and generate a new experiment/workflow using the ``generate_FV3LAM_wflow.py`` script (see :numref:`Chapter %s ` for details). - -Code Example ---------------- - -The following is an example of a code stanza for "NEW_GRID" to be added to ``predef_grid_params.yaml``: - -.. _NewGridExample: - -.. code-block:: console - - # - #--------------------------------------------------------------------- - # - # Stanza for NEW_GRID. This grid covers [description of the - # domain] with ~[size]-km cells. - # - #--------------------------------------------------------------------- - - "NEW_GRID": - - # The method used to generate the grid. This example is specifically for the "ESGgrid" method. - - GRID_GEN_METHOD: "ESGgrid" - - # ESGgrid parameters: - - ESGgrid_LON_CTR: -97.5 - ESGgrid_LAT_CTR: 38.5 - ESGgrid_DELX: 25000.0 - ESGgrid_DELY: 25000.0 - ESGgrid_NX: 200 - ESGgrid_NY: 112 - ESGgrid_PAZI: 0.0 - ESGgrid_WIDE_HALO_WIDTH: 6 - - # Forecast configuration parameters: - - DT_ATMOS: 40 - LAYOUT_X: 5 - LAYOUT_Y: 2 - BLOCKSIZE: 40 - - # Parameters for the write-component (aka "quilting") grid. - - QUILTING: - WRTCMP_write_groups: 1 - WRTCMP_write_tasks_per_group: 2 - WRTCMP_output_grid: "lambert_conformal" - WRTCMP_cen_lon: -97.5 - WRTCMP_cen_lat: 38.5 - WRTCMP_lon_lwr_left: -121.12455072 - WRTCMP_lat_lwr_left: 23.89394570 - - # Parameters required for the Lambert conformal grid mapping. - - WRTCMP_stdlat1: 38.5 - WRTCMP_stdlat2: 38.5 - WRTCMP_nx: 197 - WRTCMP_ny: 107 - WRTCMP_dx: 25000.0 - WRTCMP_dy: 25000.0 - -.. note:: - The process above explains how to create a new *predefined* grid, which can be used more than once. If a user prefers to create a custom grid for one-time use, the variables above can instead be specified in ``config.yaml``, and ``PREDEF_GRID_NAME`` can be set to a null string. In this case, it is not necessary to modify ``valid_param_vals.yaml`` or ``predef_grid_params.yaml``. Users can view an example configuration file for a custom grid `here `__. diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst deleted file mode 100644 index f22d915a62..0000000000 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/TemplateVars.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. _TemplateVars: - -====================== -Template Variables -====================== - -The SRW App's experiment configuration system supports the use of template variables -in ``config_defaults.yaml`` and ``config.yaml``. A template variable is an experiment configuration variable that contains references to values of other variables. -These references are **not** set to the values of the referenced variables (or "expanded") when the experiment's variable definitions file (``var_defns.sh``) is generated or sourced. -Instead, they are expanded and evaluated **at run time** when bash's -``eval`` command is used on the template. - -Generic Example -================== - -As an example, consider a hypothetical template variable named ``MY_CMD`` that is defined in ``config_defaults.yaml`` -(or redefined by the user in ``config.yaml``) as follows: - - .. code-block:: console - - MY_CMD: 'cd ${some_dir}' - -Here, ``some_dir`` may be another experiment variable defined in ``var_defns.sh`` or a -local variable defined in a script or function that will evaluate the template. -It is important to use single quotes on the right-hand side of the definition above; -otherwise, bash will try to evaluate ``${some_dir}`` when constructing ``var_defns.sh``, -which may result in an error and/or unexpected behavior (e.g., if ``${some_dir}`` -is not yet defined). The experiment generation system will define ``MY_CMD`` in -``var_defns.sh`` in exactly the same way as in ``config_defaults.yaml`` and/or -``config.yaml``, e.g., ``MY_CMD: 'cd ${some_dir}'``. Then the following code snippet -in a script or function will evaluate the contents of ``MY_CMD`` using a locally-set -value of ``some_dir``: - - .. code-block:: none - - ... - . var_defns.sh # Source the experiment's variable definition file (assuming - # it is in the current directory). This defines the MY_CMD - # template variable (in addition to other variables). - ... - some_dir="20200715" # Set the local variable some_dir. - ... - eval ${MY_CMD} # Use eval to evaluate the contents of MY_CMD. The value of - # some_dir specified in this file a few lines above is substituted - # for ${some_dir} in MY_CMD before MY_CMD is evaluated. - -Graphics Plotting Example -============================ - -When attempting to generate graphics plots from a forecast, users have the option to -produce difference plots from two experiments that are on the same domain and -available for the same cycle starting date/time and forecast hours. -To generate difference plots, users must use the template variable ``COMOUT_REF`` -to indicate where the :term:`GRIB2` files from post-processing are located. - -In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will -take the form ``/path/to/expt_dirs/expt_name/$PDY$cyc/postprd``, where ``$PDY`` refers -to the cycle date in YYYYMMDD format, and ``$cyc`` refers to the starting hour of the cycle. -(These variables are set in previous tasks based on the value of ``DATE_FIRST_CYCL``.) -Given two experiments, ``expt1`` and ``expt2``, users can generate difference plots by -setting ``COMOUT_REF`` in the ``expt2`` configuration file (``config.yaml``) as follows: - -.. code-block:: console - - COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd' - -The ``expt2`` workflow already knows where to find its own post-processed output, so -``COMOUT_REF`` should point to post-processed output for the other experiment (``expt1``). - -In *nco* mode, this directory should be set to the location of the first experiment's -``COMOUT`` directory (``${COMOUT}`` in the example below) and end with ``${PDY}/${cyc}``. -For example: - -.. code-block:: console - - COMOUT_REF: '${COMOUT}/${PDY}/${cyc}/' - diff --git a/docs/UsersGuide/source/TinkeringWWflowDetails/index.rst b/docs/UsersGuide/source/TinkeringWWflowDetails/index.rst deleted file mode 100644 index f272c6e220..0000000000 --- a/docs/UsersGuide/source/TinkeringWWflowDetails/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Tinkering With Workflow Details -================================== - -.. toctree:: - :maxdepth: 3 - - ConfigWorkflow - InputOutputFiles - LAMGrids - DefineWorkflow - TemplateVars - diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst index 8aa16e2969..52937c81ae 100644 --- a/docs/UsersGuide/source/index.rst +++ b/docs/UsersGuide/source/index.rst @@ -13,5 +13,5 @@ UFS Short-Range Weather App Users Guide BackgroundInfo/index BuildingRunningTesting/index - TinkeringWWflowDetails/index + CustomizingTheWorkflow/index Reference/index From 5b045a0fffb3d42818130eb289045a6c1d9ba588 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 30 Aug 2023 09:42:32 -0400 Subject: [PATCH 114/116] Update CQS ch w/Gaea c5 info --- .../source/BuildingRunningTesting/ContainerQuickstart.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst index d783da9528..d2ccb82a8c 100644 --- a/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst +++ b/docs/UsersGuide/source/BuildingRunningTesting/ContainerQuickstart.rst @@ -83,6 +83,8 @@ On most Level 1 systems, a container named ``ubuntu20.04-intel-srwapp-develop.im +==============+========================================================+ | Cheyenne | /glade/scratch/epicufsrt/containers | +--------------+--------------------------------------------------------+ + | Gaea | /lustre/f2/dev/role.epic/containers | + +--------------+--------------------------------------------------------+ | Hera | /scratch1/NCEPDEV/nems/role.epic/containers | +--------------+--------------------------------------------------------+ | Jet | /mnt/lfs4/HFIP/hfv3gfs/role.epic/containers | @@ -93,7 +95,7 @@ On most Level 1 systems, a container named ``ubuntu20.04-intel-srwapp-develop.im +--------------+--------------------------------------------------------+ .. note:: - * Singularity is not available on Gaea, and therefore container use is not supported on Gaea. + * Singularity is only available on the Gaea C5 partition, and therefore container use is only supported on Gaea C5. * The NOAA Cloud containers are accessible only to those with EPIC resources. Users can simply set an environment variable to point to the container: From 653fe019be5203b89712c6e12ab74c9ef32982f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 30 Aug 2023 09:52:29 -0400 Subject: [PATCH 115/116] rename to Customizing the Workflow --- .../CustomizingTheWorkflow/ConfigWorkflow.rst | 1238 +++++++++++++++++ .../CustomizingTheWorkflow/DefineWorkflow.rst | 241 ++++ .../InputOutputFiles.rst | 396 ++++++ .../CustomizingTheWorkflow/LAMGrids.rst | 204 +++ .../CustomizingTheWorkflow/TemplateVars.rst | 77 + .../source/CustomizingTheWorkflow/index.rst | 12 + 6 files changed, 2168 insertions(+) create mode 100644 docs/UsersGuide/source/CustomizingTheWorkflow/ConfigWorkflow.rst create mode 100644 docs/UsersGuide/source/CustomizingTheWorkflow/DefineWorkflow.rst create mode 100644 docs/UsersGuide/source/CustomizingTheWorkflow/InputOutputFiles.rst create mode 100644 docs/UsersGuide/source/CustomizingTheWorkflow/LAMGrids.rst create mode 100644 docs/UsersGuide/source/CustomizingTheWorkflow/TemplateVars.rst create mode 100644 docs/UsersGuide/source/CustomizingTheWorkflow/index.rst diff --git a/docs/UsersGuide/source/CustomizingTheWorkflow/ConfigWorkflow.rst b/docs/UsersGuide/source/CustomizingTheWorkflow/ConfigWorkflow.rst new file mode 100644 index 0000000000..4fa1fea891 --- /dev/null +++ b/docs/UsersGuide/source/CustomizingTheWorkflow/ConfigWorkflow.rst @@ -0,0 +1,1238 @@ +.. _ConfigWorkflow: + +================================================================================================ +Workflow Parameters: Configuring the Workflow in ``config.yaml`` and ``config_defaults.yaml`` +================================================================================================ +To create the experiment directory and workflow when running the SRW Application, the user must create an experiment configuration file (usually named ``config.yaml``). This file contains experiment-specific information, such as forecast dates, grid and physics suite choices, data directories, and other relevant settings. To help the user, two sample configuration files have been included in the ``ush`` directory: ``config.community.yaml`` and ``config.nco.yaml``. The first is for running experiments in *community* mode (``RUN_ENVIR`` set to "community"), and the second is for running experiments in *nco* mode (``RUN_ENVIR`` set to "nco"). The content of these files can be copied into ``config.yaml`` and used as the starting point from which to generate a variety of experiment configurations for the SRW App. Note that for this release, only *community* mode is supported. + +There is an extensive list of experiment parameters that a user can set when configuring the experiment. Not all of these parameters need to be set explicitly by the user in ``config.yaml``. If a user does not define a variable in the ``config.yaml`` script, its value in ``config_defaults.yaml`` will be used, or the value will be reset depending on other parameters, such as the platform (``MACHINE``) selected for the experiment. + +.. note:: + The ``config_defaults.yaml`` file contains the full list of experiment parameters that a user may set in ``config.yaml``. The user cannot set parameters in ``config.yaml`` that are not initialized in ``config_defaults.yaml``, with the notable exception in the ``rocoto`` section, described in :numref:`Chapter %s `. + +The following is a list of the parameters in the ``config_defaults.yaml`` file. For each parameter, the default value and a brief description is provided. + +.. _user: + +USER Configuration Parameters +================================= + +If non-default parameters are selected for the variables in this section, they should be added to the ``user:`` section of the ``config.yaml`` file. + +``RUN_ENVIR``: (Default: "nco") + This variable determines the workflow mode. The user can choose between two options: "nco" and "community". The "nco" mode uses a directory structure that mimics what is used in operations at NOAA/NCEP Central Operations (NCO) and at the NOAA/NCEP/Environmental Modeling Center (EMC), which works with NCO on pre-implementation testing. Specifics of the conventions used in "nco" mode can be found in the following `WCOSS Implementation Standards `__ document: + + | NCEP Central Operations + | WCOSS Implementation Standards + | January 19, 2022 + | Version 11.0.0 + + Setting ``RUN_ENVIR`` to "community" is recommended in most cases for users who are not planning to implement their code into operations at NCO. Valid values: ``"nco"`` | ``"community"`` + +``MACHINE``: (Default: "BIG_COMPUTER") + The machine (a.k.a. platform or system) on which the workflow will run. Currently supported platforms are listed on the `SRW App Wiki page `__. When running the SRW App on any ParellelWorks/NOAA Cloud system, use "NOAACLOUD" regardless of the underlying system (AWS, GCP, or Azure). Valid values: ``"HERA"`` | ``"ORION"`` | ``"JET"`` | ``"CHEYENNE"`` | ``"GAEA"`` | ``"NOAACLOUD"`` | ``"STAMPEDE"`` | ``"ODIN"`` | ``"MACOS"`` | ``"LINUX"`` | ``"SINGULARITY"`` | ``"WCOSS2"`` + + .. hint:: + Users who are NOT on a named, supported Level 1 or 2 platform will need to set the ``MACHINE`` variable to ``LINUX`` or ``MACOS``; to combine use of a Linux or MacOS platform with the Rocoto workflow manager, users will also need to set ``WORKFLOW_MANAGER: "rocoto"`` in the ``platform:`` section of ``config.yaml``. This combination will assume a Slurm batch manager when generating the XML. + +``MACHINE_FILE``: (Default: "") + Path to a configuration file with machine-specific settings. If none is provided, ``setup.py`` will attempt to set the path to a configuration file for a supported platform. + +``ACCOUNT``: (Default: "project_name") + The account under which users submit jobs to the queue on the specified ``MACHINE``. To determine an appropriate ``ACCOUNT`` field for `Level 1 `__ systems, users may run the ``groups`` command, which will return a list of projects that the user has permissions for. Not all of the listed projects/groups have an HPC allocation, but those that do are potentially valid account names. On some systems, the ``saccount_params`` command will display additional account details. + +.. _PlatformConfig: + +PLATFORM Configuration Parameters +===================================== + +If non-default parameters are selected for the variables in this section, they should be added to the ``platform:`` section of the ``config.yaml`` file. + +``WORKFLOW_MANAGER``: (Default: "none") + The workflow manager to use (e.g., "rocoto"). This is set to "none" by default, but if the machine name is set to a platform that supports Rocoto, this will be overwritten and set to "rocoto." If set explicitly to "rocoto" along with the use of the ``MACHINE: "LINUX"`` target, the configuration layer assumes a Slurm batch manager when generating the XML. Valid values: ``"rocoto"`` | ``"none"`` + +``NCORES_PER_NODE``: (Default: "") + The number of cores available per node on the compute platform. Set for supported platforms in ``setup.py``, but it is now also configurable for all platforms. + +``BUILD_MOD_FN``: (Default: "") + Name of an alternative build module file to use if running on an unsupported platform. It is set automatically for supported machines. + +``WFLOW_MOD_FN``: (Default: "") + Name of an alternative workflow module file to use if running on an unsupported platform. It is set automatically for supported machines. + +``BUILD_VER_FN``: (Default: "") + File name containing the version of the modules used for building the app. Currently, WCOSS2 only uses this file. + +``RUN_VER_FN``: (Default: "") + File name containing the version of the modules used for running the app. Currently, WCOSS2 only uses this file. + +.. _sched: + +``SCHED``: (Default: "") + The job scheduler to use (e.g., Slurm) on the specified ``MACHINE``. Leaving this an empty string allows the experiment generation script to set it automatically depending on the machine the workflow is running on. Valid values: ``"slurm"`` | ``"pbspro"`` | ``"lsf"`` | ``"lsfcray"`` | ``"none"`` + +``SCHED_NATIVE_CMD``: (Default: "") + Allows an extra parameter to be passed to the job scheduler (Slurm or PBSPRO) via XML Native command. + +``DOMAIN_PREGEN_BASEDIR``: (Default: "") + For use in NCO mode only (``RUN_ENVIR: "nco"``). The base directory containing pregenerated grid, orography, and surface climatology files. This is an alternative for setting ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` individually. For the pregenerated grid specified by ``PREDEF_GRID_NAME``, these "fixed" files are located in: + + .. code-block:: console + + ${DOMAIN_PREGEN_BASEDIR}/${PREDEF_GRID_NAME} + + The workflow scripts will create a symlink in the experiment directory that will point to a subdirectory (having the same name as the experiment grid) under this directory. This variable should be set to a null string in ``config_defaults.yaml``, but it can be changed in the user-specified workflow configuration file set by ``EXPT_CONFIG_FN`` (usually ``config.yaml``). + +``PRE_TASK_CMDS``: (Default: "") + Pre-task commands such as ``ulimit`` needed by tasks. For example: ``'{ ulimit -s unlimited; ulimit -a; }'`` + +Machine-Dependent Parameters +------------------------------- +These parameters vary depending on machine. On `Level 1 and 2 `__ systems, the appropriate values for each machine can be viewed in the ``ush/machine/.sh`` scripts. To specify a value other than the default, add these variables and the desired value in the ``config.yaml`` file so that they override the ``config_defaults.yaml`` and machine default values. + +``PARTITION_DEFAULT``: (Default: "") + This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). This is the default partition to which Slurm submits workflow tasks. When a variable that designates the partition (e.g., ``PARTITION_HPSS``, ``PARTITION_FCST``; see below) is **not** specified, the task will be submitted to the default partition indicated in the ``PARTITION_DEFAULT`` variable. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"hera"`` | ``"normal"`` | ``"orion"`` | ``"sjet"`` | ``"vjet"`` | ``"kjet"`` | ``"xjet"`` | ``"workq"`` + +``QUEUE_DEFAULT``: (Default: "") + The default queue or QOS to which workflow tasks are submitted (QOS is Slurm's term for queue; it stands for "Quality of Service"). If the task's ``QUEUE_HPSS`` or ``QUEUE_FCST`` parameters (see below) are not specified, the task will be submitted to the queue indicated by this variable. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` + +``PARTITION_HPSS``: (Default: "") + This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). Tasks that get or create links to external model files are submitted to the partition specified in this variable. These links are needed to generate initial conditions (:term:`ICs`) and lateral boundary conditions (:term:`LBCs`) for the experiment. If this variable is not set or is set to an empty string, it will be (re)set to the ``PARTITION_DEFAULT`` value (if set) or to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"normal"`` | ``"service"`` | ``"workq"`` + +``QUEUE_HPSS``: (Default: "") + Tasks that get or create links to external model files are submitted to this queue, or QOS (QOS is Slurm's term for queue; it stands for "Quality of Service"). These links are needed to generate initial conditions (:term:`ICs`) and lateral boundary conditions (:term:`LBCs`) for the experiment. If this value is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev_transfer"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` + +``PARTITION_FCST``: (Default: "") + This variable is only used with the Slurm job scheduler (i.e., when ``SCHED: "slurm"``). The task that runs forecasts is submitted to this partition. If this variable is not set or is set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"hera"`` | ``"normal"`` | ``"orion"`` | ``"sjet"`` | ``"vjet"`` | ``"kjet"`` | ``"xjet"`` | ``"workq"`` + +``QUEUE_FCST``: (Default: "") + The task that runs a forecast is submitted to this queue, or QOS (QOS is Slurm's term for queue; it stands for "Quality of Service"). If this variable is not set or set to an empty string, it will be (re)set to a machine-dependent value. Options are machine-dependent and include: ``""`` | ``"batch"`` | ``"dev"`` | ``"normal"`` | ``"regular"`` | ``"workq"`` + +Parameters for Running Without a Workflow Manager +----------------------------------------------------- +These settings define the run commands for the platform. + +``RUN_CMD_UTILS``: (Default: "mpirun -np 1") + 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``). 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. + +``RUN_CMD_POST``: (Default: "mpirun -np 1") + The run command for post-processing (via the :term:`UPP`). Can be left blank for smaller domains, in which case UPP will run without :term:`MPI`. + + +METplus Parameters +---------------------- + +:ref:`METplus ` is a scientific verification framework that spans a wide range of temporal and spatial scales. Many of the METplus parameters are described below, but additional documentation for the METplus components is available on the `METplus website `__. + +.. _METParamNote: + +.. note:: + Where a date field is required: + * ``YYYY`` refers to the 4-digit valid year + * ``MM`` refers to the 2-digit valid month + * ``DD`` refers to the 2-digit valid day of the month + * ``HH`` refers to the 2-digit valid hour of the day + * ``mm`` refers to the 2-digit valid minutes of the hour + * ``SS`` refers to the two-digit valid seconds of the hour + +``CCPA_OBS_DIR``: (Default: "") + 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 :term:`HPSS` (if the user has access) via the ``get_obs_ccpa`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). + + METplus configuration files require the use of a 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. 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) for dates up until 2021-05-04. The script to pull the CCPA data from the NOAA HPSS (``scripts/exregional_get_verif_obs.sh``) has an example of how to account for this and organize the data into a more intuitive format. + +``NOHRSC_OBS_DIR``: (Default: "") + User-specified location of top-level directory where NOHRSC 06- and 24-hour snowfall accumulation files (available every 6 and 12 hours respectively) 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 :term:`HPSS` (if the user has access) via the ``get_obs_nohrsc`` task. (This task is activated in the workflow by using the taskgroup file ``parm/wflow/verify_pre.yaml``). + + METplus configuration files require the use of a predetermined directory structure and file names. If the NOHRSC files are user-provided, they need to follow the anticipated naming structure: ``{YYYYMMDD}/sfav2_CONUS_{AA}h_{YYYYMMDD}{HH}_grid184.grb2``, where AA is the 2-digit accumulation duration, and 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 ``NOHRSC_OBS_DIR`` directory. METplus is configured to verify 06-, and 24-h accumulated precipitation using NOHRSC files. + + .. note:: + Due to limited availability of NOHRSC observation data on NOAA HPSS, and the likelihood that snowfall acumulation verification will not be desired outside of winter cases, this verification option is currently not present in the workflow by default. In order to use it, the verification environment variable VX_FIELDS should be updated to include ``ASNOW``. This will allow the related workflow tasks to be run. + +``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 :term:`HPSS` (if the user has access) via the ``get_obs_mrms`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. + + 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, which is why the minutes and seconds of the filename are hard-coded as "0000". Because MRMS composite reflectivity files do not typically match the valid time exactly, a script (``ush/mrms_pull_topofhour.py``) is called from within the MRMS task that identifies and renames the MRMS file nearest to the valid time to match the valid time of the forecast. This script can also be called separately for staging data independently of the workflow. + +``NDAS_OBS_DIR``: (Default: "") + User-specified location of the top-level directory where NDAS prepbufr 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 :term:`HPSS` (if the user has access) via the ``get_obs_ndas`` task (activated in the workflow automatically when using the taskgroup file ``parm/wflow/verify_pre.yaml``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. METplus is configured to verify near-surface variables hourly and upper-air variables at 00 and 12 UTC with NDAS prepbufr files. + + METplus configuration files require the use of predetermined file names. Therefore, if the NDAS files are user-provided, they need to follow the anticipated naming structure: ``prepbufr.ndas.{YYYYMMDDHH}``, where YYYYMMDDHH is as described in the note :ref:`above `. The script to pull the NDAS data from the NOAA HPSS (``scripts/exregional_get_verif_obs.sh``) has an example of how to rename the NDAS data into a more intuitive format with the valid time listed in the file name. + +Test Directories +---------------------- + +These directories are used only by the ``run_WE2E_tests.py`` script, so they are not used unless the user runs a Workflow End-to-End (WE2E) test (see :numref:`Chapter %s `). Their function corresponds to the same variables without the ``TEST_`` prefix. Users typically should not modify these variables. For any alterations, the logic in the ``run_WE2E_tests.py`` script would need to be adjusted accordingly. + +``TEST_EXTRN_MDL_SOURCE_BASEDIR``: (Default: "") + This parameter allows testing of user-staged files in a known location on a given platform. This path contains a limited dataset and likely will not be useful for most user experiments. + +``TEST_PREGEN_BASEDIR``: (Default: "") + Similar to ``DOMAIN_PREGEN_BASEDIR``, this variable sets the base directory containing pregenerated grid, orography, and surface climatology files for WE2E tests. This is an alternative for setting ``GRID_DIR``, ``OROG_DIR``, and ``SFC_CLIMO_DIR`` individually. + +``TEST_ALT_EXTRN_MDL_SYSBASEDIR_ICS``: (Default: "") + This parameter is used to test the mechanism that allows users to point to a data stream on disk. It sets up a sandbox location that mimics the stream in a more controlled way and tests the ability to access :term:`ICS`. + +``TEST_ALT_EXTRN_MDL_SYSBASEDIR_LBCS``: (Default: "") + This parameter is used to test the mechanism that allows users to point to a data stream on disk. It sets up a sandbox location that mimics the stream in a more controlled way and tests the ability to access :term:`LBCS`. + + +.. _workflow: + +WORKFLOW Configuration Parameters +===================================== + +If non-default parameters are selected for the variables in this section, they should be added to the ``workflow:`` section of the ``config.yaml`` file. + +.. _Cron: + +Cron-Associated Parameters +------------------------------ + +Cron is a job scheduler accessed through the command-line on UNIX-like operating systems. It is useful for automating tasks such as the ``rocotorun`` command, which launches each workflow task in the SRW App. Cron periodically checks a cron table (aka crontab) to see if any tasks are are ready to execute. If so, it runs them. + +``USE_CRON_TO_RELAUNCH``: (Default: false) + Flag that determines whether or not a line is added to the user's cron table, which calls the experiment launch script every ``CRON_RELAUNCH_INTVL_MNTS`` minutes. Valid values: ``True`` | ``False`` + +``CRON_RELAUNCH_INTVL_MNTS``: (Default: 3) + The interval (in minutes) between successive calls of the experiment launch script by a cron job to (re)launch the experiment (so that the workflow for the experiment kicks off where it left off). This is used only if ``USE_CRON_TO_RELAUNCH`` is set to true. + +.. _DirParams: + +Directory Parameters +----------------------- + +``EXPT_BASEDIR``: (Default: "") + The full path to the base directory in which the experiment directory (``EXPT_SUBDIR``) will be created. If this is not specified or if it is set to an empty string, it will default to ``${HOMEdir}/../expt_dirs``, where ``${HOMEdir}`` contains the full path to the ``ufs-srweather-app`` directory. If set to a relative path, the provided path will be appended to the default value ``${HOMEdir}/../expt_dirs``. For example, if ``EXPT_BASEDIR=some/relative/path`` (i.e. a path that does not begin with ``/``), the value of ``EXPT_BASEDIR`` used by the workflow will be ``EXPT_BASEDIR=${HOMEdir}/../expt_dirs/some/relative/path``. + +``EXPT_SUBDIR``: (Default: "") + The user-designated name of the experiment directory (*not* its full path). The full path to the experiment directory, which will be contained in the variable ``EXPTDIR``, will be: + + .. code-block:: console + + EXPTDIR="${EXPT_BASEDIR}/${EXPT_SUBDIR}" + + This parameter cannot be left as a null string. It must be set to a non-null value in the user-defined experiment configuration file (i.e., ``config.yaml``). + +``EXEC_SUBDIR``: (Default: "exec") + The name of the subdirectory of ``ufs-srweather-app`` where executables are installed. + +Pre-Processing File Separator Parameters +-------------------------------------------- + +``DOT_OR_USCORE``: (Default: "_") + This variable sets the separator character(s) to use in the names of the grid, mosaic, and orography fixed files. Ideally, the same separator should be used in the names of these fixed files as in the surface climatology fixed files. Valid values: ``"_"`` | ``"."`` + + +Set File Name Parameters +---------------------------- + +``EXPT_CONFIG_FN``: (Default: "config.yaml") + Name of the user-specified configuration file for the forecast experiment. + +``CONSTANTS_FN``: (Default: "constants.yaml") + Name of the file containing definitions of various mathematical, physical, and SRW App contants. + +``RGNL_GRID_NML_FN``: (Default: "regional_grid.nml") + Name of the file containing namelist settings for the code that generates an "ESGgrid" regional grid. + +``FV3_NML_BASE_SUITE_FN``: (Default: "input.nml.FV3") + Name of the Fortran file containing the forecast model's base suite namelist (i.e., the portion of the namelist that is common to all physics suites). + +``FV3_NML_YAML_CONFIG_FN``: (Default: "FV3.input.yml") + Name of YAML configuration file containing the forecast model's namelist settings for various physics suites. + +``FV3_NML_BASE_ENS_FN``: (Default: "input.nml.base_ens") + Name of the Fortran file containing the forecast model's base ensemble namelist (i.e., the original namelist file from which each of the ensemble members' namelist files is generated). + +``FV3_EXEC_FN``: (Default: "ufs_model") + Name to use for the forecast model executable. + +``DIAG_TABLE_TMPL_FN``: (Default: "") + Name of a template file that specifies the output fields of the forecast model. The selected physics suite is appended to this file name in ``setup.py``, taking the form ``{DIAG_TABLE_TMPL_FN}.{CCPP_PHYS_SUITE}``. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``diag_table.{CCPP_PHYS_SUITE}``), and users should **not** specify a value for ``DIAG_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the names of the ``diag_table`` options in the ``ufs-srweather-app/parm`` directory. + +``FIELD_TABLE_TMPL_FN``: (Default: "") + Name of a template file that specifies the :term:`tracers ` that the forecast model will read in from the :term:`IC/LBC ` files. The selected physics suite is appended to this file name in ``setup.py``, taking the form ``{FIELD_TABLE_TMPL_FN}.{CCPP_PHYS_SUITE}``. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``field_table.{CCPP_PHYS_SUITE}``), and users should **not** specify a different value for ``FIELD_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the names of the ``field_table`` options in the ``ufs-srweather-app/parm`` directory. + +``DATA_TABLE_TMPL_FN``: (Default: "") + Name of a template file that contains the data table read in by the forecast model. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``data_table``), and users should **not** specify a different value for ``DATA_TABLE_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``data_table`` in the ``ufs-srweather-app/parm`` directory. + +``MODEL_CONFIG_TMPL_FN``: (Default: "") + Name of a template file that contains settings and configurations for the :term:`NUOPC`/:term:`ESMF` main component. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``model_configure``), and users should **not** specify a different value for ``MODEL_CONFIG_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``model_configure`` in the ``ufs-srweather-app/parm`` directory. + +``NEMS_CONFIG_TMPL_FN``: (Default: "") + Name of a template file that contains information about the various :term:`NEMS` components and their run sequence. Generally, the SRW App expects to read in the default value set in ``setup.py`` (i.e., ``nems.configure``), and users should **not** specify a different value for ``NEMS_CONFIG_TMPL_FN`` in their configuration file (i.e., ``config.yaml``) unless (1) the file name required by the model changes, and (2) they also change the name of ``nems.configure`` in the ``ufs-srweather-app/parm`` directory. + +``FCST_MODEL``: (Default: "ufs-weather-model") + Name of forecast model. Valid values: ``"ufs-weather-model"`` | ``"fv3gfs_aqm"`` + +``WFLOW_XML_FN``: (Default: "FV3LAM_wflow.xml") + Name of the Rocoto workflow XML file that the experiment generation script creates. This file defines the workflow for the experiment. + +``GLOBAL_VAR_DEFNS_FN``: (Default: "var_defns.sh") + Name of the file (a shell script) containing definitions of the primary and secondary experiment variables (parameters). This file is sourced by many scripts (e.g., the J-job scripts corresponding to each workflow task) in order to make all the experiment variables available in those scripts. The primary variables are defined in the default configuration script (``config_defaults.yaml``) and in ``config.yaml``. The secondary experiment variables are generated by the experiment generation script. + +``EXTRN_MDL_VAR_DEFNS_FN``: (Default: "extrn_mdl_var_defns") + Name of the file (a shell script) containing the definitions of variables associated with the external model from which :term:`ICs` or :term:`LBCs` are generated. This file is created by the ``GET_EXTRN_*`` task because the values of the variables it contains are not known before this task runs. The file is then sourced by the ``MAKE_ICS`` and ``MAKE_LBCS`` tasks. + +``WFLOW_LAUNCH_SCRIPT_FN``: (Default: "launch_FV3LAM_wflow.sh") + Name of the script that can be used to (re)launch the experiment's Rocoto workflow. + +``WFLOW_LAUNCH_LOG_FN``: (Default: "log.launch_FV3LAM_wflow") + Name of the log file that contains the output from successive calls to the workflow launch script (``WFLOW_LAUNCH_SCRIPT_FN``). + +.. _CCPP_Params: + +CCPP Parameter +------------------ + +``CCPP_PHYS_SUITE``: (Default: "FV3_GFS_v16") + This parameter indicates which :term:`CCPP` (Common Community Physics Package) physics suite to use for the forecast(s). The choice of physics suite determines the forecast model's namelist file, the diagnostics table file, the field table file, and the XML physics suite definition file, which are staged in the experiment directory or the :term:`cycle` directories under it. + + .. note:: + For information on *stochastic physics* parameters, see :numref:`Section %s `. + + **Current supported settings for the CCPP parameter are:** + + | ``"FV3_GFS_v16"`` + | ``"FV3_RRFS_v1beta"`` + | ``"FV3_HRRR"`` + | ``"FV3_WoFS_v0"`` + | ``"FV3_RAP"`` + + Other valid values can be found in the ``ush/valid_param_vals.yaml`` file, but users can not expect full support for these schemes. + + +.. _GridGen: + +Grid Generation Parameters +------------------------------ + +``GRID_GEN_METHOD``: (Default: "") + This variable specifies which method to use to generate a regional grid in the horizontal plane. The values that it can take on are: + + * ``"ESGgrid"``: The "ESGgrid" method will generate a regional version of the Extended Schmidt Gnomonic (ESG) grid using the map projection developed by Jim Purser of EMC (:cite:t:`Purser_2020`). "ESGgrid" is the preferred grid option. More information on the ESG grid is available at https://github.com/ufs-community/ufs-srweather-app/wiki/Purser_UIFCW_2023.pdf. + + * ``"GFDLgrid"``: The "GFDLgrid" method first generates a "parent" global cubed-sphere grid. Then a portion from tile 6 of the global grid is used as the regional grid. This regional grid is referred to in the grid generation scripts as "tile 7," even though it does not correspond to a complete tile. The forecast is run only on the regional grid (i.e., on tile 7, not on tiles 1 through 6). Note that the "GFDLgrid" method is the legacy grid generation method. It is not supported in *all* predefined domains. + +.. attention:: + + If the experiment uses a **predefined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to the name of a valid predefined grid), then ``GRID_GEN_METHOD`` will be reset to the value of ``GRID_GEN_METHOD`` for that grid. This will happen regardless of whether ``GRID_GEN_METHOD`` is assigned a value in the experiment configuration file; any value assigned will be overwritten. + +.. note:: + + If the experiment uses a **user-defined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to a null string), then ``GRID_GEN_METHOD`` must be set in the experiment configuration file. Otherwise, the experiment generation will fail because the generation scripts check to ensure that the grid name is set to a non-empty string before creating the experiment directory. + +Forecast Parameters +---------------------- +``DATE_FIRST_CYCL``: (Default: "YYYYMMDDHH") + Starting date of the first forecast in the set of forecasts to run. Format is "YYYYMMDDHH". + +``DATE_LAST_CYCL``: (Default: "YYYYMMDDHH") + Starting date of the last forecast in the set of forecasts to run. Format is "YYYYMMDDHH". + +``INCR_CYCL_FREQ``: (Default: 24) + Increment in hours for Rocoto cycle frequency. The default is 24, which means cycl_freq=24:00:00. + +``FCST_LEN_HRS``: (Default: 24) + The length of each forecast, in integer hours. + +Pre-Existing Directory Parameter +------------------------------------ +``PREEXISTING_DIR_METHOD``: (Default: "delete") + This variable determines how to deal with pre-existing directories (resulting from previous calls to the experiment generation script using the same experiment name [``EXPT_SUBDIR``] as the current experiment). This variable must be set to one of three valid values: ``"delete"``, ``"rename"``, or ``"quit"``. The behavior for each of these values is as follows: + + * **"delete":** The preexisting directory is deleted and a new directory (having the same name as the original preexisting directory) is created. + + * **"rename":** The preexisting directory is renamed and a new directory (having the same name as the original pre-existing directory) is created. The new name of the preexisting directory consists of its original name and the suffix "_old###", where ``###`` is a 3-digit integer chosen to make the new name unique. + + * **"quit":** The preexisting directory is left unchanged, but execution of the currently running script is terminated. In this case, the preexisting directory must be dealt with manually before rerunning the script. + +Verbose Parameter +--------------------- +``VERBOSE``: (Default: true) + Flag that determines whether the experiment generation and workflow task scripts print out extra informational messages. Valid values: ``True`` | ``False`` + +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 be reset to true if it isn't already. Valid values: ``True`` | ``False`` + +Compiler +----------- + +``COMPILER``: (Default: "intel") + Type of compiler invoked during the build step. Currently, this must be set manually; it is not inherited from the build system in the ``ufs-srweather-app`` directory. Valid values: ``"intel"`` | ``"gnu"`` + + +.. _NCOModeParms: + +NCO-Specific Variables +========================= + +A standard set of environment variables has been established for *nco* mode to simplify the production workflow and improve the troubleshooting process for operational and preoperational models. These variables are only used in *nco* mode (i.e., when ``RUN_ENVIR: "nco"``). When non-default parameters are selected for the variables in this section, they should be added to the ``nco:`` section of the ``config.yaml`` file. + +.. note:: + Only *community* mode is fully supported for this release. *nco* mode is used by those at the Environmental Modeling Center (EMC) and Global Systems Laboratory (GSL) who are working on pre-implementation operational testing. Other users should run the SRW App in *community* mode. + +``envir, NET, model_ver, RUN``: + Standard environment variables defined in the NCEP Central Operations WCOSS Implementation Standards document. These variables are used in forming the path to various directories containing input, output, and workflow files. The variables are defined in the `WCOSS Implementation Standards `__ document (pp. 4-5) as follows: + + ``envir``: (Default: "para") + Set to "test" during the initial testing phase, "para" when running in parallel (on a schedule), and "prod" in production. + + ``NET``: (Default: "rrfs") + Model name (first level of ``com`` directory structure) + + ``model_ver``: (Default: "v1.0.0") + Version number of package in three digits (second level of ``com`` directory) + + ``RUN``: (Default: "rrfs") + Name of model run (third level of ``com`` directory structure). In general, same as ``$NET``. + +``OPSROOT``: (Default: "") + The operations root directory in *nco* mode. + +.. _make-grid: + +MAKE_GRID Configuration Parameters +====================================== + +Non-default parameters for the ``make_grid`` task are set in the ``task_make_grid:`` section of the ``config.yaml`` file. + +Basic Task Parameters +-------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. Typically, users do not need to adjust the default values. + + ``GRID_DIR``: (Default: "") + The directory containing pre-generated grid files when the ``MAKE_GRID`` task is not meant to run. + +.. _ESGgrid: + +ESGgrid Settings +------------------- + +The following parameters must be set if using the "ESGgrid" method to generate a regional grid (i.e., when ``GRID_GEN_METHOD: "ESGgrid"``, see :numref:`Section %s `). If a different ``GRID_GEN_METHOD`` is used, these parameters will be ignored. When using a predefined grid with ``GRID_GEN_METHOD: "ESGgrid"``, the values in this section will be set automatically to the assigned values for that grid. + +``ESGgrid_LON_CTR``: (Default: "") + The longitude of the center of the grid (in degrees). + +``ESGgrid_LAT_CTR``: (Default: "") + The latitude of the center of the grid (in degrees). + +``ESGgrid_DELX``: (Default: "") + The cell size in the zonal direction of the regional grid (in meters). + +``ESGgrid_DELY``: (Default: "") + The cell size in the meridional direction of the regional grid (in meters). + +``ESGgrid_NX``: (Default: "") + The number of cells in the zonal direction on the regional grid. + +``ESGgrid_NY``: (Default: "") + The number of cells in the meridional direction on the regional grid. + +``ESGgrid_PAZI``: (Default: "") + The rotational parameter for the "ESGgrid" (in degrees). + +``ESGgrid_WIDE_HALO_WIDTH``: (Default: "") + The width (in number of grid cells) of the :term:`halo` to add around the regional grid before shaving the halo down to the width(s) expected by the forecast model. The user need not specify this variable since it is set automatically in ``set_gridparams_ESGgrid.py`` + +.. _WideHalo: + +.. note:: + A :term:`halo` is the strip of cells surrounding the regional grid; the halo is used to feed in the lateral boundary conditions to the grid. The forecast model requires **grid** files containing 3-cell- and 4-cell-wide halos and **orography** files with 0-cell- and 3-cell-wide halos. In order to generate grid and orography files with appropriately-sized halos, the grid and orography tasks create preliminary files with halos around the regional domain of width ``ESGgrid_WIDE_HALO_WIDTH`` cells. The files are then read in and "shaved" down to obtain grid files with 3-cell-wide and 4-cell-wide halos and orography files with 0-cell-wide and 3-cell-wide halos. The original halo that gets shaved down is referred to as the "wide" halo because it is wider than the 0-cell-wide, 3-cell-wide, and 4-cell-wide halos that users eventually end up with. Note that the grid and orography files with the wide halo are only needed as intermediates in generating the files with 0-cell-, 3-cell-, and 4-cell-wide halos; they are not needed by the forecast model. + +GFDLgrid Settings +--------------------- + +The following parameters must be set if using the "GFDLgrid" method to generate a regional grid (i.e., when ``GRID_GEN_METHOD: "GFDLgrid"``, see :numref:`Section %s `). If a different ``GRID_GEN_METHOD`` is used, these parameters will be ignored. When using a predefined grid with ``GRID_GEN_METHOD: "GFDLgrid"``, the values in this section will be set automatically to the assigned values for that grid. + +Note that the regional grid is defined with respect to a "parent" global cubed-sphere grid. Thus, all the parameters for a global cubed-sphere grid must be specified even though the model equations are integrated only on the regional grid. Tile 6 has arbitrarily been chosen as the tile to use to orient the global parent grid on the sphere (Earth). For convenience, the regional grid is denoted as "tile 7" even though it is embedded within tile 6 (i.e., it doesn't extend beyond the boundary of tile 6). Its exact location within tile 6 is determined by specifying the starting and ending i- and j-indices of the regional grid on tile 6, where ``i`` is the grid index in the x direction and ``j`` is the grid index in the y direction. All of this information is set in the variables below. + +``GFDLgrid_LON_T6_CTR``: (Default: "") + Longitude of the center of tile 6 (in degrees). + +``GFDLgrid_LAT_T6_CTR``: (Default: "") + Latitude of the center of tile 6 (in degrees). + +``GFDLgrid_NUM_CELLS``: (Default: "") + Number of grid cells in either of the two horizontal directions (x and y) on each of the six tiles of the parent global cubed-sphere grid. Valid values: ``48`` | ``96`` | ``192`` | ``384`` | ``768`` | ``1152`` | ``3072`` + + To give an idea of what these values translate to in terms of grid cell size in kilometers, we list below the approximate grid cell size on a uniform global grid having the specified value of ``GFDLgrid_NUM_CELLS``, where by "uniform" we mean with Schmidt stretch factor ``GFDLgrid_STRETCH_FAC: "1"`` (although in regional applications ``GFDLgrid_STRETCH_FAC`` will typically be set to a value greater than ``"1"`` to obtain a smaller grid size on tile 6): + + +---------------------+--------------------+ + | GFDLgrid_NUM_CELLS | Typical Cell Size | + +=====================+====================+ + | 48 | 200 km | + +---------------------+--------------------+ + | 96 | 100 km | + +---------------------+--------------------+ + | 192 | 50 km | + +---------------------+--------------------+ + | 384 | 25 km | + +---------------------+--------------------+ + | 768 | 13 km | + +---------------------+--------------------+ + | 1152 | 8.5 km | + +---------------------+--------------------+ + | 3072 | 3.2 km | + +---------------------+--------------------+ + + Note that these are only typical cell sizes. The actual cell size on the global grid tiles varies somewhat as we move across a tile and is also dependent on ``GFDLgrid_STRETCH_FAC``, which modifies the shape and size of the tile. + +``GFDLgrid_STRETCH_FAC``: (Default: "") + Stretching factor used in the Schmidt transformation applied to the parent cubed-sphere grid. Setting the Schmidt stretching factor to a value greater than 1 shrinks tile 6, while setting it to a value less than 1 (but still greater than 0) expands it. The remaining 5 tiles change shape as necessary to maintain global coverage of the grid. + +``GFDLgrid_REFINE_RATIO``: (Default: "") + Cell refinement ratio for the regional grid. It refers to the number of cells in either the x or y direction on the regional grid (tile 7) that abut one cell on its parent tile (tile 6). + +``GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G``: (Default: "") + i-index on tile 6 at which the regional grid (tile 7) starts. + +``GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G``: (Default: "") + i-index on tile 6 at which the regional grid (tile 7) ends. + +``GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G``: (Default: "") + j-index on tile 6 at which the regional grid (tile 7) starts. + +``GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G``: (Default: "") + j-index on tile 6 at which the regional grid (tile 7) ends. + +``GFDLgrid_USE_NUM_CELLS_IN_FILENAMES``: (Default: "") + Flag that determines the file naming convention to use for grid, orography, and surface climatology files (or, if using pregenerated files, the naming convention that was used to name these files). These files usually start with the string ``"C${RES}_"``, where ``RES`` is an integer. In the global forecast model, ``RES`` is the number of points in each of the two horizontal directions (x and y) on each tile of the global grid (defined here as ``GFDLgrid_NUM_CELLS``). If this flag is set to true, ``RES`` will be set to ``GFDLgrid_NUM_CELLS`` just as in the global forecast model. If it is set to false, we calculate (in the grid generation task) an "equivalent global uniform cubed-sphere resolution" --- call it ``RES_EQUIV`` --- and then set ``RES`` equal to it. ``RES_EQUIV`` is the number of grid points in each of the x and y directions on each tile that a global UNIFORM (i.e., stretch factor of 1) cubed-sphere grid would need to have in order to have the same average grid size as the regional grid. This is a more useful indicator of the grid size because it takes into account the effects of ``GFDLgrid_NUM_CELLS``, ``GFDLgrid_STRETCH_FAC``, and ``GFDLgrid_REFINE_RATIO`` in determining the regional grid's typical grid size, whereas simply setting ``RES`` to ``GFDLgrid_NUM_CELLS`` doesn't take into account the effects of ``GFDLgrid_STRETCH_FAC`` and ``GFDLgrid_REFINE_RATIO`` on the regional grid's resolution. Nevertheless, some users still prefer to use ``GFDLgrid_NUM_CELLS`` in the file names, so we allow for that here by setting this flag to true. + +.. _make-orog: + +MAKE_OROG Configuration Parameters +===================================== + +Non-default parameters for the ``make_orog`` task are set in the ``task_make_orog:`` section of the ``config.yaml`` file. + +``KMP_AFFINITY_MAKE_OROG``: (Default: "disabled") + Intel Thread Affinity Interface for the ``make_orog`` task. See :ref:`this note ` for more information on thread affinity. Settings for the ``make_orog`` task is disabled because this task does not use parallelized code. + +``OMP_NUM_THREADS_MAKE_OROG``: (Default: 6) + The number of OpenMP threads to use for parallel regions. + + + +``OMP_STACKSIZE_MAKE_OROG``: (Default: "2048m") + Controls the size of the stack for threads created by the OpenMP implementation. + +``OROG_DIR``: (Default: "") + The directory containing pre-generated orography files to use when the ``MAKE_OROG`` task is not meant to run. + +.. _make-sfc-climo: + +MAKE_SFC_CLIMO Configuration Parameters +=========================================== + +Non-default parameters for the ``make_sfc_climo`` task are set in the ``task_make_sfc_climo:`` section of the ``config.yaml`` file. + +``KMP_AFFINITY_MAKE_SFC_CLIMO``: (Default: "scatter") + Intel Thread Affinity Interface for the ``make_sfc_climo`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_MAKE_SFC_CLIMO``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_MAKE_SFC_CLIMO``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +``SFC_CLIMO_DIR``: (Default: "") + The directory containing pre-generated surface climatology files to use when the ``MAKE_SFC_CLIMO`` task is not meant to run. + +.. _task_get_extrn_ics: + +GET_EXTRN_ICS Configuration Parameters +========================================= + +Non-default parameters for the ``get_extrn_ics`` task are set in the ``task_get_extrn_ics:`` section of the ``config.yaml`` file. + +.. _basic-get-extrn-ics: + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``EXTRN_MDL_NAME_ICS``: (Default: "FV3GFS") + The name of the external model that will provide fields from which initial condition (IC) files, surface files, and 0-th hour boundary condition files will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` + +``EXTRN_MDL_ICS_OFFSET_HRS``: (Default: 0) + Users may wish to start a forecast using forecast data from a previous cycle of an external model. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should start from a 6-hour forecast of the GFS, then ``EXTRN_MDL_ICS_OFFSET_HRS: "6"``. + +``FV3GFS_FILE_FMT_ICS``: (Default: "nemsio") + If using the FV3GFS model as the source of the :term:`ICs` (i.e., if ``EXTRN_MDL_NAME_ICS: "FV3GFS"``), this variable specifies the format of the model files to use when generating the ICs. Valid values: ``"nemsio"`` | ``"grib2"`` | ``"netcdf"`` + +File and Directory Parameters +-------------------------------- + +``USE_USER_STAGED_EXTRN_FILES``: (Default: false) + Flag that determines whether the workflow will look for the external model files needed for generating :term:`ICs` in user-specified directories (rather than fetching them from mass storage like NOAA :term:`HPSS`). Valid values: ``True`` | ``False`` + +``EXTRN_MDL_SOURCE_BASEDIR_ICS``: (Default: "") + Directory containing external model files for generating ICs. If ``USE_USER_STAGED_EXTRN_FILES`` is set to true, the workflow looks within this directory for a subdirectory named "YYYYMMDDHH", which contains the external model files specified by the array ``EXTRN_MDL_FILES_ICS``. This "YYYYMMDDHH" subdirectory corresponds to the start date and cycle hour of the forecast (see :ref:`above `). These files will be used to generate the :term:`ICs` on the native FV3-LAM grid. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. + +``EXTRN_MDL_SYSBASEDIR_ICS``: (Default: '') + A known location of a real data stream on a given platform. This is typically a real-time data stream as on Hera, Jet, or WCOSS. External model files for generating :term:`ICs` on the native grid should be accessible via this data stream. The way the full path containing these files is constructed depends on the user-specified external model for ICs (defined above in :numref:`Section %s ` ``EXTRN_MDL_NAME_ICS``). + + .. note:: + This variable must be defined as a null string in ``config_defaults.yaml`` so that if it is specified by the user in the experiment configuration file (``config.yaml``), it remains set to those values, and if not, it gets set to machine-dependent values. + +``EXTRN_MDL_FILES_ICS``: (Default: "") + Array containing templates of the file names to search for in the ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` directory. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. A single template should be used for each model file type that is used. Users may use any of the Python-style templates allowed in the ``ush/retrieve_data.py`` script. To see the full list of supported templates, run that script with the ``-h`` option. + + For example, to set FV3GFS nemsio input files: + + .. code-block:: console + + EXTRN_MDL_FILES_ICS=[ gfs.t{hh}z.atmf{fcst_hr:03d}.nemsio , + gfs.t{hh}z.sfcf{fcst_hr:03d}.nemsio ] + + To set FV3GFS grib files: + + .. code-block:: console + + EXTRN_MDL_FILES_ICS=[ gfs.t{hh}z.pgrb2.0p25.f{fcst_hr:03d} ] + +``EXTRN_MDL_DATA_STORES``: (Default: "") + A list of data stores where the scripts should look to find external model data. The list is in priority order. If disk information is provided via ``USE_USER_STAGED_EXTRN_FILES`` or a known location on the platform, the disk location will receive highest priority. Valid values: ``disk`` | ``hpss`` | ``aws`` | ``nomads`` + +NOMADS Parameters +--------------------- + +Set parameters associated with NOMADS online data. + +``NOMADS``: (Default: false) + Flag controlling whether to use NOMADS online data. Valid values: ``True`` | ``False`` + +``NOMADS_file_type``: (Default: "nemsio") + Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"`` + +.. _task_get_extrn_lbcs: + +GET_EXTRN_LBCS Configuration Parameters +========================================== + +Non-default parameters for the ``get_extrn_lbcs`` task are set in the ``task_get_extrn_lbcs:`` section of the ``config.yaml`` file. + +.. _basic-get-extrn-lbcs: + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``EXTRN_MDL_NAME_LBCS``: (Default: "FV3GFS") + The name of the external model that will provide fields from which lateral boundary condition (LBC) files (except for the 0-th hour LBC file) will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` + +``LBC_SPEC_INTVL_HRS``: (Default: "6") + The interval (in integer hours) at which LBC files will be generated. This is also referred to as the *boundary update interval*. Note that the model selected in ``EXTRN_MDL_NAME_LBCS`` must have data available at a frequency greater than or equal to that implied by ``LBC_SPEC_INTVL_HRS``. For example, if ``LBC_SPEC_INTVL_HRS`` is set to "6", then the model must have data available at least every 6 hours. It is up to the user to ensure that this is the case. + +``EXTRN_MDL_LBCS_OFFSET_HRS``: (Default: "") + Users may wish to use lateral boundary conditions from a forecast that was started earlier than the start of the forecast configured here. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should use lateral boundary conditions from the GFS started 6 hours earlier, then ``EXTRN_MDL_LBCS_OFFSET_HRS: "6"``. Note: the default value is model-dependent and is set in ``ush/set_extrn_mdl_params.py``. + +``FV3GFS_FILE_FMT_LBCS``: (Default: "nemsio") + If using the FV3GFS model as the source of the :term:`LBCs` (i.e., if ``EXTRN_MDL_NAME_LBCS: "FV3GFS"``), this variable specifies the format of the model files to use when generating the LBCs. Valid values: ``"nemsio"`` | ``"grib2"`` | ``"netcdf"`` + + +File and Directory Parameters +-------------------------------- + +``USE_USER_STAGED_EXTRN_FILES``: (Default: false) + Analogous to ``USE_USER_STAGED_EXTRN_FILES`` in :term:`ICs` but for :term:`LBCs`. Flag that determines whether the workflow will look for the external model files needed for generating :term:`LBCs` in user-specified directories (rather than fetching them from mass storage like NOAA :term:`HPSS`). Valid values: ``True`` | ``False`` + +``EXTRN_MDL_SOURCE_BASEDIR_LBCS``: (Default: "") + Analogous to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` but for :term:`LBCs` instead of :term:`ICs`. + Directory containing external model files for generating LBCs. If ``USE_USER_STAGED_EXTRN_FILES`` is set to true, the workflow looks within this directory for a subdirectory named "YYYYMMDDHH", which contains the external model files specified by the array ``EXTRN_MDL_FILES_LBCS``. This "YYYYMMDDHH" subdirectory corresponds to the start date and cycle hour of the forecast (see :ref:`above `). These files will be used to generate the :term:`LBCs` on the native FV3-LAM grid. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. + +``EXTRN_MDL_SYSBASEDIR_LBCS``: (Default: '') + Same as ``EXTRN_MDL_SYSBASEDIR_ICS`` but for :term:`LBCs`. A known location of a real data stream on a given platform. This is typically a real-time data stream as on Hera, Jet, or WCOSS. External model files for generating :term:`LBCs` on the native grid should be accessible via this data stream. The way the full path containing these files is constructed depends on the user-specified external model for LBCs (defined above in :numref:`Section %s ` ``EXTRN_MDL_NAME_LBCS`` above). + + .. note:: + This variable must be defined as a null string in ``config_defaults.yaml`` so that if it is specified by the user in the experiment configuration file (``config.yaml``), it remains set to those values, and if not, it gets set to machine-dependent values. + +``EXTRN_MDL_FILES_LBCS``: (Default: "") + Analogous to ``EXTRN_MDL_FILES_ICS`` but for :term:`LBCs` instead of :term:`ICs`. Array containing templates of the file names to search for in the ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` directory. This variable is not used if ``USE_USER_STAGED_EXTRN_FILES`` is set to false. A single template should be used for each model file type that is used. Users may use any of the Python-style templates allowed in the ``ush/retrieve_data.py`` script. To see the full list of supported templates, run that script with the ``-h`` option. For examples, see the ``EXTRN_MDL_FILES_ICS`` variable above. + +``EXTRN_MDL_DATA_STORES``: (Default: "") + Analogous to ``EXTRN_MDL_DATA_STORES`` in :term:`ICs` but for :term:`LBCs`. A list of data stores where the scripts should look to find external model data. The list is in priority order. If disk information is provided via ``USE_USER_STAGED_EXTRN_FILES`` or a known location on the platform, the disk location will receive highest priority. Valid values: ``disk`` | ``hpss`` | ``aws`` | ``nomads`` + +NOMADS Parameters +--------------------- + +Set parameters associated with NOMADS online data. Analogus to :term:`ICs` NOMADS Parameters. + +``NOMADS``: (Default: false) + Flag controlling whether to use NOMADS online data. + +``NOMADS_file_type``: (Default: "nemsio") + Flag controlling the format of the data. Valid values: ``"GRIB2"`` | ``"grib2"`` | ``"NEMSIO"`` | ``"nemsio"`` + +MAKE_ICS Configuration Parameters +====================================== + +Non-default parameters for the ``make_ics`` task are set in the ``task_make_ics:`` section of the ``config.yaml`` file. + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``KMP_AFFINITY_MAKE_ICS``: (Default: "scatter") + Intel Thread Affinity Interface for the ``make_ics`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_MAKE_ICS``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_MAKE_ICS``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +FVCOM Parameter +------------------- +``USE_FVCOM``: (Default: false) + Flag that specifies whether to update surface conditions in FV3-:term:`LAM` with fields generated from the Finite Volume Community Ocean Model (:term:`FVCOM`). If set to true, lake/sea surface temperatures, ice surface temperatures, and ice placement will be overwritten using data provided by FVCOM. Setting ``USE_FVCOM`` to true causes the executable ``process_FVCOM.exe`` in the ``MAKE_ICS`` task to run. This, in turn, modifies the file ``sfc_data.nc`` generated by ``chgres_cube`` during the ``make_ics`` task. Note that the FVCOM data must already be interpolated to the desired FV3-LAM grid. Valid values: ``True`` | ``False`` + +``FVCOM_WCSTART``: (Default: "cold") + Define if this is a "warm" start or a "cold" start. Setting this to "warm" will read in ``sfc_data.nc`` generated in a RESTART directory. Setting this to "cold" will read in the ``sfc_data.nc`` generated from ``chgres_cube`` in the ``make_ics`` portion of the workflow. Valid values: ``"cold"`` | ``"COLD"`` | ``"warm"`` | ``"WARM"`` + +``FVCOM_DIR``: (Default: "") + User-defined directory where the ``fvcom.nc`` file containing :term:`FVCOM` data already interpolated to the FV3-LAM native grid is located. The file in this directory must be named ``fvcom.nc``. + +``FVCOM_FILE``: (Default: "fvcom.nc") + Name of the file located in ``FVCOM_DIR`` that has :term:`FVCOM` data interpolated to the FV3-LAM grid. This file will be copied later to a new location, and the name will be changed to ``fvcom.nc`` if a name other than ``fvcom.nc`` is selected. + + +MAKE_LBCS Configuration Parameters +====================================== + +Non-default parameters for the ``make_lbcs`` task are set in the ``task_make_lbcs:`` section of the ``config.yaml`` file. + +``KMP_AFFINITY_MAKE_LBCS``: (Default: "scatter") + Intel Thread Affinity Interface for the ``make_lbcs`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_MAKE_LBCS``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_MAKE_LBCS``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +.. _FcstConfigParams: + +FORECAST Configuration Parameters +===================================== + +Non-default parameters for the ``run_fcst`` task are set in the ``task_run_fcst:`` section of the ``config.yaml`` file. + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``KMP_AFFINITY_RUN_FCST``: (Default: "scatter") + Intel Thread Affinity Interface for the ``run_fcst`` task. + +.. _thread-affinity: + + .. note:: + + **Thread Affinity Interface** + + "Intel's runtime library can bind OpenMP threads to physical processing units. The interface is controlled using the ``KMP_AFFINITY`` environment variable. Thread affinity restricts execution of certain threads to a subset of the physical processing units in a multiprocessor computer. Depending on the system (machine) topology, application, and operating system, thread affinity can have a dramatic effect on the application speed and on the execution speed of a program." Valid values: ``"scatter"`` | ``"disabled"`` | ``"balanced"`` | ``"compact"`` | ``"explicit"`` | ``"none"`` + + For more information, see the `Intel Development Reference Guide `__. + +``OMP_NUM_THREADS_RUN_FCST``: (Default: 2) + The number of OpenMP threads to use for parallel regions. Corresponds to the ``atmos_nthreads`` value in ``model_configure``. + +``OMP_STACKSIZE_RUN_FCST``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +.. _ModelConfigParams: + +Model Configuration Parameters +---------------------------------- + +These parameters set values in the Weather Model's ``model_configure`` file. + +``DT_ATMOS``: (Default: "") + Time step for the outermost atmospheric model loop in seconds. This corresponds to the frequency at which the physics routines and the top level dynamics routine are called. (Note that one call to the top-level dynamics routine results in multiple calls to the horizontal dynamics, :term:`tracer` transport, and vertical dynamics routines; see the `FV3 dycore scientific documentation `__ for details.) Must be set. Takes an integer value. In the SRW App, a default value for ``DT_ATMOS`` appears in the ``set_predef_grid_params.yaml`` script, but a different value can be set in ``config.yaml``. In general, the smaller the grid cell size is, the smaller this value needs to be in order to avoid numerical instabilities during the forecast. + +``RESTART_INTERVAL``: (Default: 0) + Frequency of the output restart files in hours. Using the default interval (0), restart files are produced at the end of a forecast run. When ``RESTART_INTERVAL: 1``, restart files are produced every hour with the prefix "YYYYMMDD.HHmmSS." in the ``RESTART`` directory. + +.. _InlinePost: + +``WRITE_DOPOST``: (Default: false) + Flag that determines whether to use the inline post option. The default ``WRITE_DOPOST: false`` does not use the inline post functionality, and the ``run_post`` tasks are called from outside of the Weather Model. If ``WRITE_DOPOST: true``, the ``WRITE_DOPOST`` flag in the ``model_configure`` file will be set to true, and the post-processing (:term:`UPP`) tasks will be called from within the Weather Model. This means that the post-processed files (in :term:`grib2` format) are output by the Weather Model at the same time that it outputs the ``dynf###.nc`` and ``phyf###.nc`` files. Setting ``WRITE_DOPOST: true`` turns off the separate ``run_post`` task in ``setup.py`` to avoid unnecessary computations. Valid values: ``True`` | ``False`` + +Computational Parameters +---------------------------- + +``LAYOUT_X, LAYOUT_Y``: (Default: "") + The number of :term:`MPI` tasks (processes) to use in the two horizontal directions (x and y) of the regional grid when running the forecast model. + +``BLOCKSIZE``: (Default: "") + The amount of data that is passed into the cache at a time. + +.. note:: + + In ``config_defaults.yaml`` the computational parameters are set to null strings so that: + + #. If the experiment is using a predefined grid and the user sets the parameter in the user-specified experiment configuration file (i.e., ``config.yaml``), that value will be used in the forecast(s). Otherwise, the default value for that predefined grid will be used. + #. If the experiment is *not* using a predefined grid (i.e., it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the parameter in that configuration file. Otherwise, the parameter will remain set to a null string, and the experiment generation will fail because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory. + +.. _WriteComp: + +Write-Component (Quilting) Parameters +----------------------------------------- + +.. note:: + The :term:`UPP` (called by the ``RUN_POST`` 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 use an Earth System Modeling Framework (:term:`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``. + + 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`` (meta)task cannot run because the :term:`UPP` code called by this task cannot process fields on the native grid. In that case, the ``RUN_POST`` (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. Valid values: ``True`` | ``False`` + +``PRINT_ESMF``: (Default: false) + Flag that determines whether to output extra (debugging) information from :term:`ESMF` routines. 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). Valid values: ``True`` | ``False`` + +``WRTCMP_write_groups``: (Default: 1) + The number of write groups (i.e., groups of :term:`MPI` tasks) to use in the write component. Each write group will write 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 ``WRTCMP_write_tasks_per_group`` tasks. Usually, one write group is sufficient. 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. + +``WRTCMP_write_tasks_per_group``: (Default: 20) + 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.yaml`` 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. + +``WRTCMP_cen_lat``: (Default: "") + 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 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 when running an experiment with a user-defined grid. + +**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "rotated_latlon":** + +``WRTCMP_lon_upr_rght``: (Default: "") + Longitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated longitude). + +``WRTCMP_lat_upr_rght``: (Default: "") + Latitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated latitude). + +``WRTCMP_dlon``: (Default: "") + Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated longitude). + +``WRTCMP_dlat``: (Default: "") + Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated latitude). + +**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "lambert_conformal":** + +``WRTCMP_stdlat1``: (Default: "") + First standard latitude (in degrees) in definition of Lambert conformal projection. + +``WRTCMP_stdlat2``: (Default: "") + Second standard latitude (in degrees) in definition of Lambert conformal projection. + +``WRTCMP_nx``: (Default: "") + Number of grid points in the x-coordinate of the Lambert conformal projection. + +``WRTCMP_ny``: (Default: "") + Number of grid points in the y-coordinate of the Lambert conformal projection. + +``WRTCMP_dx``: (Default: "") + Grid cell size (in meters) along the x-axis of the Lambert conformal projection. + +``WRTCMP_dy``: (Default: "") + Grid cell size (in meters) along the y-axis of the Lambert conformal projection. + +.. _PredefGrid: + +Predefined Grid Parameters +------------------------------ + +``PREDEF_GRID_NAME``: (Default: "") + This parameter indicates which (if any) predefined regional grid to use for the experiment. Setting ``PREDEF_GRID_NAME`` provides a convenient method of specifying a commonly used set of grid-dependent parameters. The predefined grid settings can be viewed in the script ``ush/set_predef_grid_params.yaml``. + + **Currently supported options:** + + | ``"RRFS_CONUS_25km"`` + | ``"RRFS_CONUS_13km"`` + | ``"RRFS_CONUS_3km"`` + | ``"SUBCONUS_Ind_3km"`` + + **Other valid values include:** + + | ``"CONUS_25km_GFDLgrid"`` + | ``"CONUS_3km_GFDLgrid"`` + | ``"EMC_AK"`` + | ``"EMC_HI"`` + | ``"EMC_PR"`` + | ``"EMC_GU"`` + | ``"GSL_HAFSV0.A_25km"`` + | ``"GSL_HAFSV0.A_13km"`` + | ``"GSL_HAFSV0.A_3km"`` + | ``"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:: + + * If ``PREDEF_GRID_NAME`` is set to a valid predefined grid name, the grid generation 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.yaml``). 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. + + * If ``PREDEF_GRID_NAME`` is set to an empty string, it implies that the user will provide the native grid parameters in the user-specified experiment configuration file (``config.yaml``). In this case, the grid generation method, the native grid parameters, the write component grid parameters, the main time step (``DT_ATMOS``), and the computational parameters (``LAYOUT_X``, ``LAYOUT_Y``, and ``BLOCKSIZE``) must be set in the configuration file. Otherwise, the values of the parameters in the default experiment configuration file (``config_defaults.yaml``) will be used. + +Aerosol Climatology Parameter +--------------------------------- + +``USE_MERRA_CLIMO``: (Default: false) + Flag that determines whether :term:`MERRA2` aerosol climatology data and lookup tables for optics properties are obtained. Valid values: ``True`` | ``False`` + + .. COMMENT: When would it be appropriate to obtain these files? + +Fixed File Parameters +------------------------- + +These parameters are associated with the fixed (i.e., static) files. On `Level 1 & 2 `__ systems, fixed files are pre-staged with paths defined in the ``setup.py`` script. Because the default values are platform-dependent, they are set to a null string in ``config_defaults.yaml``. Then these null values are overwritten in ``setup.py`` with machine-specific values or with a user-specified value from ``config.yaml``. + +``FIXgsm``: (Default: "") + System directory in which the majority of fixed (i.e., time-independent) files that are needed to run the FV3-LAM model are located. + +``FIXaer``: (Default: "") + System directory where :term:`MERRA2` aerosol climatology files are located. + +``FIXlut``: (Default: "") + System directory where the lookup tables for optics properties are located. + +``FIXshp``: (Default: "") + System directory where the graphics shapefiles are located. On Level 1 systems, these are set within the machine files. Users on other systems will need to provide the path to the directory that contains the *Natural Earth* shapefiles. + +``FIXorg``: (Default: "") + The location on disk of the static input files used by the ``make_orog`` task (i.e., ``orog.x`` and ``shave.x``). Can be the same as ``FIXgsm``. + +``FIXsfc``: (Default: "") + The location on disk of the static surface climatology input fields, used by ``sfc_climo_gen``. These files are only used if the ``MAKE_SFC_CLIMO`` task is meant to run. + +``SYMLINK_FIX_FILES``: (Default: true) + Flag that indicates whether to symlink or copy fix files to the experiment directory. + +RUN_POST Configuration Parameters +===================================== + +Non-default parameters for the ``run_post`` task are set in the ``task_run_post:`` section of the ``config.yaml`` file. + +Basic Task Parameters +--------------------------------- + +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``KMP_AFFINITY_RUN_POST``: (Default: "scatter") + Intel Thread Affinity Interface for the ``run_post`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_RUN_POST``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_RUN_POST``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + + +Subhourly Post Parameters +----------------------------- +Set parameters associated with subhourly forecast model output and post-processing. + +``SUB_HOURLY_POST``: (Default: false) + 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 valid value between 1 and 59. Valid values: ``True`` | ``False`` + +``DT_SUB_HOURLY_POST_MNTS``: (Default: 0) + Time interval in minutes between the forecast model output files (only used if ``SUB_HOURLY_POST`` is set to true). If ``SUB_HOURLY_POST`` is set to true, this needs to be set to a valid two-digit integer between 1 and 59. Note that if ``SUB_HOURLY_POST`` is set to true but ``DT_SUB_HOURLY_POST_MNTS`` is set to 0, ``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: ``0`` | ``1`` | ``2`` | ``3`` | ``4`` | ``5`` | ``6`` | ``10`` | ``12`` | ``15`` | ``20`` | ``30`` + +Customized Post Configuration Parameters +-------------------------------------------- + +Set parameters for customizing the :term:`UPP`. + +``USE_CUSTOM_POST_CONFIG_FILE``: (Default: false) + Flag that determines whether a user-provided custom configuration file should be used for post-processing the model data. If this is set to true, then the workflow will use the custom post-processing (:term:`UPP`) configuration file specified in ``CUSTOM_POST_CONFIG_FP``. Otherwise, a default configuration file provided in the UPP repository will be used. Valid values: ``True`` | ``False`` + +``CUSTOM_POST_CONFIG_FP``: (Default: "") + The full path to the custom post flat file, including filename, to be used for post-processing. This is only used if ``CUSTOM_POST_CONFIG_FILE`` is set to true. + +``POST_OUTPUT_DOMAIN_NAME``: (Default: "") + Domain name (in lowercase) used to construct the names of the output files generated by the :term:`UPP`. If using a predefined grid, ``POST_OUTPUT_DOMAIN_NAME`` defaults to ``PREDEF_GRID_NAME``. If using a custom grid, ``POST_OUTPUT_DOMAIN_NAME`` must be specified by the user. The post output files are named as follows: + + .. code-block:: console + + $NET.tHHz.[var_name].f###.${POST_OUTPUT_DOMAIN_NAME}.grib2 + + Note that this variable is first changed to lower case before being used to construct the file names. + +RUN_PRDGEN Configuration Parameters +===================================== + +Non-default parameters for the ``run_prdgen`` task are set in the ``task_run_prdgen:`` section of the ``config.yaml`` file. + +Basic Task Parameters +--------------------------------- +For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. + +``KMP_AFFINITY_RUN_PRDGEN``: (Default: "scatter") + Intel Thread Affinity Interface for the ``run_prdgen`` task. See :ref:`this note ` for more information on thread affinity. + +``OMP_NUM_THREADS_RUN_PRDGEN``: (Default: 1) + The number of OpenMP threads to use for parallel regions. + +``OMP_STACKSIZE_RUN_PRDGEN``: (Default: "1024m") + Controls the size of the stack for threads created by the OpenMP implementation. + +``DO_PARALLEL_PRDGEN``: (Default: false) + Flag that determines whether to use CFP to run the product generation job in parallel. CFP is a utility that allows the user to launch a number of small jobs across nodes/cpus in one batch command. This option should be used with the ``RRFS_NA_3km`` grid and ``PPN_RUN_PRDGEN`` should be set to 22. + +``ADDNL_OUTPUT_GRIDS``: (Default: []) + Set additional output grids for wgrib2 remapping, if any. Space-separated list of strings, e.g., ( "130" "242" "clue"). Default is no additional grids. + +``TESTBED_FIELDS_FN``: (Default: "") + The file which lists grib2 fields to be extracted for testbed files. Empty string means no need to generate testbed files. + +.. _PlotVars: + +PLOT_ALLVARS Configuration Parameters +======================================== + +Typically, the following parameters must be set explicitly by the user in the configuration file (``config.yaml``) when executing the plotting tasks. + +``COMOUT_REF``: (Default: "") + The directory where the GRIB2 files from post-processing are located. In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will correspond to the location in the experiment directory where the post-processed output can be found (e.g., ``$EXPTDIR/$DATE_FIRST_CYCL/postprd``). In *nco* mode, this directory should be set to the location of the ``COMOUT`` directory and end with ``$PDY/$cyc``. For more detail on *nco* standards and directory naming conventions, see `WCOSS Implementation Standards `__ (particularly pp. 4-5). + +``PLOT_FCST_START``: (Default: 0) + The starting forecast hour for the plotting task. For example, if a forecast starts at 18h/18z, this is considered the 0th forecast hour, so "starting forecast hour" should be 0, not 18. If a forecast starts at 18h/18z, but the user only wants plots from the 6th forecast hour on, "starting forecast hour" should be 6. + +``PLOT_FCST_INC``: (Default: 3) + Forecast hour increment for the plotting task. For example, if the user wants plots for each forecast hour, they should set ``PLOT_FCST_INC: 1``. If the user only wants plots for some of the output (e.g., every 6 hours), they should set ``PLOT_FCST_INC: 6``. + +``PLOT_FCST_END``: (Default: "") + The last forecast hour for the plotting task. For example, if a forecast run for 24 hours, and the user wants plots for each available hour of forecast output, they should set ``PLOT_FCST_END: 24``. If the user only wants plots from the first 12 hours of the forecast, the "last forecast hour" should be 12. + +``PLOT_DOMAINS``: (Default: ["conus"]) + Domains to plot. Currently supported options are ["conus"], ["regional"], or both (i.e., ["conus", "regional"]). + +Global Configuration Parameters +=================================== + +Non-default parameters for the miscellaneous tasks are set in the ``global:`` section of the ``config.yaml`` file. + +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`). :numref:`Section %s ` includes further instructions on how to do this. + +``USE_CRTM``: (Default: false) + Flag that defines whether external :term:`CRTM` coefficient files have been staged by the user in order to output synthetic satellite products available within the :term:`UPP`. If this is set to true, then the workflow will check for these files in the directory ``CRTM_DIR``. Otherwise, it is assumed that no satellite fields are being requested in the UPP configuration. Valid values: ``True`` | ``False`` + +``CRTM_DIR``: (Default: "") + This is the path to the top CRTM fix file directory. This is only used if ``USE_CRTM`` is set to true. + + +Ensemble Model Parameters +----------------------------- + +Set parameters associated with running ensembles. + +``DO_ENSEMBLE``: (Default: false) + Flag that determines whether to run a set of ensemble forecasts (for each set of specified cycles). If this is set to true, ``NUM_ENS_MEMBERS`` forecasts are run for each cycle, each with a different set of stochastic seed values. When false, a single forecast is run for each cycle. Valid values: ``True`` | ``False`` + +``NUM_ENS_MEMBERS``: (Default: 1) + The number of ensemble members to run if ``DO_ENSEMBLE`` is set to true. This variable also controls the naming of the ensemble member directories. For example, if ``NUM_ENS_MEMBERS`` is set to 8, the member directories will be named *mem1, mem2, ..., mem8*. This variable is not used unless ``DO_ENSEMBLE`` is set to true. + +.. _stochastic-physics: + +Stochastic Physics Parameters +---------------------------------- + +Set default ad-hoc stochastic physics options. For the most updated and detailed documentation of these parameters, see the `UFS Stochastic Physics Documentation `__. + +``NEW_LSCALE``: (Default: true) + Use correct formula for converting a spatial legnth scale into spectral space. + +Specific Humidity (SHUM) Perturbation Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``DO_SHUM``: (Default: false) + Flag to turn Specific Humidity (SHUM) perturbations on or off. SHUM perturbations multiply the low-level specific humidity by a small random number at each time-step. The SHUM scheme attempts to address missing physics phenomena (e.g., cold pools, gust fronts) most active in convective regions. Valid values: ``True`` | ``False`` + +``ISEED_SHUM``: (Default: 2) + Seed for setting the SHUM random number sequence. + +``SHUM_MAG``: (Default: 0.006) + Amplitudes of random patterns. Corresponds to the variable ``shum`` in ``input.nml``. + +``SHUM_LSCALE``: (Default: 150000) + Decorrelation spatial scale in meters. + +``SHUM_TSCALE``: (Default: 21600) + Decorrelation timescale in seconds. Corresponds to the variable ``shum_tau`` in ``input.nml``. + +``SHUM_INT``: (Default: 3600) + Interval in seconds to update random pattern (optional). Perturbations still get applied at every time-step. Corresponds to the variable ``shumint`` in ``input.nml``. + +.. _SPPT: + +Stochastically Perturbed Physics Tendencies (SPPT) Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SPPT perturbs full physics tendencies *after* the call to the physics suite, unlike :ref:`SPP ` (below), which perturbs specific tuning parameters within a physics scheme. + +``DO_SPPT``: (Default: false) + Flag to turn Stochastically Perturbed Physics Tendencies (SPPT) on or off. SPPT multiplies the physics tendencies by a random number between 0 and 2 before updating the model state. This addresses error in the physics parameterizations (either missing physics or unresolved subgrid processes). It is most active in the boundary layer and convective regions. Valid values: ``True`` | ``False`` + +``ISEED_SPPT``: (Default: 1) + Seed for setting the SPPT random number sequence. + +``SPPT_MAG``: (Default: 0.7) + Amplitude of random patterns. Corresponds to the variable ``sppt`` in ``input.nml``. + +``SPPT_LOGIT``: (Default: true) + Limits the SPPT perturbations to between 0 and 2. Should be "TRUE"; otherwise the model will crash. + +``SPPT_LSCALE``: (Default: 150000) + Decorrelation spatial scale in meters. + +``SPPT_TSCALE``: (Default: 21600) + Decorrelation timescale in seconds. Corresponds to the variable ``sppt_tau`` in ``input.nml``. + +``SPPT_INT``: (Default: 3600) + Interval in seconds to update random pattern (optional parameter). Perturbations still get applied at every time-step. Corresponds to the variable ``spptint`` in ``input.nml``. + +``SPPT_SFCLIMIT``: (Default: true) + When true, tapers the SPPT perturbations to zero at the model's lowest level, which reduces model crashes. + +``USE_ZMTNBLCK``: (Default: false) + When true, do not apply perturbations below the dividing streamline that is diagnosed by the gravity wave drag, mountain blocking scheme. Valid values: ``True`` | ``False`` + + +Stochastic Kinetic Energy Backscatter (SKEB) Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``DO_SKEB``: (Default: false) + Flag to turn Stochastic Kinetic Energy Backscatter (SKEB) on or off. SKEB adds wind perturbations to the model state. Perturbations are random in space/time, but amplitude is determined by a smoothed dissipation estimate provided by the :term:`dynamical core`. SKEB addresses errors in the dynamics more active in the mid-latitudes. Valid values: ``True`` | ``False`` + +``ISEED_SKEB``: (Default: 3) + Seed for setting the SHUM random number sequence. + +``SKEB_MAG``: (Default: 0.5) + Amplitude of random patterns. Corresponds to the variable ``skeb`` in ``input.nml``. + +``SKEB_LSCALE``: (Default: 150000) + Decorrelation spatial scale in meters. + +``SKEB_TSCALE``: (Default: 21600) + Decorrelation timescale in seconds. Corresponds to the variable ``skeb_tau`` in ``input.nml``. + +``SKEB_INT``: (Default: 3600) + Interval in seconds to update random pattern (optional). Perturbations still get applied every time-step. Corresponds to the variable ``skebint`` in ``input.nml``. + +``SKEBNORM``: (Default: 1) + Patterns: + * 0-random pattern is stream function + * 1-pattern is K.E. norm + * 2-pattern is vorticity + +``SKEB_VDOF``: (Default: 10) + The number of degrees of freedom in the vertical direction for the SKEB random pattern. + + +.. _SPP: + +Parameters for Stochastically Perturbed Parameterizations (SPP) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SPP perturbs specific tuning parameters within a physics :term:`parameterization ` (unlike :ref:`SPPT `, which multiplies overall physics tendencies by a random perturbation field *after* the call to the physics suite). Patterns evolve and are applied at each time step. Each SPP option is an array, applicable (in order) to the :term:`RAP`/:term:`HRRR`-based parameterization listed in ``SPP_VAR_LIST``. Enter each value of the array in ``config.yaml`` as shown below without commas or single quotes (e.g., ``SPP_VAR_LIST: [ "pbl" "sfc" "mp" "rad" "gwd" ]`` ). Both commas and single quotes will be added by Jinja when creating the namelist. + +.. note:: + SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which :term:`SDF` is chosen when turning this option on. Of the four supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. + +``DO_SPP``: (Default: false) + Flag to turn SPP on or off. SPP perturbs parameters or variables with unknown or uncertain magnitudes within the physics code based on ranges provided by physics experts. Valid values: ``True`` | ``False`` + +``ISEED_SPP``: (Default: [ 4, 5, 6, 7, 8 ] ) + Seed for setting the random number sequence for the perturbation pattern. + +``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"`` | ``"mp"`` + +``SPP_MAG_LIST``: (Default: [ 0.2, 0.2, 0.75, 0.2, 0.2 ] ) + SPP perturbation magnitudes used in each parameterization. Corresponds to the variable ``spp_prt_list`` in ``input.nml`` + +``SPP_LSCALE``: (Default: [ 150000.0, 150000.0, 150000.0, 150000.0, 150000.0 ] ) + Decorrelation spatial scales in meters. + +``SPP_TSCALE``: (Default: [ 21600.0, 21600.0, 21600.0, 21600.0, 21600.0 ] ) + Decorrelation timescales in seconds. Corresponds to the variable ``spp_tau`` in ``input.nml``. + +``SPP_SIGTOP1``: (Default: [ 0.1, 0.1, 0.1, 0.1, 0.1 ] ) + Controls vertical tapering of perturbations at the tropopause and corresponds to the lower sigma level at which to taper perturbations to zero. + +``SPP_SIGTOP2``: (Default: [ 0.025, 0.025, 0.025, 0.025, 0.025 ] ) + Controls vertical tapering of perturbations at the tropopause and corresponds to the upper sigma level at which to taper perturbations to zero. + +``SPP_STDDEV_CUTOFF``: (Default: [ 1.5, 1.5, 2.5, 1.5, 1.5 ] ) + Limit for possible perturbation values in standard deviations from the mean. + + +Land Surface Model (LSM) SPP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Land surface perturbations can be applied to land model parameters and land model prognostic variables. The LSM scheme is intended to address errors in the land model and land-atmosphere interactions. LSM perturbations include soil moisture content (SMC) (volume fraction), vegetation fraction (VGF), albedo (ALB), salinity (SAL), emissivity (EMI), surface roughness (ZOL) (in cm), and soil temperature (STC). Perturbations to soil moisture content (SMC) are only applied at the first time step. Only five perturbations at a time can be applied currently, but all seven are shown below. In addition, only one unique *iseed* value is allowed at the moment, and it is used for each pattern. + +The parameters below turn on SPP in Noah or RUC LSM (support for Noah MP is in progress). Please be aware of the :term:`SDF` that you choose if you wish to turn on Land Surface Model (LSM) SPP. SPP in LSM schemes is handled in the ``&nam_sfcperts`` namelist block instead of in ``&nam_sppperts``, where all other SPP is implemented. + +``DO_LSM_SPP``: (Default: false) + Turns on Land Surface Model (LSM) Stochastic Physics Parameterizations (SPP). When true, sets ``lndp_type=2``, which applies land perturbations to the selected paramaters using a newer scheme designed for data assimilation (DA) ensemble spread. LSM SPP perturbs uncertain land surface fields ("smc" "vgf" "alb" "sal" "emi" "zol" "stc") based on recommendations from physics experts. Valid values: ``True`` | ``False`` + +``LSM_SPP_TSCALE``: (Default: [ 21600, 21600, 21600, 21600, 21600, 21600, 21600 ] ) + Decorrelation timescales in seconds. + +``LSM_SPP_LSCALE``: (Default: [ 150000, 150000, 150000, 150000, 150000, 150000, 150000 ] ) + Decorrelation spatial scales in meters. + +``ISEED_LSM_SPP``: (Default: [ 9 ] ) + Seed to initialize the random perturbation pattern. + +``LSM_SPP_VAR_LIST``: (Default: [ "smc", "vgf", "alb", "sal", "emi", "zol", "stc" ] ) + Indicates which LSM variables to perturb. + +``LSM_SPP_MAG_LIST``: (Default: [ 0.017, 0.001, 0.001, 0.001, 0.001, 0.001, 0.2 ] ) + Sets the maximum random pattern amplitude for each of the LSM perturbations. + +.. _HaloBlend: + +Halo Blend Parameter +------------------------ +``HALO_BLEND``: (Default: 10) + Number of cells to use for "blending" the external solution (obtained from the :term:`LBCs`) with the internal solution from the FV3LAM :term:`dycore`. Specifically, it refers to the number of rows into the computational domain that should be blended with the LBCs. Cells at which blending occurs are all within the boundary of the native grid; they don't involve the 4 cells outside the boundary where the LBCs are specified (which is a different :term:`halo`). Blending is necessary to smooth out waves generated due to mismatch between the external and internal solutions. To shut :term:`halo` blending off, set this to zero. + diff --git a/docs/UsersGuide/source/CustomizingTheWorkflow/DefineWorkflow.rst b/docs/UsersGuide/source/CustomizingTheWorkflow/DefineWorkflow.rst new file mode 100644 index 0000000000..4ea8f7052d --- /dev/null +++ b/docs/UsersGuide/source/CustomizingTheWorkflow/DefineWorkflow.rst @@ -0,0 +1,241 @@ +.. _DefineWorkflow: + +============================= +Defining an SRW App Workflow +============================= + +Many predefined workflows with optional variants exist within the Short-Range Weather Application, but the Application also includes the ability to define a new workflow from scratch. This functionality allows users to add tasks to the workflow to meet their scientific exploration needs. + +Rocoto is the primary workflow manager software used by the UFS SRW App. Rocoto workflows are defined in an XML file (``FV3LAM_wflow.xml``) based on parameters set during experiment generation. This section explains how the Rocoto XML is built using a Jinja2 template (`Jinja docs here `__) and structured YAML files. The YAML follows the requirements in the `Rocoto documentation `__ with a few exceptions or additions outlined in this documentation. + +The Jinja2 Template +=================== + +In previous versions of the SRW Application, the Jinja2 template to create the Rocoto XML was tightly coupled to specific configuration settings of the SRW App. It was built from a limited, pre-defined set of specific tasks, defining switches for those tasks to be included or not in the rendered XML. + +Now, the Jinja2 template is entirely agnostic to SRW Application decisions and has been developed to wrap the features of Rocoto in an extensible, configurable format. + + +The ``rocoto`` section of ``config.yaml`` +========================================== +The structured YAML file that defines the Rocoto XML is meant to reflect the sections required by any Rocoto XML. That structure looks like this, with some example values filled in: + +.. code-block:: console + + rocoto: + attrs: + realtime: F + scheduler: slurm + cyclethrottle: 5 + corethrottle: + taskthrottle: + cycledefs: + groupname: + - !startstopfreq ['2022102000', ‘2023102018’, ‘06:00:00’] + groupname2: + - !startstopfreq ['2022102000', ‘2023102018’, ‘24:00:00’] + - !startstopfreq ['2022102006', ‘2023102018’, ‘24:00:00’] + entities: + foo: 1 + bar: “/some/path” + log: "" + tasks: + taskgroups: '{{ ["parm/wflow/prep.yaml", "parm/wflow/coldstart.yaml", "parm/wflow/post.yaml"]|include }}' + task_*: + metatask_*: + +Under the Rocoto section, several subentries are required. They are described here using similar language as in the Rocoto documentation. + +``attrs``: Any of the attributes to the ``workflow`` tag in Rocoto. This is meant to contain a nested dictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. + +``cycledefs``: A dictionary in which each key defines a group name for a ``cycledef`` tag; the key’s value is a list of acceptable ``cycledef`` formatted strings. The PyYAML constructor ``!startstopfreq`` has been included here to help with the automated construction of a tag of that nature. The preferred option for the SRW App is to use the “start, stop, step” method. + +``entities``: A dictionary in which each key defines the name of a Rocoto entity and its value. These variables are referenceable throughout the workflow with the ``&foo;`` notation. + +``log``: The path to the log file. This corresponds to the ```` tag. + +``tasks``: This section is where the defined tasks and metatasks are created. This is the main portion of the workflow that will most commonly differ from experiment to experiment with different configurations. + +In addition to the structured YAML itself, the SRW App enables additional functionality when defining a YAML file. Often, PyYAML features are introduced and documented `here `__. In the above example, the ``!startstopfreq`` is an example of a PyYAML constructor. Supported constructors will be outlined :ref:`below `. There are also examples of using PyYAML anchors and aliases in the definition of groups of tasks in the SRW App. Please see `this documentation `__ for the behavior of PyYAML anchors and aliases. + +The use of Jinja2 templates inside the values of entries allows for the reference to other keys, mathematical operations, Jinja2 control structures, and the use of user-defined filters. Here, the ``include`` filter in the ``taskgroups`` entry is a user-defined filter. The supported filters are described in a section :ref:`below `. + +.. _tasks: + +The ``tasks`` Subsection +======================== + +``taskgroups``: This entry is not a standard Rocoto entry. It defines a set of files that will be included to build a workflow from predefined groups of tasks. The supported groups are included under ``parm/wflow`` for the SRW App, but the paths can point to any location on your local disk. The resulting order of the tasks will be in the same order as defined in this list. The syntax for the “include” is included as a Jinja2 filter. + +``task_*``: This is a section header to add a task. The task name will be whatever the section key has defined after the first underscore. For example, ``task_run_fcst`` will be named ``run_fcst`` in the resulting workflow. More information about defining a task is included :ref:`below `. + +``metatask_*``: This is a section header to add a metatask. The metatask name will be whatever the section key has defined after the first underscore. For example ``metatask_run_ensemble`` will be named ``run_ensemble`` in the resulting workflow. More information about defining a metatask is included :ref:`below `. + +.. _defining_tasks: + +Defining a Task +=============== +Each task supports any of the tags that are defined in the Rocoto documentation. Here’s an example of a task: + +.. code-block:: console + + task_make_grid: + account: '&ACCOUNT;' + command: '&LOAD_MODULES_RUN_TASK_FP; "make_grid" + attrs: + cycledefs: at_start + maxtries: '2' + envars: &default_envars + GLOBAL_VAR_DEFNS_FP: '&GLOBAL_VAR_DEFNS_FP;' + USHdir: '&USHdir;' + PDY: !cycstr "@Y@m@d" + cyc: !cycstr "@H" + subcyc: !cycstr "@M" + LOGDIR: !cycstr "&LOGDIR;" + nprocs: '{{ parent.nnodes * parent.ppn }}' + native: '{{ platform.SCHED_NATIVE_CMD }}' + nodes: '{{ nnodes }}:ppn={{ ppn }}' + nnodes: 1 + nodesize: "&NCORES_PER_NODE;" + ppn: 24 + partition: '{% if platform.get("PARTITION_DEFAULT") %}&PARTITION_DEFAULT;{% else %}None{% endif %}' + queue: '&QUEUE_DEFAULT;' + walltime: 00:20:00 + dependency: + + +The following sections are constructs of the interface, while all others are direct translations to tags available in Rocoto. Any tag that allows for attributes to the XML tag will take an ``attrs`` nested dictionary entry. + +``attrs``: Any of the attributes to the task tag in Rocoto. This is meant to be a subdictionary defining any of the Rocoto-supported attributes, where the key is the name of the attribute, and the value is what Rocoto expects. Attributes might include any combination of the following: cycledefs, maxtries, throttle, or final. + +``envars``: A dictionary of keys that map to variable names that will be exported for the job. These will show up as the set of ```` tags in the XML. The value will be the value of the defined variable when it is exported. + + +If the ``command`` entry is not provided, the task won’t show up in the resulting workflow. + +Defining Dependencies +===================== + +The dependency entry will be an arbitrarily deep nested dictionary of key, value pairs. Each level represents entries that must come below it in priority. This is especially relevant for logic files. If an “and” tag must apply to multiple dependencies, those dependencies are all included as a nested dictionary of dependencies. + +Because we are representing these entries as a dictionary, which requires hashable keys (no repeats at the same level), some tags may need to be differentiated where XML may not differentiate at all. In these instances, it is best practice to name them something descriptive. For example, you might have multiple “or” dependencies at the same level that could be named “or_files_exist” and “or_task_ran”. This style can be adopted whether or not differentiation is needed. + +The ``text`` entry on some dependencies is for those dependency tags that need the information to come between two flags, as in a data dependency. + +Otherwise, all dependencies follow the same naming conventions as defined in Rocoto with ``attrs`` dictionaries included to define any of the tag attributes that may be accepted by Rocoto. + +Here is an example of a complex dependency that relies on logic, task dependencies, and data dependencies: + +.. code-block:: console + + dependency: + and: + or_get_obs: # Ensure get_obs task is complete if it's turned on + not: + taskvalid: + attrs: + task: get_obs_mrms + and: + taskvalid: + attrs: + task: get_obs_mrms + taskdep: + attrs: + task: get_obs_mrms + or_do_post: &post_files_exist + and_run_post: # If post was meant to run, wait on the whole post metatask + taskvalid: + attrs: + task: run_post_mem#mem#_f000 + metataskdep: + attrs: + metatask: run_ens_post + and_inline_post: # If inline post ran, wait on the forecast task to complete + not: + taskvalid: + attrs: + task: run_post_mem#mem#_f000 + taskdep: + attrs: + task: run_fcst_mem#mem# + +Notice the use of a PyYAML anchor under the ``or_do_post`` section. If other tasks need this same section of the dependency, it can be included like this to reduce the extensive replication: + +.. code-block:: console + + dependency: + or_do_post: + <<: *post_files_exist + datadep: + text: "&CCPA_OBS_DIR;" + +The use of ``#mem#`` here is a Rocoto construct that identifies this task as a part of a metatask that is looping over ensemble members (more on metatasks below). + +.. _defining_metatasks: + +Defining a Metatask +=================== + +A metatask groups together similar tasks and allows for the definition over entries defined by ``var`` tags. To define a metatask, the ``var`` entry with a nested dictionary of keys representing the names of the metatask variables and values indicating the list of values for each iteration is required. + +Multiple var entries may be included, but each entry must have the same number of items. + +The metatask section must include at least one entry defining another metatask or a task. + +Here’s an example of a metatask section (without the task definition): + +.. code-block:: console + + metatask_run_ensemble: + var: + mem: '{% if global.DO_ENSEMBLE %}{%- for m in range(1, global.NUM_ENS_MEMBERS+1) -%}{{ "%03d "%m }}{%- endfor -%} {% else %}{{ "000"|string }}{% endif %}' + task_make_ics_mem#mem#: + +This metatask will be named “run_ensemble” and will loop over all ensemble members or just the deterministic member (“000”) if no ensemble of forecasts is meant to run. + +The ``var`` section defines the metatask variables, here only “mem”. The name of the task represents that variable using ``#mem#`` to indicate that the resulting task name might be ``make_ics_mem000`` if only a deterministic forecast is configured to run. + +When the task or the metatask is referenced in a dependency later on, do not include the ``task_`` or ``metatask_`` portions of the name. The reference to ``#mem#`` can be included if the dependency is included in a metatask that defines the variable, e.g., ``make_ics_mem#mem#``. Otherwise, you can reference a task that includes the value of the metatask var, e.g., ``make_ics_mem000``. More on this distinction is included in the Rocoto documentation. + +.. _J2filters: + +SRW-Defined Jinja2 Filters Used by YAML Interface +================================================= + +``include()`` – given a list of files to other YAML files, load their contents as a nested dictionary under the entry. + +.. _YAMLconstructors: + +SRW-Defined PyYAML Constructors Used by YAML Interface +====================================================== + +``!cycstr`` - Returns a ```` element for use in Rocoto. It does not support the “offset” attribute. + +``!startstopfreq`` – Creates a Rocoto XML-formatted string given a start, stop, and freq value in a list. + +Order of Precedence +=================== +There is a specific order of precedence imposed when the SRW App loads configuration files. + +#. Load ``config_defaults.yaml`` file. +#. Load the user’s ``config.yaml`` file. +#. Load the ``default_workflow.yaml`` file. + + * At this point, all anchors and references will be resolved. + * All PyYAML constructors will also be called for the data provided in that entry. +#. Call ``update_dict`` function to remove any null entries from default tasks using the PyYAML anchors. +#. Load all files from the ``taskgroups:`` entry from the user’s config or from the default if not overridden. This is achieved with a call to the ``extend_yaml()`` function. +#. Add the contents of the files to the ``task:`` section. +#. Update the existing workflow configuration with any user-specified entries (removing the ones that are null entries). +#. Add a ``jobname:`` entry to every task in the workflow definition section. +#. Incorporate other default configuration settings from machine files, constants, etc. into the default configuration dictionary in memory. +#. Apply all user settings last to take highest precedence. +#. Call ``extend_yaml()`` to render templates that are available. + NOTE: This is the one that is likely to trip up any settings that ``setup.py`` will make. References to other defaults that get changed during the course of validation may be rendered here earlier than desired. + +At this point, validation and updates for many other configuration settings will be made for a variety of sections. Once complete, ``extend_yaml()`` is called repeatedly, stopping only when all possible Jinja2-templated values have been rendered. + +Just before the ``rocoto:`` section is written to its own file in the experiment directory, ``clean_rocoto_dict()`` is called on that section to remove invalid dictionaries, i.e., metatasks with no tasks, tasks with no associated commands, etc. + +The ``rocoto:`` section is not included in the ``var_defns.sh`` since that file is used primarily to store settings needed at run-time. + diff --git a/docs/UsersGuide/source/CustomizingTheWorkflow/InputOutputFiles.rst b/docs/UsersGuide/source/CustomizingTheWorkflow/InputOutputFiles.rst new file mode 100644 index 0000000000..e179219e7a --- /dev/null +++ b/docs/UsersGuide/source/CustomizingTheWorkflow/InputOutputFiles.rst @@ -0,0 +1,396 @@ +.. _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. 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 required files, see :numref:`Section %s `. + +.. _Input: + +Input Files +=========== +The SRW Application requires numerous input files to run: static datasets (fix files +containing climatological information, terrain, and land use data), initial and boundary +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 from the `SRW App Data Bucket `__, + * Pulled from the NOAA High Performance Storage System (:term:`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 generates the SRW App workflow as described in :numref:`Section %s `, 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 `Technical Documentation `__ and `Scientific Documentation `__. + +UFS Weather Model +----------------- +The input files for the UFS Weather Model include both static (fixed) files and grid- and date-specific files (terrain, initial conditions, boundary conditions, etc). The static fix(ed) 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 their machine. (See :numref:`Section %s ` for instructions on staging the data on a new machine and :numref:`Section %s ` for data locations on Level 1 machines.) The workflow scripts link the static, grid, and date-specific files to 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) +---------------------------- +Documentation for the UPP input files can be found in the `UPP User's Guide +`__. + +.. _WorkflowTemplates: + +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 SRW 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.yaml`` file are assigned. + +List of Template Files +^^^^^^^^^^^^^^^^^^^^^^^^ +The template files for the SRW Application are located in the ``parm`` directory +and are shown in :numref:`Table %s `. + +.. _TemplateFiles: + +.. list-table:: Template Files for the SRW App Workflow + :widths: 20 50 + :header-rows: 1 + + * - 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 :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 :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 ``generate_FV3LAM_wflow.py``. + * - input.nml.FV3 + - Namelist file for the Weather Model. + * - model_configure + - Settings and configurations for the :term:`NUOPC`/:term:`ESMF` main component. + * - nems.configure + - :term:`NEMS` (NOAA Environmental Modeling System) configuration file. No need to change because the usual SRW App configuration is atmosphere-only, and UFS-AQM settings handle any configuration/templating required for that configuration. + * - 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 ``diag_table.[CCPP]``, ``field_table.[CCPP]``, ``input.nml.FV3``, ``model_configure``, and ``nems.configure`` can be found in the `UFS Weather Model User's Guide `__, while information on ``regional_grid.nml`` options can be found in the `UFS_UTILS Technical Documentation `__. + +Migratory Route of the Input Files in the Workflow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:numref:`Figure %s ` shows how the input files in the template directory (``ufs-srweather-app/parm``) 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 SRW App 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 ``parm`` directory. Finally, these files are updated with the variables specified in ``var_defn.sh``. + +.. _MigratoryRoute: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/SRW_wflow_input_path.png + :alt: Flowchart showing how information from the physics suite travels from the configuration file to the setup file to the workflow generation script to the run forecast ex-script. As this information is fed from one file to the next, file paths and variables required for workflow execution are set. + + *Migratory Route of Input Files* + +.. _OutputFiles: + +Output Files +============== + +Output files from each workflow task are written to a subdirectory within the experiment directory (``$EXPTDIR/YYYYMMDDHH``), named based on the settings in ``config.yaml``. These files may then be used as input to future tasks. + +Initial and boundary condition files +------------------------------------ +The external model data used by ``chgres_cube`` (as part of the pre-processing utilities) are located +in the experiment directory under ``$EXPTDIR/YYYYMMDDHH/EXTRN_MDL_NAME/{for_ICS/for_LBCS}``. + +.. COMMENT: This is confusing bc it sounds like these are input files, not output files. Does chgres_cube output these? In which tasks? + +Pre-processing (UFS_UTILS) +-------------------------- +The files output by the other pre-processing utilities reside in the ``INPUT`` directory under the +experiment directory (``$EXPTDIR/YYYYMMDDHH/INPUT``) and consist of the following: + +* ``C403_grid.tile7.halo3.nc`` +* ``gfs_bndy.tile7.HHH.nc`` +* ``gfs_ctrl.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 User's Guide +`__. ``gfs_bndy.tile7.HHH.nc`` refers to a series of IC/LBC files where ``HHH`` is the 3-digit hour of the forecast. + +UFS Weather Model +------------------ +As stated in :numref:`Section %s `, the workflow can be run in "community" mode or "nco" mode, which determines the location and names of the output files. Weather Model output files can be in :term:`netCDF` or :term:`NEMSIO` format. The output file format is set in the ``model_configure`` file using the ``output_file`` variable (see :ref:`UFS WM Documentation `). At this time, due to limitations in the post-processing component, only netCDF output is recommended as output for the SRW Application. + +.. note:: + 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`` + +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 +`__. + +Unified Post Processor (UPP) +---------------------------- +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 ``$EXPTDIR/YYYYMMDDHH/postprd`` and have the naming convention (file->linked to): + +* ``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.yaml`` settings. + +.. _ModifyUPPOutput: + +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/sorc/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 instructions in the `UPP User's Guide `__ to make modifications to the ``fv3lam.xml`` file and to remake the flat text file, called ``postxconfig-NT-fv3lam.txt`` (default), that the UPP reads. + +After creating the new flat text file to reflect the changes, users will need to modify their ``config.yaml`` to point the workflow to the new text file. In ``config.yaml``, set the following: + +.. code-block:: console + + USE_CUSTOM_POST_CONFIG_FILE: true + CUSTOM_POST_CONFIG_FP: /path/to/custom/postxconfig-NT-fv3lam.txt + +which tells the workflow to use the custom file located in the user-defined path. The path should include the filename. If ``USE_CUSTOM_POST_CONFIG_FILE`` is set to true, but the file path is not found, then an error will occur when trying to generate the SRW Application workflow. + +After successfully generating the workflow, users may run/monitor their experiment 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 (``postxconfig-NT-fv3lam.txt``) has already been set up to output satellite products using the process described above in :numref:`Section %s`. + +Download and unpack the external files: + +.. code-block:: console + + mkdir crtm && cd crtm + wget https://github.com/NOAA-EMC/UPP/releases/download/upp_v11.0.0/fix.tar.gz + tar -xzf fix.tar.gz + +Modify the ``config.yaml`` 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 +================================== +A set of input files, including static (fix) data and raw initial and lateral boundary conditions (:term:`IC/LBCs`), 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. Therefore, users on these systems do not need to stage the fixed files manually because they have been prestaged, and the paths are set in ``ush/setup.sh``. Users on Level 3 & 4 systems can find the most recent SRW App release data in the `UFS SRW Application Data Bucket `__ by clicking on `Browse Bucket `__. + +.. _StaticFixFiles: + +Static Files +-------------- + +Static files are available in the `"fix" directory `__ of the SRW App Data Bucket. Users can download the full set of fix files as a tar file: + +.. code-block:: console + + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/fix_data.tgz + tar -xzf fix_data.tgz + +Alternatively, users can download the static files individually from the `"fix" directory `__ of the SRW Data Bucket using the ``wget`` command for each required file. A list of ``wget`` commands with links is provided :ref:`here ` for the release v2.1.0 fix file data. Users will need to create an appropriate directory structure for the files when downloading them individually. The best solution is to download the files into directories that mirror the structure of the `Data Bucket `__. + +.. COMMENT: Update release file list above for next SRW release. + +The environment variables ``FIXgsm``, ``FIXorg``, and ``FIXsfc`` 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.yaml``. Add the following code to the ``task_run_fcst:`` section of the ``config.yaml`` file, and alter the variable paths accordingly: + +.. code-block:: console + + FIXgsm: /path/to/fix/fix_am + FIXorg: /path/to/fix/fix_orog + FIXsfc: /path/to/fix/sfc_climo/ + +.. _InitialConditions: + +Initial 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, GEFS, GDAS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. + +To download the model input data for the 12-hour "out-of-the-box" experiment configuration in ``config.community.yaml`` file, run: + +.. code-block:: console + + wget https://noaa-ufs-srw-pds.s3.amazonaws.com/current_srw_release_data/gst_data.tgz + tar -xzf gst_data.tgz + +To download data for different dates, model types, and formats, users can explore the ``input_model_data`` section of the data bucket and replace the links above with ones that fetch their desired data. + +.. _ICS-LBCS: + +Initial and Lateral Boundary Condition Organization +---------------------------------------------------- + +The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBCS`` must be set in the appropriate sections of the ``config.yaml`` file: + +.. code-block:: console + + task_get_extrn_ics: + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_SOURCE_BASEDIR_ICS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH + task_get_extrn_lbcs: + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH + +The two ``EXTRN_MDL_SOURCE_BASEDIR_*CS`` variables describe where the :term:`IC ` and :term:`LBC ` file directories are located, respectively. For ease of reusing ``config.yaml`` across experiments, it is recommended that users set up the raw :term:`IC/LBC ` file paths to include the model name (e.g., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path/to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow. + +When files are pulled from NOAA :term:`HPSS` (rather than downloaded from the data bucket), the naming convention looks something like: + +* 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`` + +* GDAS (NETCDF): + + * ICs: ``gdas.t{cycle}z.atmf{fhr}.nc`` and ``gdas.t{cycle}z.sfcf{fhr}.nc``; + * LBCs: ``gdas.t{cycle}z.atmf{fhr}.nc`` + +* 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 2- or 3-digit nth hour of the forecast (3-digits for FV3GFS/GDAS data and 2 digits for RAP/HRRR data). + +For example, a forecast using FV3GFS GRIB2 data that starts at 18h00 UTC would have a {cycle} value of 18, which is the 000th forecast hour. The LBCS file for 21h00 UTC would be named ``gfs.t18z.pgrb2.0p25.f003``. + +In some cases, it may be necessary to specify values for ``EXTRN_MDL_FILES_*CS`` variables. This is often the case with HRRR and RAP data. An example ``config.yaml`` excerpt using HRRR and RAP data appears below: + +.. code-block:: console + + task_get_extrn_ics: + EXTRN_MDL_NAME_ICS: HRRR + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_FILES_ICS: + - '{yy}{jjj}{hh}00{fcst_hr:02d}00' + task_get_extrn_lbcs: + EXTRN_MDL_NAME_LBCS: RAP + LBC_SPEC_INTVL_HRS: 3 + USE_USER_STAGED_EXTRN_FILES: true + EXTRN_MDL_FILES_LBCS: + - '{yy}{jjj}{hh}00{fcst_hr:02d}00' + +Default Initial and Lateral Boundary Conditions +----------------------------------------------- + +The default initial and lateral boundary condition files are set to be a severe weather case from June 15, 2019 (20190615) at 18 UTC. FV3GFS GRIB2 files are the default model and file format. A tar file +(``gst_data.tgz``) containing the model data for this case is available in the `UFS SRW App Data Bucket `__. + +Running the App for Different Dates +----------------------------------- +If users want to run the SRW Application for dates other than June 15-16, 2019, they will need to modify the ``config.yaml`` settings, including the ``DATE_FIRST_CYCL`` and ``DATE_LAST_CYCL`` 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. + +Staging Initial Conditions Manually +----------------------------------- +If users want to run the SRW Application with raw model files for dates other than those that +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`` (which may be the same directory). The path to these variables can be set in the ``config.yaml`` file as shown :ref:`above `. 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: + +* GFS (GRIB2 or NEMSIO) - available for the last 10 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod/ +* GDAS (NETCDF) sfc files - available for the last 2 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod +* NAM - available for the last 8 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/nam/prod/ +* RAP - available for the last 2 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/rap/prod/ +* HRRR - available for the last 2 days + https://nomads.ncep.noaa.gov/pub/data/nccf/com/hrrr/prod/ + +AWS S3 Data Buckets: + +* GFS: https://registry.opendata.aws/noaa-gfs-bdp-pds/ +* GEFS: https://registry.opendata.aws/noaa-gefs/ +* GDAS: https://registry.opendata.aws/noaa-gfs-bdp-pds/ +* HRRR: https://registry.opendata.aws/noaa-hrrr-pds/ (necessary fields for initializing available for dates 2015 and newer) + +Google Cloud: + +* HRRR: https://console.cloud.google.com/marketplace/product/noaa-public/hrrr + +FTP Data Repository (data for SRW Release v1.0.0 & v1.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: + +* University of Utah HRRR archive: http://home.chpc.utah.edu/~u0553130/Brian_Blaylock/cgi-bin/hrrr_download.cgi +* NAM nest archive: https://www.ready.noaa.gov/archives.php +* NAM data older than 6 months can be requested through the Archive Information Request System: https://www.ncei.noaa.gov/has/HAS.FileAppRouter?datasetname=NAM218&subqueryby=STATION&applname=&outdest=FILE +* RAP isobaric data older than 6 months can be requested through the Archive Information Request System: https://www.ncei.noaa.gov/has/HAS.FileAppRouter?datasetname=RAP130&subqueryby=STATION&applname=&outdest=FILE + +Coexistence of Multiple Files for the Same Date +------------------------------------------------- +It is recommended that users have a separate directory for each file format if they choose to store files in multiple formats (e.g., GRIB2, NEMSIO, netCDF) for the same date. For example, the directory structure for a user storing GFS GRIB2 and NEMSIO files might resemble the following: + +.. code-block:: console + + /path/to/input_model_data/FV3GFS/grib2/YYYYMMDDHH + /path/to/input_model_data/FV3GFS/nemsio/YYYYMMDDHH + +Additionally, users must set the following environment variables if they plan to use GRIB2-formatted files for FV3GFS: + +.. code-block:: console + + FV3GFS_FILE_FMT_ICS: grib2 + FV3GFS_FILE_FMT_LBCS: grib2 + +This is ONLY necessary when using FV3GFS GRIB2 files. These settings may be removed when initializing from the default NEMSIO format for 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 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. + +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/CustomizingTheWorkflow/LAMGrids.rst b/docs/UsersGuide/source/CustomizingTheWorkflow/LAMGrids.rst new file mode 100644 index 0000000000..e4ddaa29b1 --- /dev/null +++ b/docs/UsersGuide/source/CustomizingTheWorkflow/LAMGrids.rst @@ -0,0 +1,204 @@ +.. _LAMGrids: + +================================================================================= +Limited Area Model (:term:`LAM`) Grids: Predefined and User-Generated Options +================================================================================= +In order to set up the workflow and generate an experiment with the SRW Application, the user +must choose between various predefined :term:`FV3`-:term:`LAM` grids or generate a user-defined grid. +At this time, full support is only provided to those using one of the four predefined +grids supported in the v2.1.0 release, but other predefined grids are available (see :numref:`Section %s ` for more detail). Preliminary information is also provided at the end of this chapter describing 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 SRW App v2.1.0 release includes four predefined limited area model (:term:`LAM`) grids. To select a supported predefined grid, the ``PREDEF_GRID_NAME`` variable within the ``task_run_fcst:`` section of the ``config.yaml`` script must be set to one of the following four options: + +* ``RRFS_CONUS_3km`` +* ``RRFS_CONUS_13km`` +* ``RRFS_CONUS_25km`` +* ``SUBCONUS_Ind_3km`` + +These four options are provided for flexibility related to compute resources and supported physics options. Other predefined grids are listed :ref:`here `. The high-resolution 3-km :term:`CONUS` grid generally requires more compute power and works well with three of the five 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 other supported physics suites: ``FV3_GFS_v16`` and ``FV3_RAP``. + +.. _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 | + | | | + | | FV3_RAP | + +-------------------+------------------+ + | RRFS_CONUS_25km | FV3_GFS_v16 | + | | | + | | FV3_RAP | + +-------------------+------------------+ + +In theory, it is possible to run any of the supported physics suites 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 (:term:`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 3-km 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 parameterizations. 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`` and ``FV3_RAP`` suites generally should *not* be used with the 3-km domain because the cumulus physics used in those physics suites is not configured to run at the 3-km resolution. + +.. _RRFS_CONUS_3km: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_3km.sphr.native_wrtcmp.png + :alt: Map of the continental United States 3 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. + + *The boundary of the RRFS_CONUS_3km computational grid (red) and corresponding write-component grid (blue).* + +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 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 the 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 (such as HRRR or RAP data) that has a resolution similar to that of the native FV3-LAM (predefined) grid. + + +Predefined SUBCONUS Grid Over Indianapolis +-------------------------------------------- + +.. _SUBCONUS_Ind_3km: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/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 the computational grid boundaries in blue. + + *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 :term:`CONUS` centered 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: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_13km.sphr.native_wrtcmp.png + :alt: Map of the continental United States 13 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. + + *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`` or ``FV3_RAP`` physics suites. These suites use 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 25-km and 13-km. + +Predefined 25-km Grid +------------------------ + +.. _RRFS_CONUS_25km: + +.. figure:: https://github.com/ufs-community/ufs-srweather-app/wiki/RRFS_CONUS_25km.sphr.native_wrtcmp.png + :alt: Map of the continental United States 25 kilometer domain. The computational grid boundaries appear in red and the write-component grid appears just inside the computational grid boundaries in blue. + + *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 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, 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 +out with the SRW App, more advanced users may wish to create their own predefined 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 (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 predefined 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. More information on the ESG grid is available `here `__. 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: + +#. 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/ush/valid_param_vals.yaml`` file. + +#. In ``ufs-srweather-app/ush/predef_grid_params.yaml``, add a stanza describing the parameters for NEW_GRID. An example of such a stanza is given :ref:`below `. For descriptions of the variables that need to be set, see Sections :numref:`%s ` and :numref:`%s `. + +To run a forecast experiment on NEW_GRID, start with a workflow configuration file for a successful experiment (e.g., ``config.community.yaml``, located in the ``ufs-srweather-app/ush`` subdirectory), and change the line for ``PREDEF_GRID_NAME`` in the ``task_run_fcst:`` section to ``NEW_GRID``: + +.. code-block:: console + + PREDEF_GRID_NAME: "NEW_GRID" + +Then, load the regional workflow python environment, specify the other experiment parameters in ``config.community.yaml``, and generate a new experiment/workflow using the ``generate_FV3LAM_wflow.py`` script (see :numref:`Chapter %s ` for details). + +Code Example +--------------- + +The following is an example of a code stanza for "NEW_GRID" to be added to ``predef_grid_params.yaml``: + +.. _NewGridExample: + +.. code-block:: console + + # + #--------------------------------------------------------------------- + # + # Stanza for NEW_GRID. This grid covers [description of the + # domain] with ~[size]-km cells. + # + #--------------------------------------------------------------------- + + "NEW_GRID": + + # The method used to generate the grid. This example is specifically for the "ESGgrid" method. + + GRID_GEN_METHOD: "ESGgrid" + + # ESGgrid parameters: + + ESGgrid_LON_CTR: -97.5 + ESGgrid_LAT_CTR: 38.5 + ESGgrid_DELX: 25000.0 + ESGgrid_DELY: 25000.0 + ESGgrid_NX: 200 + ESGgrid_NY: 112 + ESGgrid_PAZI: 0.0 + ESGgrid_WIDE_HALO_WIDTH: 6 + + # Forecast configuration parameters: + + DT_ATMOS: 40 + LAYOUT_X: 5 + LAYOUT_Y: 2 + BLOCKSIZE: 40 + + # Parameters for the write-component (aka "quilting") grid. + + QUILTING: + WRTCMP_write_groups: 1 + WRTCMP_write_tasks_per_group: 2 + WRTCMP_output_grid: "lambert_conformal" + WRTCMP_cen_lon: -97.5 + WRTCMP_cen_lat: 38.5 + WRTCMP_lon_lwr_left: -121.12455072 + WRTCMP_lat_lwr_left: 23.89394570 + + # Parameters required for the Lambert conformal grid mapping. + + WRTCMP_stdlat1: 38.5 + WRTCMP_stdlat2: 38.5 + WRTCMP_nx: 197 + WRTCMP_ny: 107 + WRTCMP_dx: 25000.0 + WRTCMP_dy: 25000.0 + +.. note:: + The process above explains how to create a new *predefined* grid, which can be used more than once. If a user prefers to create a custom grid for one-time use, the variables above can instead be specified in ``config.yaml``, and ``PREDEF_GRID_NAME`` can be set to a null string. In this case, it is not necessary to modify ``valid_param_vals.yaml`` or ``predef_grid_params.yaml``. Users can view an example configuration file for a custom grid `here `__. diff --git a/docs/UsersGuide/source/CustomizingTheWorkflow/TemplateVars.rst b/docs/UsersGuide/source/CustomizingTheWorkflow/TemplateVars.rst new file mode 100644 index 0000000000..f22d915a62 --- /dev/null +++ b/docs/UsersGuide/source/CustomizingTheWorkflow/TemplateVars.rst @@ -0,0 +1,77 @@ +.. _TemplateVars: + +====================== +Template Variables +====================== + +The SRW App's experiment configuration system supports the use of template variables +in ``config_defaults.yaml`` and ``config.yaml``. A template variable is an experiment configuration variable that contains references to values of other variables. +These references are **not** set to the values of the referenced variables (or "expanded") when the experiment's variable definitions file (``var_defns.sh``) is generated or sourced. +Instead, they are expanded and evaluated **at run time** when bash's +``eval`` command is used on the template. + +Generic Example +================== + +As an example, consider a hypothetical template variable named ``MY_CMD`` that is defined in ``config_defaults.yaml`` +(or redefined by the user in ``config.yaml``) as follows: + + .. code-block:: console + + MY_CMD: 'cd ${some_dir}' + +Here, ``some_dir`` may be another experiment variable defined in ``var_defns.sh`` or a +local variable defined in a script or function that will evaluate the template. +It is important to use single quotes on the right-hand side of the definition above; +otherwise, bash will try to evaluate ``${some_dir}`` when constructing ``var_defns.sh``, +which may result in an error and/or unexpected behavior (e.g., if ``${some_dir}`` +is not yet defined). The experiment generation system will define ``MY_CMD`` in +``var_defns.sh`` in exactly the same way as in ``config_defaults.yaml`` and/or +``config.yaml``, e.g., ``MY_CMD: 'cd ${some_dir}'``. Then the following code snippet +in a script or function will evaluate the contents of ``MY_CMD`` using a locally-set +value of ``some_dir``: + + .. code-block:: none + + ... + . var_defns.sh # Source the experiment's variable definition file (assuming + # it is in the current directory). This defines the MY_CMD + # template variable (in addition to other variables). + ... + some_dir="20200715" # Set the local variable some_dir. + ... + eval ${MY_CMD} # Use eval to evaluate the contents of MY_CMD. The value of + # some_dir specified in this file a few lines above is substituted + # for ${some_dir} in MY_CMD before MY_CMD is evaluated. + +Graphics Plotting Example +============================ + +When attempting to generate graphics plots from a forecast, users have the option to +produce difference plots from two experiments that are on the same domain and +available for the same cycle starting date/time and forecast hours. +To generate difference plots, users must use the template variable ``COMOUT_REF`` +to indicate where the :term:`GRIB2` files from post-processing are located. + +In *community* mode (i.e., when ``RUN_ENVIR: "community"``), this directory will +take the form ``/path/to/expt_dirs/expt_name/$PDY$cyc/postprd``, where ``$PDY`` refers +to the cycle date in YYYYMMDD format, and ``$cyc`` refers to the starting hour of the cycle. +(These variables are set in previous tasks based on the value of ``DATE_FIRST_CYCL``.) +Given two experiments, ``expt1`` and ``expt2``, users can generate difference plots by +setting ``COMOUT_REF`` in the ``expt2`` configuration file (``config.yaml``) as follows: + +.. code-block:: console + + COMOUT_REF: '${EXPT_BASEDIR}/expt1/${PDY}${cyc}/postprd' + +The ``expt2`` workflow already knows where to find its own post-processed output, so +``COMOUT_REF`` should point to post-processed output for the other experiment (``expt1``). + +In *nco* mode, this directory should be set to the location of the first experiment's +``COMOUT`` directory (``${COMOUT}`` in the example below) and end with ``${PDY}/${cyc}``. +For example: + +.. code-block:: console + + COMOUT_REF: '${COMOUT}/${PDY}/${cyc}/' + diff --git a/docs/UsersGuide/source/CustomizingTheWorkflow/index.rst b/docs/UsersGuide/source/CustomizingTheWorkflow/index.rst new file mode 100644 index 0000000000..680021f5cf --- /dev/null +++ b/docs/UsersGuide/source/CustomizingTheWorkflow/index.rst @@ -0,0 +1,12 @@ +Customizing the Workflow +=========================== + +.. toctree:: + :maxdepth: 3 + + ConfigWorkflow + InputOutputFiles + LAMGrids + DefineWorkflow + TemplateVars + From 4f6ae16fa08f3c28d8a2599e4c68b1c30d24e1ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cgspetro-NOAA=E2=80=9D?= Date: Wed, 30 Aug 2023 10:00:29 -0400 Subject: [PATCH 116/116] update link to ccpp sci docs --- docs/UsersGuide/source/BackgroundInfo/Introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst index ea8e697fe0..f4aa344fa7 100644 --- a/docs/UsersGuide/source/BackgroundInfo/Introduction.rst +++ b/docs/UsersGuide/source/BackgroundInfo/Introduction.rst @@ -114,7 +114,7 @@ A list of available component documentation is shown in :numref:`Table %s

    FK5!0ZMnGa=>q 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 D3a}}fQrkcMm}@-ryr50v#gbA zozj0St`EWg2JAjdfh&Zy*?~1iw=$1r`Y+kK_fipp+P^zhpP$Qvk_9}Je`AUN-0^Cf zZ|e8PIX!86mOx;gagp#yd+E@aYpkNw_)}*ySQp3Q-(#lEdG=NwN92E!^8Uuq3`qRy zKV^#6In{k-+bpao^4*T`rtLCabdPPmse5aGt{5=1!`Okoy^cK}#YWh>hL_}seMvZ# z_rZG!t}Y%*+J)|y(*O0A`?%0{{i=Bc#E-k-6VzG<)2nzBPE zBHhR=#;%~I0fp~`|FqlwLv8I-L)$55swU^uKfdSpdVXZ^z%BN!mw+Q)n0qF1)G|$b zY>#IfVageQZj+Xt8!>v>+N|3wj*&0+Sxc_m?Dk`xHSad1=I~AbH|`cLk|hp4*5(9q z&p)9HmNyC7DQXnWp+_ljZ{l)CNxq+!mHL#f;ObU!ILI8IIC(mC#QQVq@hoe?X#62! zQ@Eflp)gUxj)@RYm_u~w*fTauk+f~lyE}as zG<;ijHOQR2AOo__TFIR47gs)Fq94S2-u7zalgWG<-{k1v=j582ythqHPjD}jV(Ic{P^0>i|Y%Hyl$H7&V zP1DlUdoNK_F4@yogN3 z7@hOCBl>?J5+?+|dg|dG9l_kmZ*mGsu?vwo_9dd;Ha;(oO$6@--&k-ryNd17HF-Yk zqFrh0jwP|<+9X|RI`@wS)Q~SbJtm@#SDXLUJ98$K4rvFx}`_FUV#VKUDb=d|P zX_4YhT?P|3@5jrv8$YHG;dM}r1$Gm1mIN)7IY{Py0*}^sxtEuOd=mS6vw=AWVEOuY zo<^V8w>C&;5*x!|E;~Bc#lL>4{IAbf*+AG`{Y{(W z9}#l|epk7f8@qEvEkV+qX>4iIq^MS1`10Qa&j6C^rz(V)7L`EtT{eI%rr&w|U$K~f z5w~d2`=zQdJL|Inz`eWjr$9lrg}<{uOXLw0{zmlPr<9gCL0C_8XbQH6UH}&sv^2OV z253_r<{jeYPdd+zMTgE6plr6uN;T!#ioal65p6L*6yUyG-}u3}93ql+#rPYnBN4bP zhWG32ydVFiSjwQ4wWF?io^WOLH{F}dMDDx(2EFvXwg9(=sbnr6Ms8i$TO9=)fNXtl z8fivx)24CWj%|ba`ER6GL|gLJxTo5P!@kAUuVr9PkN{_g*2raWI);(hi6m2o&<-%v z==>v|{s+vVLDb^Lo_0BBtx#sYl3{9ozH zme@_|!d1kKomV{ndzJyv9U34=QR7{_cB}l8)m3evRLhW2rFyMA%Q&%;$xQt4D;CWw zUB23GK_x;FHe0Jv9>BzVOxAvW_=V(0riitfKHT@KR7nH$*F>~V3}tMl$``^o%hZ2JhDSKV$2_;+#^(S+&xC2gbh#8L_3=C#MX3S+h1zBkucGn4dm}JLAY3*!w%~uZTrAx#x12r&%OCJ;ldt9SWl+e9}&@ zU)nrkO(>!wL$6H^F%Ivne(!SVDV|H$t;d{>&iX!7enS*0R`LW z&L?QS`)(OWlx!o%3DcC4e1znvVbORW??dGu`r1ve60`0k*|y7Ew$LlHC{f1~j($?O zq!?8$QrES)G#)ac_1^jn$Ku)C$yE?~WR{___XrqiUFgBqsab z48x+qq>*@hlnZu{r^N;MV-3P-S5icH$;Xl6X;sp6e~Vv(zM>!ToR8l z5iztLxNIK916TgJFQ`%ROSNk3D~^rtAZ#a|pZhyyG;e4UCkZvkUkYs~TaxT+J1gp%Ch1E~a_IH!GANlkWFKL)wCOKf8 zWfroBHq(7bHcIiwJRi1++3udYxET9ufCaYRghaT=FYxG~D`s=bb$~#kYw%*LTLHtc zCe2CN6RT?(z=e$$tHSf<%Bsy(s(OGD$GR}~(Z*?6ojtyI-|x{tkUPhdWo#Dg@v(2B5<~_Y^S#?+7@|^d^)txD-E?Yfu4w z^$CFP7yf1ko^EgQ+j~Wu^=uKf0C@CdfUffJMEE(A%&f}ob6RJ2XO6P_68}qG&Hu8joB6e-SlspmSw#2`bZ;$`g-7bL1%jOB zM&jRL6#{g!U;5%)tdVEznPi3acg9jjL3V`mVf2yMqYR|YwF{wGx0Q-yA&Pm;+gV%| z?N*%*<09`r+35vHCTA=2EqY(S|Dm3_eS~vw zj3(~v+xqdx-Sla?5~Yz5?Tw`mhHV!Y7k`PQAu?|W`+6q;m@BqOUv5JfwCYu)qKV!@ z&_yDrN!4T`@qCEILf%A%+hURy5*$j!%d5WZd7%jL2}9yzq5TMWY;!#UoXox(WZDa{ zI3FOi^PY8LGeQNY0v?f(wxmCB_6G+fYLj zI2CDv*h}in_mV?w#RnmTs2jin9bKE|czv>N+@qF1oyDtGeunf*FX_bj=t+8U+bmo4 zkq1@+t={&)cN+lcQR{=q0ck+YQl7(Q6tw|>JahH{Z`%v#UiGy(nOZL2X^sFtS1opk z-~Udq7k4jK&aoy$f>^5sqX$;kLP&8JmCSg2pCC`T8@AIe4^3G7c_w`Ip8+HF0$kt% z_hP0%3WGX1hZajk9PoL|*=-p%t#e#Pv%&tuSAM|%J>>|VFt;WpJE;67}q&A zTQyNt78~mzggWBhzWMt&aNpM7i~P`w$2^RPW%@&>#%%p(N8fV4egSiGkaP{;z;*5vRszU5itu#e+U}DC?sp54$cG_pHH)iVyZ`ItH~z$hnB$S!fYHM_ zHqVk$1ez=&_Ofo-ePBKGdpCdyn@vccqu-$Qf?;u2%w+ic4*^=53CM6$U_m~AZMpwg zEc_(v{qnG~(3t<&`gFZe4WazPCtP3M$e{Y8%@v)A2fW4_u>tifjNu=Ws9Xi0O>LiFqz%-+Wwu2L~1Un1mMo>2Uw z$e(~(_wCmV0XO?u%MNB??K*B~r*NJWJgnh%7&2=^u|J~mstKw|89(J5G7P;*Y)UU< z6B_$NUT*v1H$G`+^y=?iCD)OpQg#KI{Eh<&@LqLL#ZQ7ofo>tfPVa|p|J?6z^d3Z$ z8vWsARTG<>hGU;VK(}7JL2f&CS?Dv+i%15&5Pt3@%l^@+aPDK1n!Bc3{!7yN)z=0# zj|HT<#_nwlzBhWkAnbk8V?5f9k~YKc$T(o1jL-$gW&;YO$`9&f-zp-qDjd%P5R6St z7Z6kY0R_$cBX}6)RVOhlh2YYT(ilThmAdbnIJ`|fig7qfk|{j$y+urX{GIbcrnaXe zn{rKP)K_X;*F8spjiQ@$hKVfztC`GEBg}-P=f4IAB^&Ug$*Ddv7k{IB-N~hjU*Z-W z1^mZagp3IlBJZXuUS@#Eb>!34L-rp4Jb$iq;*wnCE2;Y~*+NPCQV}`abgW6FgP*90 zwm2+RYI~SYf!`Ln`Y85VBpk9ep+dcdt&n#1B^Rs$OoAnp*szo6$Sa8~J{22b3gRe^ zUcr8Ev&QNQ)V4>*rRD!mmqq%ABJ70yfzkI(DfcDv9a4SvvFbZ0cq!Q4>@v01gLt7A zxf_kCfRxs#+jPJPXo?zdb@`glE}P=V7!Ux{2k&zZbee|0m6mdk*Wxls zM>&{KP{N;Rf=Lv}PCYXEMI5~aY!EXug}+~IBw-;Iv1KVIMbY38gpR?9Bq+g>Tc zeyN_M`jtdErTl}kfoJjr;5%;xSLQaX8mbQZxEMQmaZz65bm5Ngpu9%+4-=J8fd+I* z-giqU-lk1E+I-uJ>4#y$BW!mqFV7GDF*WRe3VGv^tGobxzts#cC1PESrcKKf6(eWJ z?)t($=S~g^tBaevmoBlYcviP9^X-t0x8cA9&>V5#u>d51+azPYd_8noa!UE4Fp7UW zp!-Y?v`M5d<+vNt9_x@=X}u9+twyA{4LLam+C3P;E~(*RJd0YkyMEt&oWNM0rCprS zcFA%|6M>SRa%$aO7I^gbxNv%K6@UG;uuw){U;mqS$J9&)9zLdiC+JR(iTQ))pTo8I z0D3qi4%9rA4((79Gy-`oX|3WihiyTV-Ct|tyUkXx7N~X=rLnfg9UnbvrR0;StrmG* zP?=v7b>1EF2PbK8pZ|H1W4s|)?xr35B3JH!Tr!$;W^+6zqz&}A7BAip61h376YR|t zRb`qXT;@HPmLeVfo@yZ1!}v{lhwh*gd)M&YxMR3npLMR8UM-y}B{1od+Mh#NV6)PG z(xu?_%eD%C@e$d%?TUQimw@qrWwD8=PBzM&^$6x#?HBK!5R7#!-}8`4RwKA1X23-w z)P|uTOepN#{1Jj{JIODDooE-lgZq(0uL-QF@L@*DtB{$SN9lkILMXQN>zC&`ADEKn zM_PV4x(X!PbBOVY%Ia{Zm%O!W_@%M=v3~(g)%d*QHz)Y<{5KV}LjVJaCB%mPn87s5 zDH&DsrbqaB%w{H4J%la#0q*P@*#kt)^fCDfDO3}w6C_E94j z_K^_PFj4lH@;PNx>@<$^q~v2luv;x1yKD>iR+vfbZ#mX7RnaFLP>Fw32;_kbpqiiUSC zE2dAwgTKjTe6Zhk1w6pKpl=^8kdmc9uFh&Pr`aO%u z?ol@DUH`8L=w8mice0eP;hsei)Vql(fJ1J+N3N{Mc&CE>T)x>A81WirSL>$jebm!A z1@mKQ0}a2^zLA$hj{E*w58Wim^$tE(Ccg%hC!+Q4ynsf6*vS|_#>3=3?;&u{tnRBT9qlf-VLMR++n%Q@5g1`uk9-O zfDt7+L~CsA`N4Ozg0pd97VVqwXNM{v(PKsoIqMTIv(p;{Ygaf_J>cs4atMR_PC_l> z0M6bx*CPrFym%Q4YmM=k|5^Elm?9aJGzim1$DmQ__%ZPpxf{>9=fy+~m5+3l)c}1p zk|RUOC`Ka?VlsloB||-f2OC`>QbD>CBQrzD40U5r{M=j!ZUmsk%%A`~BxW-yTSKjY zI4o1C<^rqBgPD>0<2ahdYe%$CqUmpgOj^}QkvPnm65J+^j3q2gNdnk%?!>&v`_}jaE;?L}|^&aSSX>IQ8m-ORe_I zSNK>&(L6VDHZ*F^eBD@^ByAYRZi55QOGw**0QDYs2oB2TyeO)E0PU>2ZLw1n?xm# z91F@HjxI_R?_&UzWgLMKQVJ5m_ALRw?wZWa%~wMea*1RQ907dFP*#yx(dbF!c%@w~ zg7noMhcMpmr>OOz8kBK7*$=26KAchtMxpGBIHCkHRGwu!N+hWGlGjIPe|@TqXVq=NjYrPgJ|02)pd6Gfun2i8cyutNF<{oFZtULgWIhs_iN zYLdjlwRWF_cs_Ny&au7EB{faz%;}o0WW4ChR+r~f0nl^63<={6mS@-vSzx0V&0-ZUE`f` z$Tzt$8TjU6sLgkh-6t{Y}vc(r*F} z(I#Q2yPtz;E>W-|K;p8JRZg4O>v;QYBFv~QQ4;gHqEaW6cXmD->%ImkZVpvhWMTp^ z^;~4~T0O%lNx^J)B9SsZPNAXeUqmj-POtNAJ+JKoUL#6&djvumElxChnEl`{fM*}q zk%y&N_Nq`FXc1cq&2JZ!V8(GOM619Y@!E>qA$Ap8H;+tXPmN=Ih~zrj1ksq|xA%2>42S&!^Tar<44 zw0;Zc(az&QC>p?#v)VmlLXK!q|CqeDc{&5@oZ+F3sg4opok zYvka#PkkID@+c%*)d@KDSfXj(qBamOl9D;{F^JIcoDsJ9#oKz<-@t%G4`{{wYe*8rs$lEjcXY+;lh^(2L zYqt9cYZUvfR7pEXWi`u=#O%kdI^|68ig#lL2Q;TtCU^O85_9)37g-lB;${QGfsceV zNFOc+lYnVDk`Vu0$G{AxDYtEB<s}b&a z!t0dw^EOG;w%#24=5RwJkEzmZ$byTq-q@+ zh+#pyd-*uJb)=<{*;ZP&_S>7Gz+JpV#i{g0=ix)Q&7;Pu_ARlTLD)Bb zb$J9DXkyJ{zF!~f?d@{TD+~ll&A&z3G4stx0*|8#N(YX79|*R%GV|VrV2#+CJ9!;R z<#vZUm@GK*9ynh}7OkMi;W$(WXe`MxJOFl4*;h)2n$!qGu&irgGR#<6y98q=$_UrSzlGUfal z^Y*jbbG%RmiN`)gvN-02J1o%B4{JvGTqs{S6#n4xeDz3jG`Y_Le%B>;D zdundSsf3d$m?muv{m?6R0(?=5Rne6C6GJ1h)Qj^COXRVIa6z1Oz_4Y#9FI7TXqt1k zG@@<9@2mhO^TuEhqTyv}{pVkUs+oIZ?JJWbyZ&8@0oG&oGM~-du$|Oe`=SE4JCRAsbn)mA+FCEbRfF2Q&OyYVxIr zd;jw&gcvG~?L03vG8yv=1352=1=$P>_Kh&9%$f6wbiA}vk!UL7QPCMmgbVQvzcnd> zSUt<(L5oNXZh%L}Ta!-wyF-pkOe@*{pgW9|J1hPI$JS$d-w?EWW4+uFMe%+NQ;9aPu zp?PV}#`Ldlt0r*y7*|A9tVyR&5K#A4iEBu4j>8o!f_%48)01urAL{?HWiijG;ei;>iM{+{H`kI3Rf4*As)W@@{|4bkUN7=+wo;7Hw(i z5;jPR@NA*Z;NTu#EyUo?FlN|fdALzsLQ}Bfvzz?8oH!j_N;vVsk6)R_mT9I#K_k%1 zYH|2plf zk?3iTY!$?w_!Idc(l5RbR(`|1+A=d>3E)IF6=@nfeB>L@XTHsFIylZVgps} zPpX`A-r0+uPF03&@xcD;#-!htai~!3ZTXZ?m8Hshw&f(1LW#YUgRx_VAC4wRe@x&l zlpWix;v?a%w1}K61QQy9AoyCLGuofES+qxgpO7OlV z&8oTl1vdd@aVA)UkiJCK4mfk!YeW2Hbc4W%jb^(pF8%aJ(LP%J>m##X!ki&zT{t7{ zkA!Qbx8ZN-*qK*lP}&rw_SQ$b2No=wGtZoYLvv??oCyo_IquOl<#r%0qw@VgNHp7sI0D9>a3Ioc&J@ zlcq3oIdWj8`|VPO_rt+I6oucdG?*#0hIEj&PoZPv(40Hu!5(aJ^>{Kf+qc!>{V8r6 zdm&h*z*?;vKXC`{Ixjm9e1YX8M?hf;x?IaQ!ElH#ff>gCjDVTT59%dH3;>B{MB z4rXEAOvHgg`6z=0KKHB^%dBrSHaB0)7gBp1;M_0Br(3?$Mq|VqKoJTk8xJKnsUggi z`pm#E$(-8GuY(7*h)`-Eg8AGVYl=XF$`AKsOT5knYkn2I`c+FJQD22D_&%H;KI+wD z5h9FaCDQXv;Ceo0@2aRLFTDlr!tHyk9U^W-7gC9M^nh1(bGD@}yF!U62!yL4>xZUR z(s9KonGrzq`{43H9F}XFfYU#kClOCFjJi(VHzsiDSHyG6N>=nt^NinjY-$70K)JP6 z+i>mD1mfi;_s4C>hxQs$;f^E-VO$AzXS<`t4Ocm}gafxdGkwk5aCi+)7-oOQc{`TK zC%2%_4QTx{_dz-+_2)FvwLjmv6F`;7IW%v*1Y?(7F+XYb{5>jvvdSD6Rh zoQ^>p^0@C(N6~ zGR#Dz(88l!2s$zVgR8#SRjqpG+J)pePzJLpZX($@5>)sYyxsV-8R_mpq4h%{^TV}^ zlroC7LShsg6c48JFvutsfB*8_b;|bKE(&|SY+R+tF5o_r5EYfEZfUE?;cw!`Z$3gq z5Zl({Bu)!++U0z}i^^t#NOs_mLY(Q8bdE&-ld5cT4O1oMct<2EbefJKT(#&AaYnML z)}O2}bEjieuq36937?AKC4!Ez2L_xZ6`2l*4jC31*>S%l`7NUH^g-&~ zQXznI{6g?UoT~{kcdT^Ss>t^EllG}T98(B_#7+}*@nZRswZWuD9~&ivJlrA~xo<5h zI;Y=S$nKVZMh)6gJ83MTepp-8PBHkiNIc8W2P4_i6ZLE5_5_Q5dPK!c)uctPT(`0G zbBIU0gXq~n3<7~p9d#Q=V}&#Ms!sl|8fOi9U|)s0!0x}XLlad0MfN7Uv@g%}W6FS- zFO;{Au)B?h)*A$4{HS(oPdh7r#60|A+XA4{g_bqn;2pTvAYu0o61vbB_G-k}^#@?g zc~Vj-3;FY&bMB;UuTchbm4dEHFE8gYDu~S-WPuCiG*+Vic(n@@v@k#bQ!&u~jaq!| zTe{Y8-`LQ$Ao^{{+AdGrZ>y;iInP%<|!O9O7Y#*6P>Z; zH06r4%}ms9bV6FGbOo%ITU9v|-_4Ja5RyN)TH9IJUrp$YZD0f&BMmczg_Al|D)J*e`)+_I1r^t#pqMKS@gB{9v9^F zZT~O(7C=DxX$1SS{UqSaV|t@AeMpqXO`%!MXDn0KUT#ss;XW&aiT@W!dE*(!H2$=2 z->5j?P^5QA);6!Dp2cV^{2o3Z||K*xwIa7L1ag%_w}JdnxKA>Q7wHKU%T4NaI0Zz zd0(LmUSGz|3z%kw=d+Yf{SJGyaBH26{q%Mp@LU&t8bAJNmWmXyvq|<->0ex9M+A*b z@SULbWnFxmQ%WJXrQU>i{m9)!wpT#fF8Y5Xc^Xk7TG%@xBAdP&O}&V1#6N-Tne#OR z-p$Nqwyh4TqR@}I@PefLC$NOJv`anH!T?u6RRiD49>3pZ;}y6 zJi-XI>`Idpai(c&o1LZsc)TlRsV`DwO4hNo52RzFU%h{RR%$+erMAfkXz zvEu`V&z@9_ZuRsbJFc#=(aE6^_Gy}DLKAFhay-u2;@bPS-w!ASMuRbK!X5nVs%D$1 zXO!GD<%QG*r|L~n_`cQ%1_eYPF}xSnq4Qhn-pNPd-wTG>>`qaN{gQ!XG&pzCcVFZI zM~tQG)+?)hG?_2H!Dc_E`0w!xOlvrP^=g@S9GpVE!^y+5;JNR$1ITrr07;V?R#;`$ z&$s8TXPGkSq9hSLKmz!XTGx>8uCMOw?-}9e9m^Xz#$pm~$-mP7btaY&z)~BHBv*0` zeM=wYz=O!TYJ2Q%cY1!2KM1v^m@ zE&k?V0C@zaLx?MEh;nxwb?2P+!x3Oj^FKVt zF^G68H#|vaa9{yGOm6^rJU`Y&52y4{EcojzDi?Xx^_JvAu?AEvKn;dM!R~%B2*-=C z>~fo=@{*Tq17me>#gM)wzUN{N67Ixj(-zKajpS*I0eT!QZTaaOHnvfX+r;M)N%>{v zWD~Ew*aGf!?oZdMzvt4X3XxTvTd)0xo@^#^(=ilU_aEYp6Cok08-3PkF%KEku2y7Y zkM}<~gnKGR=p=*ITCfNgDMS!S2a@5G3i~)A%aKV){*3euT&3irw*SC5L(K zL6ilGTla0ao}5MF)6r8;k5Z}_W6QU@Q`w2pUrCy+r>SUc=F5ZcHhF0(0~0G(n%{TZ zEUVCM9F_;MdE4(f6=CiA|2>xeGo&UVBZJq1_T!kJyOSB^9x67~4DBrXQ$ABu+57kd z`8wylPv+Fm(gtFJpnsrC@G<7@oc9SF;3bix{|~ZP3^C|$O?d4-r=6e090W0AiDgf` zPq0FaPrx!d9zR<5-~JDFNt>dC{%@5VaP30#>*qfV9#EZ03H#mELi;AH7kNee}N=FrMFgC0@zYd}9az1h|H1=tAh}=;D*;)jr)-fro(D zjPK{3^a*Q#{A?4DZ9oFT)l6=XPHOBnq(J=6Wt%%YYOcCVWCGCrqkjzFmun8=k9Bju z*dBOcAN-}5fqI-%6hdk-Rv zQ|=V%Ym5pw{$V@)Tt#wiU8;ZzX=q6P@p}-2<$y$Va9B<&NJSA)y?y((+OP-h4j@4` zePPgIf!F39)hcxu0aCB#0KlJ&W%U4So#*A4wEd_kyzEQ`l`g>ZI(~x~=OC%_8M*;* z9&nL(fRPT8F$|z@@myczV3Ps=*n(Hzcb(9T6`{mHkV)f)F* z06dDA-#HQRxD6)n)Ne#5Oil_4W>=65q%fxdDJ6XXUPiRo#wNTym`3sbt3s8rvYcG} z=B5$E`o%(TtMx+Ov7V#kj}~%6Lj#-R?&vD#dTkB!)dt_eLS3b1%S>}K-(V`Mc&bz+zJ6s$ z3)?6TCdH4P{xDZO#m^rRP&XhaG|ElezFgKT51%1Z=N11>i=LV zHm=xlf`_VlNGxTC+g_e*xiP9Bu8#l5|~Y36I-*e63OI@TUQ?h|96P3zrPEdVI_O9-cO=LOib=N&0s&--W? z$%0bF^vquwnV4u8EY#Z>dU(n(cBWrp)MG0PsOorKP03}EM=Q3NYk2}yu;fRVy>UtK z1P6kW(4CPwU@4?3u3PbLqPnkaxlZ>4@~X~%!=TR^>Nrh(Or8XioT-G^y~iftZ^Q1YNo4zRNw#%sG$r zQA z@(+D+J)l>!{b>cz2l}f1gz1K#sVGo-dbmNiWR}*ecF-f0~a4=XsMa~l`JTI&~bBzLMn6G)+tdrCp zI)0JRXXOHv1uq4|9&1t{I7!fj2}Vt*j>y_Nw1km)C;Fo6mp+2SDv&$&t0^^DEZ6B^ z+Rw700oc+lVLgPZrI3SH>`1o1F)SW3e6%2lX6?Xg$CV)gv2)s!cGe-%NSm$GDjyg< zTHftPK{Owo9)U}Ci{&%Tjc3y0gTpWqEOn}~0Sj{nO)<#|YmCSnh`Nx7Nvj zv;U#ou=CW@33lHSwl18vd6RX#KjZ@XFeC3{i?molO*a)GvW2U*40jS39GWe4Em0LSr~u-X*zA!XNqo za5Ri8(>Vv2euJWZi*!b0@w@Z`8D4~gq(N9N(GUScyA$m!1XR%Gl28H&HJW;3y;AvUoxsFE3uuO5+1GK7r!{N z7$IKhqgCCBnDL z8~~)PA<o9~`!S`7)+`Nk8#x$#U_X?`2}@C>cQCdO z{oU5!7asXL4|B@MIj4B5&p2nmE22lv{{GmrX@Z)@(eJfx$UU@7^^V@~T z08wJ;Te|UB(d*Y(!DLI2w&Z$-g)U zpc!GNp2=v69fWe2V{`xv*?E-;T%HljD(8Jn-jj3iWtU~FyR?cfU>u{L648OG@&O|H zJSi76sb@`@TlF&H;`D3mb69OrO#q#0wM5P?)%KSlVin#)3UczpR|w`9Bgt+HdQ@-y zLcP4b5T?8Jj>a#Wfm`%UZXqgX=aXy{bxvm0d28ig^tN?N+2r!YHnE?U45$`ebEf)f zpqUwz6U=4jeDDWMk$-(mdhG{wW!YQ8wT4r{j~uTykUiKk&QuyUINwS>a!pFGATG4) z6VN$TY8vK{oi?yaN%EQ62?P=y{a!F7i5JODK+L#2q$lO&iW4v;y~_cF99mJ>#R6$y zOZyoxQ$3wx&CO;ZOGaEWct-J-fdyDEMpI`SM;fYPX62IL8TN_heZ+&)P>ZOWgd zk%Nh^D>mq-6=;8Fd{FReMfTt3QuWtJk?^7(EiI7N}+fvl)-SOEaj@X>sQ?pRe-!c|=T8 z-pCz)n;k`2YuuG=OKG#jXtN@Aa{bGJlz`#Iv+bS9OX}1959h4(>J?eyqJ>plt_y$N z8JRzWifoUit*w6+P?B>5cs??DyQeBX%z7@T#@5h^Ok7`WZEC{Zo#X9<^o8xQSuZWG zm%Tf92MbLe8?RF%hP4wnK~lpODU!uzQ-d0Yxxr9EUFXOndwgP_JXw;wK!{(WrCxNV zkukF<^ETAgmo*Go_H|%LpN53PZwDSAnXuugc7dV&?8d+G`ht#h{Q@{Hclm0od7Tfk zUKo7&^!P)iR6nFTtiq}itn1xp(FwT*-MMu=&m{TVBRS^9%k-$%f(&965J*Tqqr`vu z9Po(Q9&mrUNUm-dn9bL2e>hv^%<^ij%Zz?muen5N9U4x-8KvttcJ+XSn7{(YdpH;= zc}A&>qwmmSeD<3%2bj|FP?%20O&I3>%|A1^;ks~+W4Ks8i@^P1hvkASVk#9q^~l~V zbNOPAKw)xZ+S&XL-hqaW>g;qIi(*=0+P9xjmaPT5?KR!uK%K#2+h@i7>F44(g`j6AJ~maWs<4wCks=$&tULmE8X-j3OJ4 z-JKRB_{dY~SZMyDnsSrOFj2SC%@{uz$-sMiIm|Vw@*!Xz_dBjOLBAgb-#}?Y#ul-7 z^~=Sh{& z_x?4_tVzPL65ArY(l`uHJoy@3SG}rvG>->?gClZCPkbCKmxDu!s zTcm~k+BC^zuRg8J*RVXj+lnjP{yc&h4ZR$^#HeBJBu|D`2M&&C2#`mh^-(~2wvlQ?8$+-*e5cV9*YW!S zmc_>o6uE7W4QI5In1Oiyk=&rla|?=gk#Nl3bSE?LS<5M zkv_)n)mNyuAk$3!8?78skPX^t>V;H5Sb<)^nA9foqGmSZxgS|Dk=gEO-k()OX`x z4);$C%AA3zRfh0Zrn`cCx6zifrOrhG`rI_PJTa$zJBh9-*|+*8d+zMGSJ z6)t)egP25E%C!2M(Ah7WFa7&IwC)kntyP};_2LqK#kYGK}U+ry$z5Xul6YU|&cj)qql@`UX2^B+k#6o;268d?09FDS8}aUhcGkhVAO56meh2Zs`<#{356DiCaN`JsR2% zNWw=$uIo&XljLJnlNft=I@nfL={?;2O!Itj$nAX0I`+48h?-K7r#wF9oV)~kzZMds z2K?|(Iy&lE3UwUsid%7rI67K&fmGr{s6IYE;-Us$x4S*)p;Xz;VU&HJ@*&g$TLf75 zA)5r>5cQQrz6ocL#LBGD;GxitNs&ZH3tDccxHS8G7q?UFl(h>m?IQ4lY;Fk)?8dH1GQkU#~zvg_s ze)nwDM$-nFs%&&bVw05`7ymkBDyp%j#aSRbl}lO>*7!h%-dg!bu1%vkuJ}o){`GX% zomt(?PT<5vCh~<*PS~$M{Ylp=B7^%=*(T-1X$Qg|LIE{OVECZqlvSL6gYoSV8E?7k4_|+Y-o)6RD}{1;Tls^4TaiIFFhRfq$$Sm`yCGCU?DJh;t>>h z+6GT%Zw{N)IHq1zD>d*B)fT^y37L8k@7rCKC@7#siM|;XFhEJ(p4Pqa5VGedBRLaW zCriyIApfGVFyt~RmFuYv6+NF9X+RWIJQ^7sMZA#lg`R zE%m;$ygnY}R_{{ok6AG(JD_Vqi>}?gE(2QHD+}EIdiyVkvKhyQm)07JUGn;L!`>D0 zQN*U^y6M;iHc0_o&zie-5yZ0t(WQp_${}G$yAKIMp6mG1NTX%Gjm9lJJX`6rpEdW+ zt%LsRpa}?Yw5X1Zr7`c!fSDY!J7Kc z9+mj?yysyJu3=a$miq%=G+$o5v%@XLTy1U|dpPu7FC6qeM_>ssW-lvW$(;(6_V~_3D9?_#)q2<8BWHY|h>VfO>^4z7aleNUJ zew}uDt6$dhcY*0bLLaN>t8Y(~fc(5NqvuVMDrVj`b`vAddZOjr*$ z1g6FLR;u7XWpyZ4s(n5M=2Og0g*3G`lAR@a!Y~M)JDMv$!O=4O$`_dW^EViyHq;O_ zd5l>5=+ScO+hBUpDx{s^=T@)^5u$nJtn52=KnO*OLg%_?@YwYK!wTT zWUsZ!(A6TwW|C&HHx21jabaiMOZ07^@F268Yf!E&3q01b5I9t;_!vk9wu84d`^p6graZdx83#C&Wn