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 =================