diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index eeba7bc..6cd7e77 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -17,8 +17,8 @@ jobs: name: Documentation runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@v6 + - uses: actions/setup-python@v6 with: python-version: '3.8' - name: Install dependencies @@ -26,12 +26,12 @@ jobs: python -m pip install --upgrade -r docs/requirements.txt - name: Build Documentation run: ./.github/jobs/build_documentation.sh - - uses: actions/upload-artifact@v4 + - uses: actions/upload-artifact@v7 if: always() with: name: i-wrf_documentation path: artifact/documentation - - uses: actions/upload-artifact@v4 + - uses: actions/upload-artifact@v7 if: failure() with: name: documentation_warnings.log diff --git a/docs/Users_Guide/use-cases/lulc/common/metplus.rst b/docs/Users_Guide/use-cases/lulc/common/metplus.rst new file mode 100644 index 0000000..ed2ec1e --- /dev/null +++ b/docs/Users_Guide/use-cases/lulc/common/metplus.rst @@ -0,0 +1,66 @@ + +.. dropdown:: Run METplus + + .. dropdown:: Define Environment Variables for METplus + + Set environment variables to define paths and Docker image names:: + + METPLUS_IMAGE=ncar/iwrf-metplus:latest + OBS_DATA_VOL=lulc-input-obs-d03 + OBS_DATA_IMAGE=ncar/iwrf-data:${OBS_DATA_VOL}.docker + METPLUS_OUTPUT=~/metplus_out + METPLUS_CONFIG_DIR=~/i-wrf/use_cases/Land_Use_Land_Cover/METplus + PLOT_SCRIPT_DIR=~/i-wrf/use_cases/Land_Use_Land_Cover/Visualization + + The path to the WRF data to be read into METplus depends on how WRF was + run in the previous steps. + Set the **WRF_TOP_DIR** environment variable using one of the following approaches: + + If the Control simulation was run, set:: + + WRF_TOP_DIR=${WRF_OUTPUT}/ctl + + If the DFW 4x simulation was run, set:: + + WRF_TOP_DIR=${WRF_OUTPUT}/dfw4x + + If the WRF simulation was not run and the output was obtained via Ceph, set:: + + WRF_TOP_DIR=~/lulc_full_output + + + .. dropdown:: Get METplus Docker Images + + The METplus software and observation data are both available on DockerHub. + Run commands to pull the images and create the Docker data volume:: + + sudo docker pull ${METPLUS_IMAGE} + sudo docker pull ${OBS_DATA_IMAGE} + sudo docker create --name ${OBS_DATA_VOL} ${OBS_DATA_IMAGE} + + .. dropdown:: Run METplus Verification + + The LULC use case includes verification for two meteorological variables: + accumulated precipitation and radar reflectivity. + Each verification is run separately using its own METplus configuration file. + Run the accumulated precipitation verification:: + + docker run --rm -it \ + --volumes-from ${OBS_DATA_VOL} \ + -v ${METPLUS_CONFIG_DIR}:/config \ + -v ${PLOT_SCRIPT_DIR}:/plot_scripts \ + -v ${WRF_TOP_DIR}:/data/input/wrf \ + -v ${METPLUS_OUTPUT}:/data/output ${METPLUS_IMAGE} \ + /metplus/METplus/ush/run_metplus.py /config/GridStat_apcp_lulc.conf \ + config.FCST_PCP_COMBINE_INPUT_TEMPLATE="wrfout_d03_{valid?fmt=%Y-%m-%d_%H:%M}:*" + + Run the reflectivity verification:: + + docker run --rm -it \ + --volumes-from ${OBS_DATA_VOL} \ + -v ${METPLUS_CONFIG_DIR}:/config \ + -v ${PLOT_SCRIPT_DIR}:/plot_scripts \ + -v ${WRF_TOP_DIR}:/data/input/wrf \ + -v ${METPLUS_OUTPUT}:/data/output ${METPLUS_IMAGE} \ + /metplus/METplus/ush/run_metplus.py /config/GridStat_refc_lulc.conf \ + config.FCST_GRID_STAT_INPUT_TEMPLATE="wrfout_d03_{valid?fmt=%Y-%m-%d_%H:%M}:*" diff --git a/docs/Users_Guide/use-cases/lulc/jetstream2.rst b/docs/Users_Guide/use-cases/lulc/jetstream2.rst index fbb262f..c860d8b 100644 --- a/docs/Users_Guide/use-cases/lulc/jetstream2.rst +++ b/docs/Users_Guide/use-cases/lulc/jetstream2.rst @@ -134,3 +134,20 @@ to secure access to and log in to Jetstream2. df -h ${mountPoint} The full output should be in ``/home/exouser/lulc_full_output``. + + .. include:: lulc/common/metplus.rst + + .. dropdown:: View the Plotted Simulation Results + + The METplus container also plots the results of the simulation, outputting them as PNG images. + To view these images: + + * Find the desktop shortcut "Files" on the left side of the desktop and click it to open a file browser. + * Double-click on the following folders in order: metplus_out, met_plot, and either apcp or refc. + * Double-click on the image files in the folder, which opens an image viewing application. + * Click the Maximize button in the upper right to increase the viewer to full size. + * Click the button in the middle of the right side of the image to advance to the next image. + + When you are finished running simulations and viewing their results, + you can close the web browser tab containing your Web Desktop. + Then, return to the Exosphere dashboard to manage your instance so it does not incur further charges. diff --git a/docs/Users_Guide/use-cases/lulc/red-cloud.rst b/docs/Users_Guide/use-cases/lulc/red-cloud.rst index 61a6866..6efb1bd 100644 --- a/docs/Users_Guide/use-cases/lulc/red-cloud.rst +++ b/docs/Users_Guide/use-cases/lulc/red-cloud.rst @@ -138,3 +138,20 @@ to secure access to and log in to Red Cloud. df -h ${mountPoint} The full output should be in ``/home/ubuntu/lulc_full_output``. + + .. include:: lulc/common/metplus.rst + + .. dropdown:: View the Plotted Simulation Results + + The METplus container also plots the results of the simulation, outputting them as PNG images. + To view these images: + + * Disconnect from the instance and reconnect using SSH with X11 forwarding enabled by running ``ssh -X ubuntu@``. The ``-X`` option enables X11 forwarding, which allows images to be displayed on your local screen. Note that you must also have an X server running on your local machine (XQuartz on macOS or Xming on Windows). + * Install the ``feh`` image viewer on the instance by running ``sudo apt update`` followed by ``sudo apt install feh``. This installation only needs to be done once. + * Navigate to the plots folder: ``cd ~/metplus_out/met_plot/apcp`` or ``cd ~/metplus_out/met_plot/refc``. + * Open all the images in the folder by running ``feh .``. + * Press the right arrow key to advance to the next image or the left arrow key to go back. + * Press ``q`` to quit the viewer. + +Refer back to the **Managing a Red Cloud Instance** section of the :ref:`compute-platform-red-cloud` +instructions to avoid unneccessary computing costs. \ No newline at end of file diff --git a/docs/Users_Guide/use-cases/matthew/red-cloud.rst b/docs/Users_Guide/use-cases/matthew/red-cloud.rst index bb3cd70..6b65cde 100644 --- a/docs/Users_Guide/use-cases/matthew/red-cloud.rst +++ b/docs/Users_Guide/use-cases/matthew/red-cloud.rst @@ -144,7 +144,18 @@ and then pasted into your web shell by right-clicking. These files contain tabular output that can be viewed in a text editor. Turn off word wrapping for better viewing. Refer to the MET User's Guide for more information about the `Point-Stat output `_. - In the near future, this exercise will be extended to include instructions to visualize the results. + + .. dropdown:: View the Plotted Simulation Results + + The METplus container also plots the results of the simulation, outputting them as PNG images. + To view these images: + + * Disconnect from the instance and reconnect using SSH with X11 forwarding enabled by running ``ssh -X ubuntu@``. The ``-X`` option enables X11 forwarding, which allows images to be displayed on your local screen. Note that you must also have an X server running on your local machine (XQuartz on macOS or Xming on Windows). + * Install the ``feh`` image viewer on the instance by running ``sudo apt update`` followed by ``sudo apt install feh``. This installation only needs to be done once. + * Navigate to the plots folder: ``cd ~/metplus_out/wrf/20161006_00/plots``. + * Open all the images in the folder by running ``feh .``. + * Press the right arrow key to advance to the next image or the left arrow key to go back. + * Press ``q`` to quit the viewer. Refer back to the **Managing a Red Cloud Instance** section of the :ref:`compute-platform-red-cloud` instructions to avoid unneccessary computing costs. diff --git a/use_cases/Land_Use_Land_Cover/METplus/GridStat_apcp_lulc.conf b/use_cases/Land_Use_Land_Cover/METplus/GridStat_apcp_lulc.conf index fbf4d25..c4ca8d1 100644 --- a/use_cases/Land_Use_Land_Cover/METplus/GridStat_apcp_lulc.conf +++ b/use_cases/Land_Use_Land_Cover/METplus/GridStat_apcp_lulc.conf @@ -169,7 +169,7 @@ OBS_PCP_COMBINE_METHOD = ADD OBS_PCP_COMBINE_INPUT_DATATYPE = NETCDF OBS_PCP_COMBINE_INPUT_ACCUMS = 10M -OBS_PCP_COMBINE_INPUT_NAMES = i-wrf/use_cases/Land_Use_Land_Cover/METplus/read_lulc_radar_obs.py {OBS_PCP_COMBINE_INPUT_DIR}/RADAR_DFW22_N1P_20170703_d03_2017Jul03_2017Jul05.nc accum {valid?fmt=%Y%m%d_%H%M} +OBS_PCP_COMBINE_INPUT_NAMES = /config/read_lulc_radar_obs.py {OBS_PCP_COMBINE_INPUT_DIR}/RADAR_DFW22_N1P_20170703_d03_2017Jul03_2017Jul05.nc accum {valid?fmt=%Y%m%d_%H%M} OBS_PCP_COMBINE_OUTPUT_ACCUM = 1H OBS_PCP_COMBINE_OUTPUT_NAME = APCP diff --git a/use_cases/Land_Use_Land_Cover/METplus/GridStat_refc_lulc.conf b/use_cases/Land_Use_Land_Cover/METplus/GridStat_refc_lulc.conf index 72c919d..24eed6e 100644 --- a/use_cases/Land_Use_Land_Cover/METplus/GridStat_refc_lulc.conf +++ b/use_cases/Land_Use_Land_Cover/METplus/GridStat_refc_lulc.conf @@ -62,7 +62,7 @@ FCST_VAR1_NAME = REFD_MAX FCST_VAR1_LEVELS = (0,*,*) FCST_VAR1_THRESH = ge20, ge30, ge40, ge50 -OBS_VAR1_NAME = i-wrf/use_cases/Land_Use_Land_Cover/METplus/read_lulc_radar_obs.py {OBS_GRID_STAT_INPUT_DIR}/RADAR_DFW22_NCR_20170703_d03_2017Jul03_2017Jul05.nc refl {valid?fmt=%Y%m%d_%H%M} +OBS_VAR1_NAME = /config/read_lulc_radar_obs.py {OBS_GRID_STAT_INPUT_DIR}/RADAR_DFW22_NCR_20170703_d03_2017Jul03_2017Jul05.nc refl {valid?fmt=%Y%m%d_%H%M} OBS_VAR1_THRESH = ge20, ge30, ge40, ge50