diff --git a/.github/scripts/check_tech_doc.sh b/.github/scripts/check_tech_doc.sh index d988e50cd6..1ee78b8574 100755 --- a/.github/scripts/check_tech_doc.sh +++ b/.github/scripts/check_tech_doc.sh @@ -5,7 +5,7 @@ set -eo pipefail # Install prerequisites -pip install sphinx +pip install Sphinx==7.4.7 pip install sphinx-rtd-theme pip install sphinxcontrib-bibtex diff --git a/.github/workflows/doc_tests.yaml b/.github/workflows/doc_tests.yaml index 34fb01a9ac..6649fc91c0 100644 --- a/.github/workflows/doc_tests.yaml +++ b/.github/workflows/doc_tests.yaml @@ -22,4 +22,9 @@ jobs: - name: Build documentation run: | cd doc - make doc + make clean && make html + - name: Check links + if: ${{ !cancelled() }} + run: | + cd doc + make linkcheck diff --git a/doc/Makefile b/doc/Makefile index a4fac61e1a..614ffbaafa 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,6 +1,6 @@ # Makefile for Sphinx documentation -SPHINXOPTS = -a -n -W +SPHINXOPTS = -a -n -W --keep-going SPHINXBUILD = sphinx-build SOURCEDIR = . BUILDDIR = build diff --git a/doc/UsersGuide/BuildingRunningTesting/RunSRW.rst b/doc/UsersGuide/BuildingRunningTesting/RunSRW.rst index eefaf63715..b93ebd0a28 100644 --- a/doc/UsersGuide/BuildingRunningTesting/RunSRW.rst +++ b/doc/UsersGuide/BuildingRunningTesting/RunSRW.rst @@ -310,9 +310,9 @@ On platforms where Rocoto and :term:`cron` are available, users can automate res USE_CRON_TO_RELAUNCH: true CRON_RELAUNCH_INTVL_MNTS: 3 -.. note:: +.. attention:: - 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. + Cron is not available on Derecho or Gaea. On Orion/Hercules, users must be logged into the [hercules/orion]-login-1 node to use cron. 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. @@ -1389,6 +1389,10 @@ where ``/path/to/experiment/directory`` is changed to correspond to the user's ` * 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, administrators discourage using ``*/1 * * * *`` due to load problems. ``*/3 * * * *`` (or ``CRON_RELAUNCH_INTVL_MNTS: 3``) is the preferred option for cron jobs on other Level 1 systems. +.. attention:: + + Cron is not available on Derecho or Gaea. On Orion/Hercules, users must be logged into the [hercules/orion]-login-1 node to use cron. + To check the experiment progress: .. code-block:: console diff --git a/doc/UsersGuide/CustomizingTheWorkflow/ConfigWorkflow.rst b/doc/UsersGuide/CustomizingTheWorkflow/ConfigWorkflow.rst index dc582ba4bd..b32a012cf7 100644 --- a/doc/UsersGuide/CustomizingTheWorkflow/ConfigWorkflow.rst +++ b/doc/UsersGuide/CustomizingTheWorkflow/ConfigWorkflow.rst @@ -30,7 +30,7 @@ If non-default parameters are selected for the variables in this section, they s Setting ``RUN_ENVIR`` to "community" is recommended in most cases for users who are not running in NCO's production environment. 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-wiki:`SRW App Wiki page `. When running the SRW App on any ParallelWorks/NOAA Cloud system, use "NOAACLOUD" regardless of the underlying system (AWS, GCP, or Azure). Valid values: ``"HERA"`` | ``"ORION"`` | ``"HERCULES"`` | ``"JET"`` | ``"CHEYENNE"`` | ``"DERECHO"`` | ``"GAEA"`` | ``"GAEA-C6"`` | ``"NOAACLOUD"`` | ``"STAMPEDE"`` | ``"ODIN"`` | ``"MACOS"`` | ``"LINUX"`` | ``"SINGULARITY"`` | ``"WCOSS2"`` (Check ``ufs-srweather-app/ush/valid_param_vals.yaml`` for the most up-to-date list of supported platforms.) + The machine (a.k.a. platform or system) on which the workflow will run. Currently supported platforms are listed on the :srw-wiki:`SRW App Wiki page `. When running the SRW App on any ParallelWorks/NOAA Cloud system, use "NOAACLOUD" regardless of the underlying system (AWS, GCP, or Azure). Valid values: ``"HERA"`` | ``"ORION"`` | ``"HERCULES"`` | ``"JET"`` | ``"DERECHO"`` | ``"GAEA"`` | ``"GAEA-C6"`` | ``"NOAACLOUD"`` | ``"MACOS"`` | ``"LINUX"`` | ``"SINGULARITY"`` | ``"WCOSS2"`` (Check ``ufs-srweather-app/ush/valid_param_vals.yaml`` for the most up-to-date list of supported platforms.) .. 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. @@ -2103,7 +2103,7 @@ Non-default parameters for coupled Air Quality Modeling (AQM) tasks are set in t Smoke and Dust Configuration Parameters -===================================== +========================================= Non-default parameters for Smoke and Dust tasks are set in the ``smoke_dust_parm:`` section of the ``config.yaml`` file. diff --git a/doc/UsersGuide/Reference/Glossary.rst b/doc/UsersGuide/Reference/Glossary.rst index c543b73258..efcc47cc7b 100644 --- a/doc/UsersGuide/Reference/Glossary.rst +++ b/doc/UsersGuide/Reference/Glossary.rst @@ -106,10 +106,10 @@ Glossary FV3 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. + 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. FVCOM - `Finite Volume Community Ocean Model `__. FVCOM is used in modeling work for the `Great Lakes Coastal Forecasting System (next-gen FVCOM) `__ conducted by the `Great Lakes Environmental Research Laboratory `__. + `Finite Volume Community Ocean Model `_. FVCOM is used in modeling work for the `Great Lakes Coastal Forecasting System (next-gen FVCOM) `_ conducted by the `Great Lakes Environmental Research Laboratory `_. 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. @@ -172,7 +172,7 @@ Glossary MPI stands for Message Passing Interface. An MPI is a standardized communication system used in parallel programming. It establishes portable and efficient syntax for the exchange of messages and data between multiple processors that are used by a single computer program. An MPI is required for high-performance computing (HPC) systems. MRMS - Multi-Radar/Multi-Sensor (MRMS) System Analysis data. This data is required for METplus composite reflectivity or :term:`echo top` verification tasks within the SRW App. A two-day archive of precipitation, radar, and aviation and severe weather fields is publicly available and can be accessed `here `__. + Multi-Radar/Multi-Sensor (MRMS) System Analysis data. This data is required for METplus composite reflectivity or :term:`echo top` verification tasks within the SRW App. A two-day archive of precipitation, radar, and aviation and severe weather fields is publicly available and can be accessed `here `_. NAM `North American Mesoscale Forecast System `_. NAM generates multiple grids (or domains) of weather forecasts over the North American continent at various horizontal resolutions. Each grid contains data for dozens of weather parameters, including temperature, precipitation, lightning, and turbulent kinetic energy. NAM uses additional numerical weather models to generate high-resolution forecasts over fixed regions, and occasionally to follow significant weather events like hurricanes. diff --git a/doc/conf.py b/doc/conf.py index a490a0df4d..22d23e757c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -36,9 +36,18 @@ numfig = True -nitpick_ignore = [('py:class', 'obj'),('py:class', - 'yaml.dumper.Dumper'),('py:class', - 'xml.etree.ElementTree'),('py:class', 'Basemap'),] +nitpick_ignore = [('py:class', 'obj'), + ('py:class', 'yaml.dumper.Dumper'), + ('py:class', 'xml.etree.ElementTree'), + ('py:class', 'Basemap'), + ('py:class', 'pandas.DataFrame'), + ('py:class', 'numpy.ndarray'), + ('py:class', 'pandas.Index'), + ('py:class', 'xarray.DataArray'), + ('py:class', 'netCDF4.Dataset'), + ('py:class', 'ESMF.Field'), + ('py:class', 'ESMF.Grid'), + ] # -- General configuration --------------------------------------------------- @@ -255,8 +264,19 @@ def setup(app): # -- Options for autodoc extension --------------------------------------- -autodoc_mock_imports = ["f90nml","cartopy","mpl_toolkits.basemap","fill_jinja_template", - "matplotlib","numpy","uwtools","mpl_toolkits","metplus", +autodoc_mock_imports = ["f90nml", + "cartopy", + "mpl_toolkits.basemap", + "fill_jinja_template", + "matplotlib", + "numpy", + "uwtools", + "mpl_toolkits", + "metplus", + "netCDF4", + "pandas", + "xarray", + "ESMF", ] logger = logging.getLogger(__name__) diff --git a/doc/requirements.in b/doc/requirements.in index 75a70ab416..b38adfa03d 100644 --- a/doc/requirements.in +++ b/doc/requirements.in @@ -1,3 +1,3 @@ -sphinx>=7.4.0 +sphinx==7.4.7 sphinx_rtd_theme sphinxcontrib-bibtex diff --git a/modulefiles/build_odin_intel.lua b/modulefiles/build_odin_intel.lua deleted file mode 100644 index 40c3ada501..0000000000 --- a/modulefiles/build_odin_intel.lua +++ /dev/null @@ -1,54 +0,0 @@ -help([[ -This module loads libraries for building the UFS SRW App on -the NSSL machine Odin using Intel -]]) - -whatis([===[Loads libraries needed for building the UFS SRW App on Odin ]===]) - -prepend_path("PATH","/home/yunheng.wang/tools/cmake-3.23.0-rc2/bin") -setenv("CMAKE","/home/yunheng.wang/tools/cmake-3.23.0-rc2/bin/cmake") - -load("hpc/1.2.0") -load("hpc-intel") -load("hpc-cray-mpich") - ---load("srw_common") - -load("jasper") -load("zlib") -load("png") - ---load("cray-hdf5") ---load("cray-netcdf") -load("esmf") -load("fms") - -load("bacio") -load("crtm") -load("g2") -load("g2tmpl") -load("ip") -load("sp") -load("w3nco") -load("upp") - -load("gftl-shared") -load("yafyaml") -load("mapl") - -load("gfsio") -load("landsfcutil") -load("nemsio") -load("nemsiogfs") -load("sfcio") -load("sigio") -load("w3emc") -load("wgrib2") - -setenv("FC", "ftn") - -setenv("CMAKE_C_COMPILER","cc") -setenv("CMAKE_CXX_COMPILER","CC") -setenv("CMAKE_Fortran_COMPILER","ftn") -setenv("CMAKE_Platform","odin.intel") - diff --git a/modulefiles/wflow_odin.lua b/modulefiles/wflow_odin.lua deleted file mode 100644 index be3f9607e8..0000000000 --- a/modulefiles/wflow_odin.lua +++ /dev/null @@ -1,35 +0,0 @@ -help([[ -This module loads python environement for running the UFS SRW App on -the NSSL machine Odin -]]) - -whatis([===[Loads libraries needed for running the UFS SRW App on Odin ]===]) - - - -if mode() == "load" then - -- >>> conda initialize >>> - -- !! Contents within this block are managed by 'conda init' !! - local shell=myShellType() - local conda_path="/scratch/software/Odin/python/anaconda2" - local conda_file - if shell == "csh" then - conda_file=pathJoin(conda_path,"conda.csh") - else - conda_file=pathJoin(conda_path,"conda.sh") - end - - local exit_code = os.execute('test -f'..conda_file) - if exit_code == 0 then - local mcmd="source " .. conda_file - execute{cmd=mcmd, modeA={"load"}} - else - prepend_path("PATH", pathJoin(conda_path,"bin")) - end - -- <<< conda initialize <<< - - LmodMsgRaw([===[Please do the following to activate conda: - > conda config --set changeps1 False - > conda activate workflow_tools - ]===]) -end diff --git a/ush/smoke_dust_add_smoke.py b/ush/smoke_dust_add_smoke.py index 64229d7e36..5d3ee7ef6b 100755 --- a/ush/smoke_dust_add_smoke.py +++ b/ush/smoke_dust_add_smoke.py @@ -23,6 +23,9 @@ def populate_data(data: np.ndarray, target_shape: Tuple) -> np.ndarray: def main() -> None: + """ + Main entrypoint for generating smoke/dust initial conditions. + """ # File paths source_file = "fv_tracer.res.tile1.nc" target_file = "gfs_data.tile7.halo0.nc" diff --git a/ush/valid_param_vals.yaml b/ush/valid_param_vals.yaml index 84e6d093d9..c310eb1e00 100644 --- a/ush/valid_param_vals.yaml +++ b/ush/valid_param_vals.yaml @@ -4,7 +4,7 @@ valid_vals_RUN_ENVIR: ["nco", "community"] valid_vals_VERBOSE: [True, False] valid_vals_DEBUG: [True, False] -valid_vals_MACHINE: ["HERA", "WCOSS2", "ORION", "HERCULES", "JET", "ODIN", "CHEYENNE", "DERECHO", "STAMPEDE", "LINUX", "MACOS", "NOAACLOUD", "SINGULARITY", "GAEA", "GAEA-C6"] +valid_vals_MACHINE: ["HERA", "WCOSS2", "ORION", "HERCULES", "JET", "DERECHO", "LINUX", "MACOS", "NOAACLOUD", "SINGULARITY", "GAEA", "GAEA-C6"] valid_vals_SCHED: ["slurm", "pbspro", "lsf", "lsfcray", "none"] valid_vals_FCST_MODEL: ["ufs-weather-model"] valid_vals_WORKFLOW_MANAGER: ["rocoto", "ecflow", "none"]