diff --git a/doc/UsersGuide/source/CAPE2020.rst b/doc/UsersGuide/source/CAPE2020.rst new file mode 100644 index 0000000000..2cc065da8f --- /dev/null +++ b/doc/UsersGuide/source/CAPE2020.rst @@ -0,0 +1,90 @@ +.. role:: raw-html(raw) + :format: html + +.. _cape-2020: + +==================== +July 2020 CAPE Case +==================== + +The July 2020 CAPE case is an atmosphere-only forecast run at C48 resolution with 127 vertical levels. It is set to run a 24-hour forecast from 2020-07-23 at 0z using the `FV3_GFS_v16 `_ physics suite and default values from the WM's `default_vars.sh `_ ``export_fv3_v16`` function. + +The original July 2020 CAPE case illustrated a shortcoming of the Global Forecast System (GFS) v16 --- low Convective Available Potential Energy (CAPE) predictions during summertime (:cite:t:`SunEtAl2024`). :cite:t:`SunEtAl2024` (2024) used this case study to investigate the low CAPE bias in the GFS and determined that "the GFS simulates smaller surface latent heat flux and larger surface sensible heat flux than the observations" due to "slightly drier-than-observed soil moisture" within the offline Global Data Assimilation System (GDAS) initial conditions used in the study. This resulted in less latent heat and moisture being fed back to the lower levels of the atmosphere and ultimately changed the overall vertical profile of the atmosphere, which lowered CAPE values relative to the older GFS v15.2. + +The UFS WM and its subcomponents have undergone signficant changes since the original July 2020 CAPE case study was posted and since :cite:t:`SunEtAl2024`'s experiment, so the current GFS v16 CAPE bias may have shifted. However, users may still wish to run this case and then experiment with different (potentially user-generated) initial conditions, a coupled land surface model (LSM), or other factors to explore factors that improve or worsen CAPE bias. Additionally, :cite:t:`SunEtAl2024`'s findings only apply to this case study, so users may wish to expand their research to include other warm-season cases. + +============================================ +Obtaining Data for the July 2020 CAPE Case +============================================ + +.. include:: ./doc-snippets/hsd_data.rst + +User-Generated Data +--------------------- + +Users can enable the WM to run using GFS initial conditions (ICs) from the UFS Case Studies page. + +.. _run-cape: + +================================= +Running the July 2020 CAPE Case +================================= + +This section explains how to run the July 2020 CAPE case described above using the ``ufs-test.sh`` script. + +Clone the Repository +-------------------- + +.. include:: ./doc-snippets/clone_hsd.rst + +Machine Configuration +----------------------- + +.. include:: ./doc-snippets/hsd_machine_config.rst + +.. _cape-config: + +Test Configuration +---------------------- + +The July 2020 CAPE case can be run as-is without adjusting the configuration. + +Baseline Configuration +---------------------- + +.. include:: ./doc-snippets/hsd_baseline_config.rst + +Running Tests +------------- + +.. include:: ./doc-snippets/hsd_run_tests.rst + +Examples +^^^^^^^^^^ + +A user with access to the ``epic`` account can run the ``2020_CAPE`` test case with the ``intel`` compiler on ``Hera``, ``Orion``, or ``Gaea`` using the following command: + +.. code-block:: console + + ./ufs_test.sh -a epic -s -c -k -r -n "2020_CAPE intel" + +Running Multiple Cases +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ./doc-snippets/hsd_run_multiple.rst + +.. _check-results: + +Checking Results +----------------- + +.. include:: ./doc-snippets/hsd_check_results.rst + +For example, to monitor progress or check results for the ``2020_CAPE_intel`` case, run: + +.. code-block:: console + + tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/err + tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/out + +.. include:: ./doc-snippets/hsd_notes.rst \ No newline at end of file diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst deleted file mode 100644 index 89535c51b3..0000000000 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. role:: raw-html(raw) - :format: html - -.. _hsd: - -******************************************** -Hierarchical System Development (HSD) Cases -******************************************** - -Hierarchical System Development is the ability to engage in development and testing at multiple levels of complexity in numerical weather prediction (NWP) software (such as the :term:`UFS`). It typically includes multiple entry points into development (e.g., atmospheric physics, ocean and ice dynamics, or data assimilation for land models and other earth system components), and it can include both operationally relevant and idealized configurations. - -Although the UFS Weather Model (WM) can be run in any of several configurations, from a single-component atmospheric -model to a fully coupled model with multiple earth system components (e.g., atmosphere, ocean, sea-ice, land, mediator), -this chapter documents just a few of the cases designed to support hierarchical system development (HSD) within the UFS. - -Currently, users can find information on: - -* :ref:`Running the HSD cases using ufs_test.sh ` and -* Two HSD cases: - - * The :ref:`July 2020 CAPE Case ` - * The :ref:`Baroclinic Instability Case ` - -For a full list of supported WM configurations, view the `rt.conf `_ file. - -.. attention:: - - This chapter is a work in progress. There are a multitude of options for configuring the UFS WM, - and this chapter merely details a few supported configurations. It will be expanded over time - to include a wide variety of idealized test cases for use in research and testing. - - -.. _cape-2020: - -==================== -July 2020 CAPE Case -==================== - -The July 2020 CAPE case is an atmosphere-only forecast run at C48 resolution with 127 vertical levels. It is set to run a 24-hour forecast from 2020-07-23 at 0z using the `FV3_GFS_v16 `_ physics suite and default values from the WM's `default_vars.sh `_ ``export_fv3_v16`` function. - -The original July 2020 CAPE case illustrated a shortcoming of the Global Forecast System (GFS) v16 --- low Convective Available Potential Energy (CAPE) predictions during summertime (:cite:t:`SunEtAl2024`). :cite:t:`SunEtAl2024` (2024) used this case study to investigate the low CAPE bias in the GFS and determined that "the GFS simulates smaller surface latent heat flux and larger surface sensible heat flux than the observations" due to "slightly drier-than-observed soil moisture" within the offline Global Data Assimilation System (GDAS) initial conditions used in the study. This resulted in less latent heat and moisture being fed back to the lower levels of the atmosphere and ultimately changed the overall vertical profile of the atmosphere, which lowered CAPE values relative to the older GFS v15.2. - -The UFS WM and its subcomponents have undergone signficant changes since the original July 2020 CAPE case study was posted and since :cite:t:`SunEtAl2024`'s experiment, so the current GFS v16 CAPE bias may have shifted. However, users may still wish to run this case and then experiment with different (potentially user-generated) initial conditions, a coupled land surface model (LSM), or other factors to explore factors that improve or worsen CAPE bias. Additionally, :cite:t:`SunEtAl2024`'s findings only apply to this case study, so users may wish to expand their research to include other warm-season cases. - -.. _baroclinic-wave: - -============================ -Baroclinic Instability Case -============================ - -The UFS WM baroclinic wave case adapts the test outlined in :cite:t:`Jablonowski&Williamson2006` (2006). This test is designed to evaluate the accuracy of various atmospheric models in simulating a baroclinic wave, which commonly forms in the Northern Hemisphere and influences weather patterns. This test aims to assess how well "dry dynamical cores," the foundational components of weather and climate models that handle air movement and temperature changes, perform in idealized conditions. - -The simulation sets the model's atmosphere to an initial steady state, designed to be a simple, realistic representation of atmospheric conditions using the adiabatic (no heat exchange) and inviscid (no friction) primitive equations. The test first checks whether each model can maintain this steady, zonal (west-to-east) state without developing any unintended changes. After verifying this, the next step is to introduce a small disturbance, or perturbation, which triggers the growth of a baroclinic wave. The wave then evolves over several simulated days, allowing the researchers to observe how accurately different models handle the wave's development and movement. - -This test provides a standard way to assess how different atmospheric models handle the development of baroclinic waves. The results help identify which models are more accurate and can serve as benchmarks for model improvement, ultimately contributing to better simulations of atmospheric behavior in weather and climate predictions. - -In the UFS WM, the idealized baroclinic wave test case is an atmosphere-only, :term:`dycore`-only forecast run at C192 resolution with 127 vertical levels. It uses default values from the WM's ``export_fv3`` function, along with default values for a tiled grid namelist (from ``export_tiled``) and for the `Unified Gravity Wave Physics version 1 `_ (from ``export_ugwpv1``). These initial values are all set based on values from `default_vars.sh `_. - -The test is set to run a dynamics-only 24-hour forecast from 2019-12-03 at 0z. However, it is recommended that users modify the case to run it as a 5-10 day forecast by setting the forecast length (``FHMAX``) to 120-240 hours in the test file (see :numref:`Section %s ` for instructions). Users will also need to update ``OUTPUT_FH`` accordingly. - -.. _hsd-data: - -============================= -Obtaining Data for HSD Cases -============================= - -Data for the HSD cases is already staged on Tier-1 platforms at the ``INPUTROOT_*`` locations listed in `baseline_setup.yaml `_. However, users on any platform can download the data directly from the `HTF data bucket ` using ``wget``. - -.. code-block:: console - - wget https://noaa-ufs-htf-pds.s3.amazonaws.com/develop-20241025/HSD_INPUT_DATA/HSD_INPUT_DATA.tar.gz - tar xvfz HSD_INPUT_DATA.tar.gz - -.. _ufs-test: - -============================================ -Running the HSD Cases Using ``ufs_test.sh`` -============================================ - -This section explains how to run the idealized cases described above using the ``ufs-test.sh`` script. - -Clone the Repository --------------------- - -To start, recursively clone the repository: - -.. code-block:: console - - git clone --recursive -b develop https://github.com/ufs-community/ufs-weather-model.git - cd ufs-weather-model - -After cloning, users may save (or "export") the path to the UFS WM in an environment variable: - -.. code-block:: console - - export UFS_WM=$PWD - -Although this step is optional, users may find it convenient when navigating between directories. This documentation will use ``${UFS_WM}`` to refer to the path to the ``ufs-weather-model`` directory, but users may choose to type out the full path instead. - -.. _machine-config: - -Machine Configuration ------------------------ - -The HSD cases are configured to be run on NOAA Tier-1 platforms, and the configuration files for each platform are located at: - -.. code-block:: console - - ${UFS_WM}/tests-dev/machine_config/machine_.config - -where ```` corresponds to the name of the platform. These configuration files load the necessary Python and Rocoto modules for each platform. Users generally do not need to make any changes to these files. - -.. _test-config: - -Test Configuration ----------------------- - -The July 2020 CAPE case can be run as-is without adjusting the configuration. However, it is recommended that users adjust certain values in the baroclinic wave case. Currently, the forecast length (``FHMAX``) is set to 24 hours, but it is recommended that users run the case for 5 or 10 days (120 or 240 hours). To do this, open ``${UFS_WM}/tests-dev/test_cases/tests/baroclinic_wave`` using ``vi``/``vim`` or a code editor. Then, add ``FHMAX`` and update ``OUTPUT_FH`` to extend by increments of 6 to the new ``FHMAX``. - -.. code-block:: console - - export FHMAX=120 # (or 240) - export OUTPUT_FH='0 6 12 18 24 30 36 42 48 54 60 66 72 78 84 90 96 102 108 114 120' - -In general, it is preferable to make ``FHMAX`` a multiple of 24. - -.. _baseline-config: - -Baseline Configuration ----------------------- - -Users may need to modify the baseline configuration file (``${UFS_WM}/tests-dev/baseline_setup.yaml``), which contains details on the location of staged input data, user-specific output directories, and batch job scheduling. The following variables are of particular importance: - -* ``dprefix``: Set this value to an existing directory where the user has write permissions. -* ``STMP``: Directory for baseline test output (typically ``${dprefix}/stmp4``) -* ``PTMP``: Directory for runtime files (typically ``${dprefix}/stmp2``) - -.. _run-tests: - -Running Tests -------------- - -Launch tests from the ``${UFS_WM}/tests-dev`` directory with the following command: - -.. code-block:: console - - cd tests-dev - ./ufs_test.sh -a [-s] [-c] -k -r -n " " - -where: - -* ````: Account/project number for batch jobs. -* ````: Name of the test case (e.g., ``2020_CAPE`` or ``baroclinic_wave``). -* ````: Compiler used for the tests (``intel`` or ``gnu``). - -**Command-line Options:** - -- ``-s``: Syncs scripts from ``./ufs-wm/tests`` to ``./ufs-wm/tests-dev`` (only required on the first run) -- ``-c``: Creates a new baseline (necessary until idealized case baselines are staged in the ``UFS_WM_RT`` directory). -- ``-k``: Keeps runtime directories after test completion -- ``-r``: Uses Rocoto workflow manager -- ``-n``: Runs a single test case - -.. COMMENT: What is the -m option? It should be listed here. - -.. note:: - - After the initial run of ``ufs_test.sh`` with the ``-s`` option, users do not need to use ``-s`` again. - -Examples -^^^^^^^^^^ - -A user with access to the ``epic`` account can run the ``2020_CAPE`` test case with the ``intel`` compiler on ``Hera``, ``Orion``, or ``Gaea`` using the following command: - -.. code-block:: console - - ./ufs_test.sh -a epic -s -c -k -r -n "2020_CAPE intel" - -For the ``baroclinic_wave`` test case, which takes longer, the same user would run: - -.. code-block:: console - - ./ufs_test.sh -a epic -s -c -k -r -n "baroclinic_wave intel" - -Running Multiple Cases -^^^^^^^^^^^^^^^^^^^^^^^^ - -To run multiple cases at once, copy ``test_cases.yaml`` from the test cases directory and use the ``-l`` argument: - -.. code-block:: console - - cp ${UFS_WM}/tests-dev/test_cases/test_cases.yaml ${UFS_WM}/tests-dev/ - ./ufs_test.sh -a epic -s -c -k -r -l test_cases.yaml - -.. _check-results: - -Checking Results ------------------ - -When the test case finishes running, users should see console output that includes a ``SUCCESS`` message: - -.. code-block:: console - :emphasize-lines: 2 - - Performing Cleanup... - REGRESSION TEST RESULT: SUCCESS - + echo 'ufs_test.sh finished' - ufs_test.sh finished - + cleanup - ++ awk '{print $2}' - + PID_LOCK=2133541 - + [[ 2133541 == \2\1\3\3\5\4\1 ]] - + rm -rf /scratch2/NAGAPE/epic/Gillian.Petro/ufs-weather-model/tests-dev/lock - + [[ false == true ]] - + trap 0 - + exit - -Compilation and model run directories can be accessed in the local repository via the ``run_dir`` softlink, which points to the actual ``FV3_RT`` directory. Each test generates ``atm*.nc`` and ``sfc*.nc`` files at specified forecast hour intervals. - -Users can view progress of compile or model run phases by using the ``tail -f `` command or ``vi``/``vim`` on the ``err`` or ``out`` files in the ``run_dir/compile*`` or ``run_dir/`` directories. For example, to monitor progress or check results for the ``2020_CAPE_intel`` case, run: - -.. code-block:: console - - tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/err - tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/out - -.. note:: - - Once the tests run successfully with the ``-c`` option (baseline created), users can compare future test results with the newly created baseline using ``-m`` instead of ``-c``. - -For further test management, users may save the test directory location in an environment variable: - -.. code-block:: console - - export UFS_WM_TEST=/path/to/expt_dirs/ufs_test diff --git a/doc/UsersGuide/source/HSD.rst b/doc/UsersGuide/source/HSD.rst new file mode 100644 index 0000000000..2382a56944 --- /dev/null +++ b/doc/UsersGuide/source/HSD.rst @@ -0,0 +1,33 @@ +.. role:: raw-html(raw) + :format: html + +.. _hsd: + +******************************************** +Hierarchical System Development (HSD) Cases +******************************************** + +Hierarchical System Development is the ability to engage in development and testing at multiple levels of complexity in numerical weather prediction (NWP) software (such as the :term:`UFS`). It typically includes multiple entry points into development (e.g., atmospheric physics, ocean and ice dynamics, or data assimilation for land models and other earth system components), and it can include both operationally relevant and idealized configurations. + +Although the UFS Weather Model (WM) can be run in any of several configurations, from a single-component atmospheric +model to a fully coupled model with multiple earth system components (e.g., atmosphere, ocean, sea-ice, land, mediator), +this chapter documents just a few of the cases designed to support hierarchical system development (HSD) within the UFS. + +.. toctree:: + :maxdepth: 3 + + CAPE2020 + baroclinic_wave + +Currently, users can find information on running the following HSD cases: + + * The :ref:`July 2020 CAPE Case ` + * The :ref:`Baroclinic Instability Case ` + +For a full list of supported WM configurations, view the `rt.conf `_ file. + +.. attention:: + + This chapter is a work in progress. There are a multitude of options for configuring the UFS WM, + and this chapter merely details a few supported configurations. It will be expanded over time + to include a wide variety of idealized test cases for use in research and testing. diff --git a/doc/UsersGuide/source/baroclinic_wave.rst b/doc/UsersGuide/source/baroclinic_wave.rst new file mode 100644 index 0000000000..99ed13877d --- /dev/null +++ b/doc/UsersGuide/source/baroclinic_wave.rst @@ -0,0 +1,94 @@ +.. role:: raw-html(raw) + :format: html + +.. _baroclinic-wave: + +============================ +Baroclinic Instability Case +============================ + +The UFS WM baroclinic wave case adapts the test outlined in :cite:t:`Jablonowski&Williamson2006` (2006). This test is designed to evaluate the accuracy of various atmospheric models in simulating a baroclinic wave, which commonly forms in the Northern Hemisphere and influences weather patterns. This test aims to assess how well "dry dynamical cores," the foundational components of weather and climate models that handle air movement and temperature changes, perform in idealized conditions. + +The simulation sets the model's atmosphere to an initial steady state, designed to be a simple, realistic representation of atmospheric conditions using the adiabatic (no heat exchange) and inviscid (no friction) primitive equations. The test first checks whether each model can maintain this steady, zonal (west-to-east) state without developing any unintended changes. After verifying this, the next step is to introduce a small disturbance, or perturbation, which triggers the growth of a baroclinic wave. The wave then evolves over several simulated days, allowing the researchers to observe how accurately different models handle the wave's development and movement. + +This test provides a standard way to assess how different atmospheric models handle the development of baroclinic waves. The results help identify which models are more accurate and can serve as benchmarks for model improvement, ultimately contributing to better simulations of atmospheric behavior in weather and climate predictions. + +In the UFS WM, the idealized baroclinic wave test case is an atmosphere-only, :term:`dycore`-only forecast run at C192 resolution with 127 vertical levels. It uses default values from the WM's ``export_fv3`` function, along with default values for a tiled grid namelist (from ``export_tiled``) and for the `Unified Gravity Wave Physics version 1 `_ (from ``export_ugwpv1``). These initial values are all set based on values from `default_vars.sh `_. + +The test is set to run a dynamics-only 24-hour forecast from 2019-12-03 at 0z. However, it is recommended that users modify the case to run it as a 5-10 day forecast by setting the forecast length (``FHMAX``) to 120-240 hours in the test file (see :numref:`Section %s ` for instructions). Users will also need to update ``OUTPUT_FH`` accordingly. + +============================= +Obtaining Data for HSD Cases +============================= + +.. include:: ./doc-snippets/hsd_data.rst + +.. _run-bw: + +================================== +Running the Baroclinic Wave Case +================================== + +This section explains how to run the baroclinic wave case described above using the ``ufs-test.sh`` script. + +Clone the Repository +-------------------- + +.. include:: ./doc-snippets/clone_hsd.rst + +Machine Configuration +----------------------- + +.. include:: ./doc-snippets/hsd_machine_config.rst + +.. _bw-config: + +Test Configuration +---------------------- + +It is recommended that users adjust certain values in the baroclinic wave case. Currently, the forecast length (``FHMAX``) is set to 24 hours, but it is recommended that users run the case for 5 or 10 days (120 or 240 hours). To do this, open ``${UFS_WM}/tests-dev/test_cases/tests/baroclinic_wave`` using ``vi``/``vim`` or a code editor. Then, add ``FHMAX`` and update ``OUTPUT_FH`` to extend by increments of 6 to the new ``FHMAX``. + +.. code-block:: console + + export FHMAX=120 # (or 240) + export OUTPUT_FH='0 6 12 18 24 30 36 42 48 54 60 66 72 78 84 90 96 102 108 114 120' + +In general, it is preferable to make ``FHMAX`` a multiple of 24. + +Baseline Configuration +---------------------- + +.. include:: ./doc-snippets/hsd_baseline_config.rst + +Running Tests +------------- + +.. include:: ./doc-snippets/hsd_run_tests.rst + +Example: +^^^^^^^^^ + +A user with access to the ``epic`` account can run the ``baroclinic_wave`` test case with the ``intel`` compiler on ``Hera``, ``Orion``, or ``Gaea`` using the following command: + +.. code-block:: console + + ./ufs_test.sh -a epic -s -c -k -r -n "baroclinic_wave intel" + +Running Multiple Cases +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ./doc-snippets/hsd_run_multiple.rst + +Checking Results +----------------- + +.. include:: ./doc-snippets/hsd_check_results.rst + +For example, to monitor progress or check results for the ``baroclinic_wave`` case, run: + +.. code-block:: console + + tail -f ${UFS_WM}/tests-dev/run_dir/baroclinic_wave/err + tail -f ${UFS_WM}/tests-dev/run_dir/baroclinic_wave/out + +.. include:: ./doc-snippets/hsd_notes.rst diff --git a/doc/UsersGuide/source/doc-snippets/clone_hsd.rst b/doc/UsersGuide/source/doc-snippets/clone_hsd.rst new file mode 100644 index 0000000000..4bbf6073fb --- /dev/null +++ b/doc/UsersGuide/source/doc-snippets/clone_hsd.rst @@ -0,0 +1,14 @@ +To start, recursively clone the repository: + +.. code-block:: console + + git clone --recursive -b develop https://github.com/ufs-community/ufs-weather-model.git + cd ufs-weather-model + +After cloning, users may save (or "export") the path to the UFS WM in an environment variable: + +.. code-block:: console + + export UFS_WM=$PWD + +Although this step is optional, users may find it convenient when navigating between directories. This documentation will use ``${UFS_WM}`` to refer to the path to the ``ufs-weather-model`` directory, but users may choose to type out the full path instead. diff --git a/doc/UsersGuide/source/doc-snippets/hsd_baseline_config.rst b/doc/UsersGuide/source/doc-snippets/hsd_baseline_config.rst new file mode 100644 index 0000000000..0c3aeb8925 --- /dev/null +++ b/doc/UsersGuide/source/doc-snippets/hsd_baseline_config.rst @@ -0,0 +1,5 @@ +Users may need to modify the baseline configuration file (``${UFS_WM}/tests-dev/baseline_setup.yaml``), which contains details on the location of staged input data, user-specific output directories, and batch job scheduling. The following variables are of particular importance: + +* ``dprefix``: Set this value to an existing directory where the user has write permissions. +* ``STMP``: Directory for baseline test output (typically ``${dprefix}/stmp4``) +* ``PTMP``: Directory for runtime files (typically ``${dprefix}/stmp2``) diff --git a/doc/UsersGuide/source/doc-snippets/hsd_check_results.rst b/doc/UsersGuide/source/doc-snippets/hsd_check_results.rst new file mode 100644 index 0000000000..aa45c64ead --- /dev/null +++ b/doc/UsersGuide/source/doc-snippets/hsd_check_results.rst @@ -0,0 +1,38 @@ +When the test case finishes running, users should see console output that includes a ``SUCCESS`` message. FOr example: + +.. code-block:: console + :emphasize-lines: 2 + + Performing Cleanup... + REGRESSION TEST RESULT: SUCCESS + + echo 'ufs_test.sh finished' + ufs_test.sh finished + + cleanup + ++ awk '{print $2}' + + PID_LOCK=2133541 + + [[ 2133541 == \2\1\3\3\5\4\1 ]] + + rm -rf /scratch2/NAGAPE/epic/User.Name/ufs-weather-model/tests-dev/lock + + [[ false == true ]] + + trap 0 + + exit + +Compilation and model run directories can be accessed in the local repository via the ``run_dir`` softlink, which points to the actual ``FV3_RT`` directory. Each test generates ``atm*.nc`` and ``sfc*.nc`` files at specified forecast hour intervals. + +Users can view progress of compile or model run phases by using the ``tail -f `` command or ``vi``/``vim`` on the ``err`` or ``out`` files in the ``run_dir/compile*`` or ``run_dir/`` directories. + +For example, to monitor progress or check results for the ``2020_CAPE_intel`` case, run: + +.. code-block:: console + + tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/err + tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/out + +.. note:: + + Once the tests run successfully with the ``-c`` option (baseline created), users can compare future test results with the newly created baseline using ``-m`` instead of ``-c``. + +For further test management, users may save the test directory location in an environment variable: + +.. code-block:: console + + export UFS_WM_TEST=/path/to/expt_dirs/ufs_test diff --git a/doc/UsersGuide/source/doc-snippets/hsd_data.rst b/doc/UsersGuide/source/doc-snippets/hsd_data.rst new file mode 100644 index 0000000000..f3c890cb1e --- /dev/null +++ b/doc/UsersGuide/source/doc-snippets/hsd_data.rst @@ -0,0 +1,6 @@ +Data for the HSD cases is already staged on Tier-1 platforms at the ``INPUTROOT_*`` locations listed in `baseline_setup.yaml `_. However, users on any platform can download the data directly from the `HTF data bucket `_ using ``wget``. + +.. code-block:: console + + wget https://noaa-ufs-htf-pds.s3.amazonaws.com/develop-20241025/HSD_INPUT_DATA/HSD_INPUT_DATA.tar.gz + tar xvfz HSD_INPUT_DATA.tar.gz diff --git a/doc/UsersGuide/source/doc-snippets/hsd_machine_config.rst b/doc/UsersGuide/source/doc-snippets/hsd_machine_config.rst new file mode 100644 index 0000000000..02e7534bc8 --- /dev/null +++ b/doc/UsersGuide/source/doc-snippets/hsd_machine_config.rst @@ -0,0 +1,7 @@ +The HSD cases are configured to be run on NOAA Tier-1 platforms, and the configuration files for each platform are located at: + +.. code-block:: console + + ${UFS_WM}/tests-dev/machine_config/machine_.config + +where ```` corresponds to the name of the platform. These configuration files load the necessary Python and Rocoto modules for each platform. Users generally do not need to make any changes to these files. \ No newline at end of file diff --git a/doc/UsersGuide/source/doc-snippets/hsd_notes.rst b/doc/UsersGuide/source/doc-snippets/hsd_notes.rst new file mode 100644 index 0000000000..b279a9891c --- /dev/null +++ b/doc/UsersGuide/source/doc-snippets/hsd_notes.rst @@ -0,0 +1,9 @@ +.. note:: + + Once the tests run successfully with the ``-c`` option (baseline created), users can compare future test results with the newly created baseline using ``-m`` instead of ``-c``. + +For further test management, users may save the test directory location in an environment variable: + +.. code-block:: console + + export UFS_WM_TEST=/path/to/expt_dirs/ufs_test \ No newline at end of file diff --git a/doc/UsersGuide/source/doc-snippets/hsd_run_multiple.rst b/doc/UsersGuide/source/doc-snippets/hsd_run_multiple.rst new file mode 100644 index 0000000000..6d7aca5080 --- /dev/null +++ b/doc/UsersGuide/source/doc-snippets/hsd_run_multiple.rst @@ -0,0 +1,6 @@ +To run multiple cases at once, copy ``test_cases.yaml`` from the test cases directory and use the ``-l`` argument: + +.. code-block:: console + + cp ${UFS_WM}/tests-dev/test_cases/test_cases.yaml ${UFS_WM}/tests-dev/ + ./ufs_test.sh -a epic -s -c -k -r -l test_cases.yaml diff --git a/doc/UsersGuide/source/doc-snippets/hsd_run_tests.rst b/doc/UsersGuide/source/doc-snippets/hsd_run_tests.rst new file mode 100644 index 0000000000..e42e0479e1 --- /dev/null +++ b/doc/UsersGuide/source/doc-snippets/hsd_run_tests.rst @@ -0,0 +1,26 @@ +Launch tests from the ``${UFS_WM}/tests-dev`` directory with the following command: + +.. code-block:: console + + cd tests-dev + ./ufs_test.sh -a [-s] [-c] -k -r -n " " + +where: + +* ````: Account/project number for batch jobs. +* ````: Name of the test case (e.g., ``2020_CAPE`` or ``baroclinic_wave``). +* ````: Compiler used for the tests (``intel`` or ``gnu``). + +**Command-line Options:** + +- ``-s``: Syncs scripts from ``./ufs-wm/tests`` to ``./ufs-wm/tests-dev`` (only required on the first run) +- ``-c``: Creates a new baseline (necessary until idealized case baselines are staged in the ``UFS_WM_RT`` directory). +- ``-k``: Keeps runtime directories after test completion +- ``-r``: Uses Rocoto workflow manager +- ``-n``: Runs a single test case + +.. COMMENT: What is the -m option? It should be listed here. + +.. note:: + + After the initial run of ``ufs_test.sh`` with the ``-s`` option, users do not need to use ``-s`` again. \ No newline at end of file diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst index 01fb5c191b..290a9cfcc2 100644 --- a/doc/UsersGuide/source/index.rst +++ b/doc/UsersGuide/source/index.rst @@ -15,7 +15,7 @@ Welcome to the UFS Weather Model User's Guide BuildingAndRunning InputsOutputs RTConfigurations - CasesConfigurations + HSD modules ConfigParameters AutomatedTesting