diff --git a/doc/UsersGuide/Makefile b/doc/UsersGuide/Makefile index a883b1dda4..2b79cf2c86 100644 --- a/doc/UsersGuide/Makefile +++ b/doc/UsersGuide/Makefile @@ -15,6 +15,11 @@ help: .PHONY: help Makefile linkcheck +doc: + make clean + $(MAKE) linkcheck + $(MAKE) html + linkcheck: $(SPHINXBUILD) -b linkcheck $(SPHINXOPTS) $(SOURCEDIR) $(LINKCHECKDIR) diff --git a/doc/UsersGuide/source/Glossary.rst b/doc/UsersGuide/source/Glossary.rst index 0d528a8d34..aa012eb238 100644 --- a/doc/UsersGuide/source/Glossary.rst +++ b/doc/UsersGuide/source/Glossary.rst @@ -10,16 +10,16 @@ Glossary To transport substances in the atmostphere by :term:`advection`. advection - According to the American Meteorological Society (AMS) `definition `__, advection is "The process of transport of an atmospheric property solely by the mass motion (velocity field) of the atmosphere." In common parlance, advection is movement of atmospheric substances that are carried around by the wind. + According to the American Meteorological Society (AMS) definition, `advection `_ is "The process of transport of an atmospheric property solely by the mass motion (velocity field) of the atmosphere." In common parlance, advection is movement of atmospheric substances that are carried around by the wind. ATM The Weather Model configuration that runs only the standalone atmospheric model. AQM - The `Air Quality Model `__ (AQM) is a UFS Application that dynamically couples the Community Multiscale Air Quality (:term:`CMAQ`) model with the UFS Weather Model through the :term:`NUOPC` Layer to simulate temporal and spatial variations of atmospheric compositions (e.g., ozone and aerosol compositions). The CMAQ, 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 Weather Model as :term:`tracers`. + The `Air Quality Model `_ (AQM) is a UFS Application that dynamically couples the Community Multiscale Air Quality (:term:`CMAQ`) model with the UFS Weather Model through the :term:`NUOPC` Layer to simulate temporal and spatial variations of atmospheric compositions (e.g., ozone and aerosol compositions). The CMAQ, 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 Weather Model as :term:`tracers`. CCPP - The `Common Community Physics Package `__ is a forecast-model agnostic, vetted collection of code containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (:term:`NWP`) along with a framework that connects the physics to the host forecast model. + The `Common Community Physics Package `_ is a forecast-model agnostic, vetted collection of code containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (:term:`NWP`) along with a framework that connects the physics to the host forecast model. CCPP-Framework The infrastructure that connects physics schemes with a host model; also refers to a software @@ -29,10 +29,10 @@ Glossary The pool of CCPP-compliant physics schemes; also refers to a software repository of the same name CDEPS - The `Community Data Models for Earth Predictive Systems `__ repository (CDEPS) contains a set of :term:`NUOPC`-compliant data components and :term:`ESMF`-based "stream" code that selectively removes feedback in coupled model systems. In essence, CDEPS handles the static Data Atmosphere (:term:`DATM`) integration with dynamic coupled model components (e.g., :term:`MOM6`). The CDEPS data models perform the basic function of reading external data files, modifying those data, and then sending the data back to the :term:`CMEPS` mediator. The fields sent to the :term:`mediator` are the same as those that would be sent by an active component. This takes advantage of the fact that the mediator and other CMEPS-compliant model components have no fundamental knowledge of whether another component is fully active or just a data component. More information about DATM is available in the `CDEPS Documentation `__. + The `Community Data Models for Earth Predictive Systems `_ repository (CDEPS) contains a set of :term:`NUOPC`-compliant data components and :term:`ESMF`-based "stream" code that selectively removes feedback in coupled model systems. In essence, CDEPS handles the static Data Atmosphere (:term:`DATM`) integration with dynamic coupled model components (e.g., :term:`MOM6`). The CDEPS data models perform the basic function of reading external data files, modifying those data, and then sending the data back to the :term:`CMEPS` mediator. The fields sent to the :term:`mediator` are the same as those that would be sent by an active component. This takes advantage of the fact that the mediator and other CMEPS-compliant model components have no fundamental knowledge of whether another component is fully active or just a data component. More information about DATM is available in the `CDEPS Documentation `_. CESM - The `Community Earth System Model `__ (CESM) is a fully-coupled global climate model developed at the National Center for Atmospheric Research (:term:`NCAR`) in collaboration with colleagues in the research community. + The `Community Earth System Model `_ (CESM) is a fully-coupled global climate model developed at the National Center for Atmospheric Research (:term:`NCAR`) in collaboration with colleagues in the research community. chgres_cube The preprocessing software used to create initial and boundary condition files to "coldstart" the forecast model. It is part of :term:`UFS_UTILS`. @@ -40,13 +40,13 @@ Glossary CICE CICE6 Sea Ice Model - `CICE `__ is a computationally efficient model for simulating the growth, melting, and movement of polar sea ice. It was designed as one component of a coupled atmosphere-ocean-land-ice global climate model. CICE has several interacting components, including a model of ice dynamics, a transport model that describes :term:`advection` of different state variables; and a vertical physics package called "Icepack". + `CICE `_ is a computationally efficient model for simulating the growth, melting, and movement of polar sea ice. It was designed as one component of a coupled atmosphere-ocean-land-ice global climate model. CICE has several interacting components, including a model of ice dynamics, a transport model that describes :term:`advection` of different state variables; and a vertical physics package called "Icepack". CMAQ - The `Community Multiscale Air Quality Model `__ (CMAQ, pronounced "cee-mak") is a numerical air quality model that predicts the concentration of airborne gases and particles and the deposition of these pollutants back to Earth's surface. The purpose of CMAQ is to provide fast, technically sound estimates of ozone, particulates, toxics, and acid deposition. CMAQ is an active open-source development project of the U.S. Environmental Protection Agency (EPA). Code is publicly availably at https://github.com/USEPA/CMAQ. + The `Community Multiscale Air Quality Model `_ (CMAQ, pronounced "cee-mak") is a numerical air quality model that predicts the concentration of airborne gases and particles and the deposition of these pollutants back to Earth's surface. The purpose of CMAQ is to provide fast, technically sound estimates of ozone, particulates, toxics, and acid deposition. CMAQ is an active open-source development project of the U.S. Environmental Protection Agency (EPA). Code is publicly availably at https://github.com/USEPA/CMAQ. CMEPS - The `Community Mediator for Earth Prediction Systems `__ (CMEPS) is a :term:`NUOPC`-compliant :term:`mediator` used for coupling Earth system model components. It is currently being used in NCAR's Community Earth System Model (:term:`CESM`) and NOAA's subseasonal-to-seasonal (S2S) coupled system. More information is available in the `CMEPS Documentation `__. + The `Community Mediator for Earth Prediction Systems `_ (CMEPS) is a :term:`NUOPC`-compliant :term:`mediator` used for coupling Earth system model components. It is currently being used in NCAR's Community Earth System Model (:term:`CESM`) and NOAA's subseasonal-to-seasonal (S2S) coupled system. More information is available in the `CMEPS Documentation `_. cron cron job @@ -58,21 +58,21 @@ Glossary Data assimilation is the process of combining observations, model data, and error statistics to achieve the best estimate of the state of a system. One of the major sources of error in weather and climate forecasts is uncertainty related to the initial conditions that are used to generate future predictions. Even the most precise instruments have a small range of unavoidable measurement error, which means that tiny measurement errors (e.g., related to atmospheric conditions and instrument location) can compound over time. These small differences result in very similar forecasts in the short term (i.e., minutes, hours), but they cause widely divergent forecasts in the long term. Errors in weather and climate forecasts can also arise because models are imperfect representations of reality. Data assimilation systems seek to mitigate these problems by combining the most timely observational data with a "first guess" of the atmospheric state (usually a previous forecast) and other sources of data to provide a "best guess" analysis of the atmospheric state to start a weather or climate simulation. When combined with an "ensemble" of model runs (many forecasts with slightly different conditions), data assimilation helps predict a range of possible atmospheric states, giving an overall measure of uncertainty in a given forecast. DATM - DATM is the *Data Atmosphere* component of :term:`CDEPS`. It uses static atmospheric forcing files (derived from observations or previous atmospheric model runs) instead of output from an active atmospheric model. This reduces the complexity and computational cost associated with coupling to an active atmospheric model. The *Data Atmosphere* component is particularly useful when employing computationally intensive Data Assimilation (DA) techniques to update ocean and/or sea ice fields in a coupled model. In general, use of DATM in place of :term:`ATM` can be appropriate when users are running a coupled model and only want certain components of the model to be active. More information about DATM is available in the `CDEPS Documentation `__. + DATM is the *Data Atmosphere* component of :term:`CDEPS`. It uses static atmospheric forcing files (derived from observations or previous atmospheric model runs) instead of output from an active atmospheric model. This reduces the complexity and computational cost associated with coupling to an active atmospheric model. The *Data Atmosphere* component is particularly useful when employing computationally intensive Data Assimilation (DA) techniques to update ocean and/or sea ice fields in a coupled model. In general, use of DATM in place of :term:`ATM` can be appropriate when users are running a coupled model and only want certain components of the model to be active. More information about DATM is available in the `CDEPS DATM Documentation `_. DOCN - DOCN is the *Data Ocean* component of :term:`CDEPS`. It uses static ocean forcing files (derived from observations or previous ocean model runs) instead of output from an active ocean model. This reduces the complexity and computational cost associated with coupling to an active ocean model. The *Data Ocean* component is particularly useful when employing computationally intensive Data Assimilation (DA) techniques to update atmospheric fields in a coupled model. In general, use of DOCN in place of :term:`MOM6` or :term:`HYCOM` can be appropriate when users are running a coupled model and only want certain components of the model to be active. More information about DOCN is available in the `CDEPS Documentation `__. + DOCN is the *Data Ocean* component of :term:`CDEPS`. It uses static ocean forcing files (derived from observations or previous ocean model runs) instead of output from an active ocean model. This reduces the complexity and computational cost associated with coupling to an active ocean model. The *Data Ocean* component is particularly useful when employing computationally intensive Data Assimilation (DA) techniques to update atmospheric fields in a coupled model. In general, use of DOCN in place of :term:`MOM6` or :term:`HYCOM` can be appropriate when users are running a coupled model and only want certain components of the model to be active. More information about DOCN is available in the `CDEPS DOCN Documentation `_. dycore dynamical core Global atmospheric model based on fluid dynamics principles, including Euler's equations of motion. EMC - The `Environmental Modeling Center `__ is one of :term:`NCEP`'s nine centers and leads the :term:`National Weather Service `'s modeling efforts. + The `Environmental Modeling Center `_ is one of :term:`NCEP`'s nine centers and leads the :term:`National Weather Service `'s modeling efforts. ESMF - `Earth System Modeling Framework `__. The ESMF defines itself as "a suite of software tools for developing high-performance, multi-component Earth science modeling applications." It is a community-developed software infrastructure for building and coupling models. + `Earth System Modeling Framework `_. The ESMF defines itself as "a suite of software tools for developing high-performance, multi-component Earth science modeling applications." It is a community-developed software infrastructure for building and coupling models. FMS The Flexible Modeling System (FMS) is a software framework for supporting the efficient @@ -82,20 +82,20 @@ Glossary FV3 FV3 dycore FV3 dynamical core - The Finite-Volume Cubed-Sphere :term:`dynamical core` (dycore). Developed at NOAA's `Geophysical - Fluid Dynamics Laboratory `__ (GFDL), it is a scalable and flexible dycore capable of both hydrostatic and non-hydrostatic atmospheric simulations. It is the dycore used in the UFS Weather Model. + The Finite-Volume Cubed-Sphere :term:`dynamical core` (dycore). Developed at NOAA's Geophysical + Fluid Dynamics Laboratory `(GFDL) `_, it is a scalable and flexible dycore capable of both hydrostatic and non-hydrostatic atmospheric simulations. It is the dycore used in the UFS Weather Model. 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. HPC-Stack - The `HPC-Stack `__ is a repository that provides a unified, shell script-based build system for building the software stack required for numerical weather prediction (NWP) tools such as the `Unified Forecast System (UFS) `__ and the `Joint Effort for Data assimilation Integration (JEDI) `__ framework. + The `HPC-Stack `_ is a repository that provides a unified, shell script-based build system for building the software stack required for numerical weather prediction (NWP) tools such as the `Unified Forecast System (UFS) `_ and the `Joint Effort for Data assimilation Integration (JEDI) `_ framework. HAFS - The Hurricane Analysis and Forecast System (`HAFS `__) is a :term:`UFS` application for hurricane forecasting. It is an :term:`FV3`-based multi-scale model and data assimilation (DA) system capable of providing analyses and forecasts of the inner core structure of tropical cyclones (TC) --- including hurricanes and typhoons --- out to 7 days. This is key to improving size and intensity predictions. HAFS also provides analyses and forecasts of the large-scale environment that is known to influence a TC's motion. HAFS development targets an operational analysis and forecast system for hurricane forecasters with reliable, robust and skillful guidance on TC track and intensity (including rapid intensification), storm size, genesis, storm surge, rainfall, and tornadoes associated with TCs. Currently, HAFS is under active development with collaborative efforts among NCEP/EMC, AOML/HRD, GFDL, ESRL/GSD, ESRL/NESII, OFCM/AOC, and NCAR/DTC. + The Hurricane Analysis and Forecast System (`HAFS `_) is a :term:`UFS` application for hurricane forecasting. It is an :term:`FV3`-based multi-scale model and data assimilation (DA) system capable of providing analyses and forecasts of the inner core structure of tropical cyclones (TC) --- including hurricanes and typhoons --- out to 7 days. This is key to improving size and intensity predictions. HAFS also provides analyses and forecasts of the large-scale environment that is known to influence a TC's motion. HAFS development targets an operational analysis and forecast system for hurricane forecasters with reliable, robust and skillful guidance on TC track and intensity (including rapid intensification), storm size, genesis, storm surge, rainfall, and tornadoes associated with TCs. Currently, HAFS is under active development with collaborative efforts among NCEP/EMC, AOML/HRD, GFDL, ESRL/GSD, ESRL/NESII, OFCM/AOC, and NCAR/DTC. HYCOM - The HYbrid Coordinate Ocean Model (`HYCOM `__) was developed to address known shortcomings in the vertical coordinate scheme of the Miami Isopycnic-Coordinate Ocean Model (MICOM). HYCOM is a primitive equation, general circulation model with vertical coordinates that remain isopycnic in the open, stratified ocean. However, the isopycnal vertical coordinates smoothly transition to z-coordinates in the weakly stratified upper-ocean mixed layer, to terrain-following sigma coordinates in shallow water regions, and back to z-level coordinates in very shallow water. The latter transition prevents layers from becoming too thin where the water is very shallow. See the `HYCOM User's Guide `__ for more information on using the model. The `HYCOM model code `__ is publicly available on GitHub. + The HYbrid Coordinate Ocean Model (`HYCOM `_) was developed to address known shortcomings in the vertical coordinate scheme of the Miami Isopycnic-Coordinate Ocean Model (MICOM). HYCOM is a primitive equation, general circulation model with vertical coordinates that remain isopycnic in the open, stratified ocean. However, the isopycnal vertical coordinates smoothly transition to z-coordinates in the weakly stratified upper-ocean mixed layer, to terrain-following sigma coordinates in shallow water regions, and back to z-level coordinates in very shallow water. The latter transition prevents layers from becoming too thin where the water is very shallow. See the `HYCOM User's Guide `_ for more information on using the model. The `HYCOM model code `_ is publicly available on GitHub. LM4 NUOPC NOAA-GFDL Land Model version 4 @@ -110,14 +110,14 @@ Glossary MOM MOM6 Modular Ocean Model - MOM6 is the latest generation of the Modular Ocean Model. It is numerical model code for simulating the ocean general circulation. MOM6 was originally developed by the `Geophysical Fluid Dynamics Laboratory `__. Currently, `MOM6 code `__ and an `extensive suite of test cases `__ are available under an open-development software framework. Although there are many public forks of MOM6, the `NOAA EMC fork `__ is used in the UFS Weather Model. + MOM6 is the latest generation of the Modular Ocean Model. It is numerical model code for simulating the ocean general circulation. MOM6 was originally developed by the `Geophysical Fluid Dynamics Laboratory `_. Currently, `MOM6 code `_ and an `extensive suite of test cases `_ are available under an open-development software framework. Although there are many public forks of MOM6, the `NOAA EMC fork `_ is used in the UFS Weather Model. MRW MRW App - The `Medium-Range Weather Application `__ is a UFS Application that targets predictions of atmospheric behavior out to about two weeks. It packages a prognostic atmospheric model (the UFS Weather Model), pre- and post-processing tools, and a community workflow. + The `Medium-Range Weather Application `_ is a UFS Application that targets predictions of atmospheric behavior out to about two weeks. It packages a prognostic atmospheric model (the UFS Weather Model), pre- and post-processing tools, and a community workflow. NCAR - The `National Center for Atmospheric Research `__. + The `National Center for Atmospheric Research `_. NCEP National Centers for Environmental Prediction (NCEP) is a branch of the :term:`National Weather Service ` and consists of nine centers, including the :term:`Environmental Modeling Center `. More information can be found at https://www.ncep.noaa.gov. @@ -168,10 +168,10 @@ Glossary SRW SRW App Short-Range Weather Application - The `Short-Range Weather Application `__ is a UFS Application that targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to about two days. It packages a prognostic atmospheric model (the UFS Weather Model), pre- and post-processing tools, and a community workflow. + The `Short-Range Weather Application `_ is a UFS Application that targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes out to about two days. It packages a prognostic atmospheric model (the UFS Weather Model), pre- and post-processing tools, and a community workflow. spack-stack - The `spack-stack `__ is a collaborative effort between the NOAA Environmental Modeling Center (EMC), the UCAR Joint Center for Satellite Data Assimilation (JCSDA), and the Earth Prediction Innovation Center (EPIC). *spack-stack* is a repository that provides a Spack-based method for building the software stack required for numerical weather prediction (NWP) tools such as the `Unified Forecast System (UFS) `__ and the `Joint Effort for Data assimilation Integration (JEDI) `__ framework. *spack-stack* uses the Spack package manager along with custom Spack configuration files and Python scripts to simplify installation of the libraries required to run various applications. The *spack-stack* can be installed on a range of platforms and comes pre-configured for many systems. Users can install the necessary packages for a particular application and later add the missing packages for another application without having to rebuild the entire stack. + The `spack-stack `_ is a collaborative effort between the NOAA Environmental Modeling Center (EMC), the UCAR Joint Center for Satellite Data Assimilation (JCSDA), and the Earth Prediction Innovation Center (EPIC). *spack-stack* is a repository that provides a Spack-based method for building the software stack required for numerical weather prediction (NWP) tools such as the `Unified Forecast System (UFS) `_ and the `Joint Effort for Data assimilation Integration (JEDI) `_ framework. *spack-stack* uses the Spack package manager along with custom Spack configuration files and Python scripts to simplify installation of the libraries required to run various applications. The *spack-stack* can be installed on a range of platforms and comes pre-configured for many systems. Users can install the necessary packages for a particular application and later add the missing packages for another application without having to rebuild the entire stack. Suite Definition File (SDF) An external file containing information about the @@ -184,20 +184,20 @@ Glossary well together tracer - According to the American Meteorological Society (AMS) `definition `__, a tracer is "Any substance in the atmosphere that can be used to track the history [i.e., movement] of an air mass." Tracers are carried around by the motion of the atmosphere (i.e., by :term:`advection`). These substances are usually gases (e.g., water vapor, CO2), but they can also be non-gaseous (e.g., rain drops in microphysics parameterizations). In weather models, temperature (or potential temperature), absolute humidity, and radioactivity are also usually treated as tracers. According to AMS, "The main requirement for a tracer is that its lifetime be substantially longer than the transport process under study." + According to the American Meteorological Society (AMS) definition, a `tracer `_ is "Any substance in the atmosphere that can be used to track the history [i.e., movement] of an air mass." Tracers are carried around by the motion of the atmosphere (i.e., by :term:`advection`). These substances are usually gases (e.g., water vapor, CO2), but they can also be non-gaseous (e.g., rain drops in microphysics parameterizations). In weather models, temperature (or potential temperature), absolute humidity, and radioactivity are also usually treated as tracers. According to AMS, "The main requirement for a tracer is that its lifetime be substantially longer than the transport process under study." UFS Unified Forecast System The Unified Forecast System (UFS) is a community-based, coupled, comprehensive Earth system modeling system. The UFS numerical applications span regional to global domains - and sub-hourly to seasonal time scales. The UFS is designed to support the :term:`Weather Enterprise` and to be the source system for NOAA's operational numerical weather prediction (:term:`NWP`) applications. For more information, visit https://ufscommunity.org/. + and sub-hourly to seasonal time scales. The UFS is designed to support the :term:`Weather Enterprise` and to be the source system for NOAA's operational numerical weather prediction (:term:`NWP`) applications. For more information, visit https://ufs.epic.noaa.gov/. UFS_UTILS - The UFS Utilities repository (`UFS_UTILS `__) contains a collection of pre-processing programs for use with the UFS Weather Model and UFS applications. These programs set up the model grid and create coldstart initial conditions. The code is publicly available on the `UFS_UTILS `__ Github repository. + The UFS Utilities repository (`UFS_UTILS `_) contains a collection of pre-processing programs for use with the UFS Weather Model and UFS applications. These programs set up the model grid and create coldstart initial conditions. The code is publicly available in the `UFS_UTILS GitHub repository `_. UPP Unified Post Processor - The `Unified Post Processor `__ is the :term:`post-processor` software developed at :term:`NCEP`. It is used operationally to + The `Unified Post Processor `_ is the :term:`post-processor` software developed at :term:`NCEP`. It is used operationally to convert the raw output from a variety of :term:`NCEP`'s :term:`NWP` models, including the :term:`FV3 dycore`, to a more useful form. WW3 @@ -213,6 +213,6 @@ Glossary A prognostic model that can be used for short- and medium-range research and operational forecasts. It can be an atmosphere-only model or be an atmospheric model coupled with one or more additional components, such as a wave or ocean model. - The UFS Weather Model repository is publicly available on `GitHub `__. + The UFS Weather Model repository is publicly available on `GitHub `_. diff --git a/doc/UsersGuide/source/InputsOutputs.rst b/doc/UsersGuide/source/InputsOutputs.rst index c4a79ed5f8..2ad87b2f74 100644 --- a/doc/UsersGuide/source/InputsOutputs.rst +++ b/doc/UsersGuide/source/InputsOutputs.rst @@ -793,7 +793,7 @@ The input files containing grid information and the time-varying forcing files f .. note:: - Users can find atmospheric forcing files for use with the land (:ref:`LND `) component in the `Land Data Assimilation (DA) data bucket `__. These files provide atmospheric forcing data related to precipitation, solar radiation, longwave radiation, temperature, pressure, winds, humidity, topography, and mesh data. Forcing files for the land component configuration come from the Global Soil Wetness Project Phase 3 (`GSWP3 `__) dataset. + Users can find atmospheric forcing files for use with the land (:ref:`LND `) component in the `Land Data Assimilation (DA) data bucket `_. These files provide atmospheric forcing data related to precipitation, solar radiation, longwave radiation, temperature, pressure, winds, humidity, topography, and mesh data. Forcing files for the land component configuration come from the Global Soil Wetness Project Phase 3 (`GSWP3 `_) dataset. .. code-block:: console @@ -1021,18 +1021,18 @@ AQM inputs defined in ``aqm.rc`` are listed and described in :numref:`Table %s < .. _lnd-in: -------- -LND -------- +-------------- +NOAH-MP (LND) +-------------- -LND component datasets are available from the `Land Data Assimilation (DA) System data bucket `__ and can be retrieved using a ``wget`` command: +LND component datasets are available from the `Land Data Assimilation (DA) System data bucket `_ and can be retrieved using a ``wget`` command: .. code-block:: console - wget https://noaa-ufs-land-da-pds.s3.amazonaws.com/current_land_da_release_data/v1.2.0/Landdav1.2.0_input_data.tar.gz - tar xvfz Landdav1.2.0_input_data.tar.gz + wget https://noaa-ufs-land-da-pds.s3.amazonaws.com/develop-20240501/Landda_develop_data.tar.gz + tar xvfz Landda_develop_data.tar.gz -These files will be untarred into an ``inputs`` directory if the user does not specify a different name. They include data for Dec. 21, 2019. :numref:`Table %s ` describes the file types. In each file name, ``YYYY`` refers to a valid 4-digit year, ``MM`` refers to a valid 2-digit month, and ``DD`` refers to a valid 2-digit day of the month. +These files will be untarred into an ``inputs`` directory. They include data for Jan. 1-2, 2000. :numref:`Table %s ` describes the file types. In each file name, ``YYYY`` refers to a valid 4-digit year, ``MM`` refers to a valid 2-digit month, and ``DD`` refers to a valid 2-digit day of the month. .. _LndInputFiles: @@ -1062,19 +1062,19 @@ These files will be untarred into an ``inputs`` directory if the user does not s oro_C96.mx100.tile*.nc - Tiled static files that contain information on maximum snow albedo, slope type, soil color and type, substrate temperature, vegetation greenness and type, and orography (grid and land mask information). ``*`` stands for the grid tile number [1-6]. - - Static/fixed files - * - grid_spec.nc + - FV3 fix files/Grid information + * - grid_spec.nc (aka C96.mosaic.nc) - Contains information on the mosaic grid - - Grid + - FV3 fix files/Grid information * - C96_grid.tile*.nc - - C96 grid information for tiles 1-6, where ``*`` is the grid tile number [1-6]. - - Grid + - C96 grid information for tiles 1-6 at C96 grid resolution, where ``*`` is the grid tile number [1-6]. + - FV3 fix files/Grid information * - C96_oro_data.tile*.nc / oro_C96.mx100.tileN.nc - Orography files that contain grid and land mask information, where ``*`` is the grid tile number [1-6]. ``mx100`` refers to the ocean resolution (100=1ยบ). - - Grid - * - See :ref:`CDEPS ` for information on atmospheric forcing files. + - FV3 fix files/Grid information + * - See :ref:`CDEPS ` for information on GSWP3 atmospheric forcing files. - Atmospheric forcing - - CDEPS + - CDEPS/DATM * - ghcn_snwd_ioda_YYYYMMDD.nc - GHCN snow depth data assimilation files - DA @@ -1088,9 +1088,9 @@ These files will be untarred into an ``inputs`` directory if the user does not s Static Datasets (i.e., *fix files*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The static files (listed in :numref:`Table %s `) include specific information on location, time, soil layers, and fixed (invariant) experiment parameters that are required for the land component to run. The data must be provided in :term:`netCDF` format. +The fix files (listed in :numref:`Table %s `) include specific information on location, time, soil layers, and fixed (invariant) experiment parameters that are required for the land component to run. The data must be provided in :term:`netCDF` format. -The following static files are available in the ``inputs/UFS_WM/FV3_fix_tiled/C96/`` data directory (downloaded :ref:`above `): +The following fix files are available in the ``inputs/UFS_WM/FV3_fix_tiled/C96/`` data directory (downloaded :ref:`above `): .. code-block:: @@ -1104,7 +1104,7 @@ The following static files are available in the ``inputs/UFS_WM/FV3_fix_tiled/C9 oro_C96.mx100.tile*.nc where ``*`` refers to the tile number (1-6). -Details on the configuration variables included in this file are available in the :ref:`Land DA documentation `. +Details on the configuration variables included in these files are available in the :ref:`Land DA documentation `. .. _lnd-grid-ic-files: @@ -1148,6 +1148,7 @@ The configuration files used by the UFS Weather Model are listed here and descri * ``field_table`` * ``model_configure`` * ``ufs.configure`` + * ``fd_ufs.yaml`` * ``suite_[suite_name].xml`` (used only at build time) * ``datm.streams`` (used by CDEPS) * ``datm_in`` (used by CDEPS) @@ -1675,6 +1676,34 @@ However, ``ufs.configure`` files for other configurations of the Weather Model a .. note:: The ``aoflux_code`` option is used to define the algorithm that will be used to calculate atmosphere-ocean fluxes. The possible options are ``cesm`` and ``ccpp``. If ``ccpp`` is selected then the suite file provided in the ``aoflux_ccpp_suite`` option is used to calculate atmosphere-ocean fluxes through the use of CCPP host model. + +.. _fd-ufs: + +----------------- +``fd_ufs.yaml`` +----------------- + +The ``fd_ufs.yaml`` file contains a field dictionary to configure several fields that are used in import/export operations by different Earth modeling components in ESMF's NUOPC coupling system. It allows the sharing of coupling fields between components. Entries in the field dictionary are organized as YAML lists of maps. The NUOPC Field Dictionary data structure in the model code is set up by the NUOPC function called ``NUOPC_FieldDictionarySetup()``, which loads the ``fd_ufs.yaml`` file (see `UFSDriver.F90 `_). The field +metadata described in each entry are used by the NUOPC layer to match fields provided and requested by the various component models. The field dictionary can be shared with other Earth modeling systems that use the same ESPS coupling strategy, such as the Community Earth System Model (CESM). + +The standard field metadata for each coupling field has the following keys and corresponding values: + +.. code-block:: console + + - standard_name: + canonical_units: + description: + alias: + +* ``standard_name`` (required): Name of the field. +* ``canonical_units`` (required): The units used to fully define the field +* ``description`` (optional): Brief explanation of the field +* ``alias`` (optional): Alternative names for the field. An alias can be one character string or a list of strings (e.g., ```` or ``[, ]``). This allows a field to have different names used in the coupling field exchange. + +Either the ``standard_name`` or ``alias`` name can be used in a component model, and the NUOPC layer will recognize these fields as the same field using the definitions provided in the YAML file. For more on the NUOPC field dictionary, visit the `documentation `_. + + + .. _SDF-file: --------------------------------------- diff --git a/doc/UsersGuide/source/Introduction.rst b/doc/UsersGuide/source/Introduction.rst index b2d86b08c1..829d332e4a 100644 --- a/doc/UsersGuide/source/Introduction.rst +++ b/doc/UsersGuide/source/Introduction.rst @@ -8,7 +8,7 @@ The Unified Forecast System (:term:`UFS`) Weather Model (:term:`WM`) is a progno used for short- and medium-range research and operational forecasts, as exemplified by its use in the operational Global Forecast System (GFS) of the National Oceanic and Atmospheric Administration (NOAA). In addition to its use in NOAA's operational forecast systems, the UFS WM is the atmospheric model used in public UFS application releases, such as the Short-Range Weather (SRW) Application v2.2.0 release. These releases represent a snapshot of a continuously evolving system undergoing open -development. More information about the UFS can be found on the UFS Community Portal at https://ufscommunity.org/ and on the Earth Prediction Innovation Center (EPIC) website at https://epic.noaa.gov/get-code/ufs-weather-model/. +development. More information about the UFS can be found on the UFS Community Portal at https://ufs.epic.noaa.gov/ and on the Earth Prediction Innovation Center (EPIC) website at https://epic.noaa.gov/get-code/ufs-weather-model/. Key architectural elements of the UFS WM, along with links to external detailed documentation for those elements, are listed below: diff --git a/doc/UsersGuide/source/conf.py b/doc/UsersGuide/source/conf.py index ea5e7cf860..ae16c27be2 100644 --- a/doc/UsersGuide/source/conf.py +++ b/doc/UsersGuide/source/conf.py @@ -14,13 +14,15 @@ # import os import sys +import sphinx +from sphinx.util import logging sys.path.insert(0, os.path.abspath('.')) - +sys.path.insert(0, os.path.abspath('../../../tests-dev')) # -- Project information ----------------------------------------------------- project = 'UFS Weather Model Users Guide' -copyright = '2020' +copyright = '2024' author = ' ' # The short X.Y version @@ -121,6 +123,7 @@ def setup(app): app.add_css_file('custom.css') # may also be an URL app.add_css_file('theme_overrides.css') # may also be an URL + app.connect('autodoc-process-docstring', warn_undocumented_members) # Created warnings for undocumented portions of Python scripts # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -212,6 +215,34 @@ def setup(app): # -- Extension configuration ------------------------------------------------- +# -- Options for autodoc extension --------------------------------------- + +autodoc_mock_imports = [ + ] + +logger = logging.getLogger(__name__) + +# Ensure that warnings pop up when functions, attributes, or methods are undocumented +members_to_watch = ['function', 'attribute', 'method'] +def warn_undocumented_members(app, what, name, obj, options, lines): + if(what in members_to_watch and len(lines)==0): + message = what + " is undocumented: " + name + "(%d)"% len(lines) + logger.warning(message) + +autodoc_default_options = { + "members": True, + "undoc-members": True, + "show-inheritance": True, +} + +add_module_names = False + +# -- Options for napoleon extension --------------------------------------- + +napoleon_numpy_docstring = False +napoleon_google_docstring = True +napoleon_custom_sections = [('Returns', 'params_style')] # Allows return of multiple values + # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. diff --git a/doc/UsersGuide/source/create_log.rst b/doc/UsersGuide/source/create_log.rst new file mode 100644 index 0000000000..80158437ee --- /dev/null +++ b/doc/UsersGuide/source/create_log.rst @@ -0,0 +1,7 @@ +create\_log module +================== + +.. automodule:: create_log + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/UsersGuide/source/create_xml.rst b/doc/UsersGuide/source/create_xml.rst new file mode 100644 index 0000000000..29037b6637 --- /dev/null +++ b/doc/UsersGuide/source/create_xml.rst @@ -0,0 +1,7 @@ +create\_xml module +================== + +.. automodule:: create_xml + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst index c6636e8452..6004f5a5fe 100644 --- a/doc/UsersGuide/source/index.rst +++ b/doc/UsersGuide/source/index.rst @@ -15,6 +15,7 @@ Welcome to the UFS Weather Model User's Guide BuildingAndRunning InputsOutputs Configurations + modules ConfigParameters AutomatedTesting FAQ diff --git a/doc/UsersGuide/source/modules.rst b/doc/UsersGuide/source/modules.rst new file mode 100644 index 0000000000..456173aa9a --- /dev/null +++ b/doc/UsersGuide/source/modules.rst @@ -0,0 +1,9 @@ +Technical Documentation for ``tests-dev`` +========================================== + +.. toctree:: + :maxdepth: 4 + + create_log + create_xml + ufs_test_utils diff --git a/doc/UsersGuide/source/ufs_test_utils.rst b/doc/UsersGuide/source/ufs_test_utils.rst new file mode 100644 index 0000000000..c5291bb440 --- /dev/null +++ b/doc/UsersGuide/source/ufs_test_utils.rst @@ -0,0 +1,7 @@ +ufs\_test\_utils module +======================= + +.. automodule:: ufs_test_utils + :members: + :undoc-members: + :show-inheritance: diff --git a/tests-dev/create_log.py b/tests-dev/create_log.py index 72ebd5ae70..6dfee1cbf4 100644 --- a/tests-dev/create_log.py +++ b/tests-dev/create_log.py @@ -6,7 +6,7 @@ from ufs_test_utils import get_testcase, write_logfile, delete_files, machine_check_off def finish_log(): - """Collect regression test results and generate log file. + """Collects regression test results and generates log file. """ UFS_TEST_YAML = str(os.getenv('UFS_TEST_YAML')) PATHRT = os.getenv('PATHRT') diff --git a/tests-dev/create_xml.py b/tests-dev/create_xml.py index 2d567cec4e..a7462c70bf 100644 --- a/tests-dev/create_xml.py +++ b/tests-dev/create_xml.py @@ -5,18 +5,19 @@ from ufs_test_utils import get_testcase, write_logfile, rrmdir, machine_check_off def rocoto_create_entries(RTPWD,MACHINE_ID,INPUTDATA_ROOT,INPUTDATA_ROOT_WW3,INPUTDATA_ROOT_BMIC,RUNDIR_ROOT,NEW_BASELINE,ROCOTO_XML): - """Generate header information for Rocoto xml file + """Generate header information for Rocoto XML file Args: RTPWD (str): Baseline directory - MACHINE_ID (str): Machine ID i.e. Hera, Gaea, Jet, etc. + MACHINE_ID (str): Machine ID i.e., Hera, Gaea, Jet, etc. INPUTDATA_ROOT (str): Input data directory INPUTDATA_ROOT_WW3 (str): WW3 input data directory INPUTDATA_ROOT_BMIC (str): BMIC input data directory RUNDIR_ROOT (str): Test run directory NEW_BASELINE (str): Directory for newly generated baselines - ROCOTO_XML (str): Rocoto .xml filename to write to + ROCOTO_XML (str): Rocoto XML filename to write to """ + PATHRT = os.getenv('PATHRT') LOG_DIR= PATHRT+'/logs/log_'+MACHINE_ID PATHTR, tail = os.path.split(PATHRT) @@ -43,17 +44,17 @@ def rocoto_create_entries(RTPWD,MACHINE_ID,INPUTDATA_ROOT,INPUTDATA_ROOT_WW3,INP f.close() def rocoto_create_compile_task(MACHINE_ID,COMPILE_ID,ROCOTO_COMPILE_MAXTRIES,MAKE_OPT,ACCNR,COMPILE_QUEUE,PARTITION,ROCOTO_XML): - """Generate and append compile task into Rocoto xml file + """Generate and append compile task into Rocoto XML file Args: - MACHINE_ID (str): Machine ID i.e. Hera, Gaea, Jet, etc. - COMPILE_ID (str): Compile identifier e.g. s2swa_intel + MACHINE_ID (str): Machine ID i.e., Hera, Gaea, Jet, etc. + COMPILE_ID (str): Compile identifier e.g., s2swa_intel ROCOTO_COMPILE_MAXTRIES (str): Max attempts for compile MAKE_OPT (str): Make build options ACCNR (str): Account to run the job with - COMPILE_QUEUE (str): QOS i.e. batch, windfall, normal, etc. - PARTITION (str): System partition i.e. xjet, c5 - ROCOTO_XML (str): Rocoto .xml filename to write to + COMPILE_QUEUE (str): Quality of Service (QOS), i.e., batch, windfall, normal, etc. + PARTITION (str): System partition i.e., xjet, c5 + ROCOTO_XML (str): Rocoto XML filename to write to """ NATIVE="" BUILD_CORES="8" @@ -90,11 +91,11 @@ def rocoto_create_compile_task(MACHINE_ID,COMPILE_ID,ROCOTO_COMPILE_MAXTRIES,MAK f.close() def write_metatask_begin(COMPILE_METATASK_NAME, filename): - """Write compile task metadata to Rocoto xml file + """Write compile task metadata to Rocoto XML file Args: - COMPILE_METATASK_NAME (str): Compile job name e.g. s2swa_intel - filename (str): Rocoto xml filename to append to + COMPILE_METATASK_NAME (str): Compile job name e.g., s2swa_intel + filename (str): Rocoto XML filename to append to """ metatask_name = f""" 0 """ @@ -103,10 +104,10 @@ def write_metatask_begin(COMPILE_METATASK_NAME, filename): f.close() def write_metatask_end(filename): - """Append closing metatask element to Rocoto xml + """Append closing metatask element to Rocoto XML Args: - filename (str): Rocoto xml filename + filename (str): Rocoto XML filename """ metatask_name = f""" """ @@ -118,10 +119,10 @@ def write_compile_env(SCHEDULER,PARTITION,JOB_NR,COMPILE_QUEUE,RUNDIR_ROOT): """Generate compile task .env file Args: - SCHEDULER (str): Job scheduler e.g. pbs, slurm - PARTITION (str): System partition i.e. xjet, c5 + SCHEDULER (str): Job scheduler, e.g., pbs, slurm + PARTITION (str): System partition, i.e., xjet, c5 JOB_NR (str): Job number - COMPILE_QUEUE (str): QOS i.e. batch, windfall, normal, etc. + COMPILE_QUEUE (str): Quality of Service (QOS), i.e., batch, windfall, normal, etc. RUNDIR_ROOT (str): Test run directory """ filename = RUNDIR_ROOT+"/compile_"+str(os.getenv('COMPILE_ID'))+".env" @@ -308,6 +309,11 @@ def make_loghead(ACCNR,MACHINE_ID,RUNDIR_ROOT,RTPWD,REGRESSIONTEST_LOG): write_logfile(filename, "a", output="* (-v) - VERBOSE OUTPUT"+"\n") def xml_loop(): + """ + Creates workflow XML file for each test. + Reads in ``baseline_setup.yaml``, parses ``ufs_test.yaml``, and sets up Rocoto XML + according to the runtime arguments given in ``ufs_test.sh``. + """ ACCNR = str(os.getenv('ACCNR')) PATHRT = str(os.getenv('PATHRT')) MACHINE_ID = str(os.getenv('MACHINE_ID')) diff --git a/tests-dev/ufs_test_utils.py b/tests-dev/ufs_test_utils.py index 9a0f8a2faa..dafefea0a5 100644 --- a/tests-dev/ufs_test_utils.py +++ b/tests-dev/ufs_test_utils.py @@ -7,7 +7,7 @@ import subprocess def update_testyaml(input_list): - """Generate temporary test yaml based on list of tests received + """Generates temporary test YAML based on list of tests received Args: input_list (list): list of tests to run @@ -80,7 +80,7 @@ def update_testyaml(input_list): file_yaml.close() def update_testyaml_n(): - """Update test yaml file for a single test specified in -n + """Updates test YAML file for a single test specified in ``-n `` """ try: SRT_NAME = str(os.getenv('SRT_NAME')) @@ -91,7 +91,7 @@ def update_testyaml_n(): update_testyaml(input_list) def update_testyaml_b(): - """Update test yaml file for tests specified in -b + """Updates test YAML file for tests specified in ``-b `` """ NEW_BASELINES_FILE = str(os.getenv('NEW_BASELINES_FILE')) input_list=[] @@ -104,31 +104,31 @@ def update_testyaml_b(): update_testyaml(input_list) def string_clean(str_in): - """Strip out RUN or COMPILE whitespace and separate with commas. + """Strips out RUN or COMPILE whitespace and separates with commas. Args: - str_in (str): RUN or COMPILE line read in from rt.conf + str_in (str): RUN or COMPILE line read in from ``rt.conf`` Returns: - str: whitespace stripped and comma separated values + str: Whitespace stripped and comma separated values """ return "'"+("','".join(str_in.split()))+"'" def parse_line(str_in): - """Parse rt.conf line into list + """Parses ``rt.conf`` line into list Args: str_in (str): RUN or COMPILE line from rt.conf Returns: - list: list of RUN or COMPILE test attributes + build_attr: List of RUN or COMPILE test attributes """ build_attr = " ".join(str_in.split()).split('|') build_attr = [attr.strip() for attr in build_attr] return build_attr def create_yaml(): - """Parse default rt.conf into ufs_test.yaml + """Parses default ``rt.conf`` into ``ufs_test.yaml`` """ with open('ufs_test.yaml', 'w') as yaml_file, open("rt.conf") as conf_file: @@ -190,7 +190,7 @@ def create_yaml(): yaml_file.close(); conf_file.close() def sync_testscripts(): - """symlink sharable rt.sh test scripts + """Symlinks sharable ``rt.sh`` test scripts """ dst= os.getcwd() src= os.path.split(os.getcwd())[0]+'/tests' @@ -211,13 +211,13 @@ def sync_testscripts(): os.symlink(src_name, dst_name) def machine_check_off(machine_id, val): - """Check turned-off machine from yaml configuration + """Checks turned-off machine from YAML configuration Args: - machine_id (str): local machine name - val (dic): build and test config dictionary list + machine_id (str): Local machine name + val (dict): Build and test config dictionary list Returns: - pass_machine: logical flag to pass local machine + pass_machine: Logical flag to pass local machine """ pass_machine = True if 'turnoff' in val.keys(): @@ -229,10 +229,10 @@ def machine_check_off(machine_id, val): return pass_machine def delete_files(deletefiles): - """Remove specified filepath + """Removes specified filepath Args: - deletefiles (str): filepath to remove e.g. tests/rocoto.* + deletefiles (str): filepath to remove, e.g., ``tests/rocoto.*`` """ fileList = glob.glob(deletefiles, recursive=True) for filePath in fileList: @@ -242,7 +242,7 @@ def delete_files(deletefiles): print("Error while deleting ",deletefiles) def link_new_baselines(): - """Create symlinks for newly generated baselines. + """Creates symlinks for newly generated baselines """ USER = str(os.environ.get('USER')) MACHINE_ID = os.getenv('MACHINE_ID') @@ -272,14 +272,14 @@ def link_new_baselines(): symlink_baselines.wait() def get_testdep(casename,val): - """Retrieve test case dependencies + """Retrieves test case dependencies Args: casename (str): Test case name - val (dict): Test case attributes e.g. val['compiler'] + val (dict): Test case attributes, e.g., val['compiler'] Returns: - dict: Test case and config for the specified dependency + test_dep: Dictionary with test case and configuration for the specified dependency """ test_dep = None for test in val: @@ -289,13 +289,13 @@ def get_testdep(casename,val): return test_dep def get_testcase(test): - """Retrieve test case names and configs from given dict from pyaml + """Retrieves test case names and configs from given dictionary from PyYAML Args: - test (dict): dict retrieved from reading in yaml test file + test (dict): Dictionary retrieved from reading in YAML test file Returns: - str, dict: test name and python dict of test configuration + case_name, case_config: Test name (str) and Python dictionary of test configuration """ case_name = None case_config = None @@ -305,11 +305,11 @@ def get_testcase(test): return case_name, case_config def write_logfile(logfile, openmod, output="", subproc=""): - """Append given output into log file + """Appends given output into log file Args: logfile (str): Log filename - openmod (str): mode to open file in + openmod (str): Mode to open file in output (str): Content to append to log file. Defaults to "". subproc (str): Command to run within the shell. Defaults to "". """ @@ -321,7 +321,7 @@ def write_logfile(logfile, openmod, output="", subproc=""): rtlog.close() def rrmdir(path): - """Remove all files and directories in specified path. + """Removes all files and directories in specified path. Args: path (str): File path to remove