From 7dc7eb0ee479b6e97c31906bfdc91be68dfc3f7f Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Mon, 21 Oct 2024 14:49:15 -0400 Subject: [PATCH 01/24] rm unmaintainable rt-specific config info --- doc/UsersGuide/source/Configurations.rst | 526 +--------------------- doc/UsersGuide/source/tables/rrfs-rts.csv | 11 - 2 files changed, 5 insertions(+), 532 deletions(-) delete mode 100644 doc/UsersGuide/source/tables/rrfs-rts.csv diff --git a/doc/UsersGuide/source/Configurations.rst b/doc/UsersGuide/source/Configurations.rst index 69d659ffa5..0d76dce392 100644 --- a/doc/UsersGuide/source/Configurations.rst +++ b/doc/UsersGuide/source/Configurations.rst @@ -6,14 +6,14 @@ .. _Configurations: -************************* -Configurations -************************* +******************************* +Regresson Test Configurations +******************************* 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, and -mediator). This chapter documents a few of the currently supported configurations. For a full list of -supported configurations, view the `rt.conf `__ file. +mediator). This chapter documents a few of the supported regression test (RT) configurations. For a full list of +supported RT configurations, view the `rt.conf `__ file. .. attention:: @@ -273,66 +273,6 @@ These tests use default values set in the ``export_fv3`` function of ``default_v The "Detailed Physics Parameters" column in :numref:`Table %s ` details physics settings that differ from both the ``default_vars.sh`` values and these ATMAERO-specific defaults. -.. _atmaero-rts: - -.. list-table:: *ATMAERO regression test descriptions* - :widths: 50 10 50 10 10 10 10 10 - :header-rows: 1 - - * - Test |nbsp| Name |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| - - Description - - Detailed |nbsp| Physics |nbsp| Parameters |nbsp| (see |nbsp| namelist |nbsp| options `here `__ |nbsp| for variable definitions) - - Start |nbsp| Date |nbsp| |nbsp| |nbsp| |nbsp| - - Fcst Length (hours) - - Output Grid - - Configuration Files - - Other - * - `atmaero_control_p8 `__ - - Compare global results for prognostic aerosols with previous trunk version - - **Set to FALSE:** LHEATSTRG :raw-html:`

` - **Set to TRUE:** ATMAERO default values only :raw-html:`

` - **Set to VALUE:** IAER=1011, DNATS=2 - - 2021-03-22 06:00:00 - - 24 - - OUTPUT_GRID=gaussian_grid :raw-html:`

` - **Grid Parameters**: INPES=${INPES_atmaero}, JNPES=${JNPES_atmaero}, NPZ=127, NPZP=128 - - FIELD_TABLE=field_table_thompson_noaero_tke_GOCART - DIAG_TABLE=diag_table_cpld.IN - INPUT_NML=ufs.configure.atmaero_esmf.IN - UFS_CONFIGURE=ufs.configure.atmaero.IN - FV3_RUN=control_run.IN - - RESTART_INTERVAL=12 -1 - * - `atmaero_control_p8_rad `__ - - Compare global results for prognostic aerosols with previous trunk version - - **Set to FALSE:** ATMAERO values only :raw-html:`

` - **Set to TRUE:** LHEATSTRG :raw-html:`

` - **Set to VALUE:** IAER=2011, DNATS=2 - - 2021-03-22 06:00:00 - - 24 - - OUTPUT_GRID=gaussian_grid :raw-html:`

` - **Grid Parameters**: NPZ=127, NPZP=128 - - FIELD_TABLE=field_table_thompson_noaero_tke_GOCART - DIAG_TABLE=diag_table_cpld.IN - INPUT_NML=cpld_control.nml.IN - UFS_CONFIGURE=ufs.configure.atmaero_esmf.IN - FV3_RUN=control_run.IN - - RESTART_INTERVAL=12 -1 - * - `atmaero_control_p8_rad_micro `__ - - Compare global results for prognostic aerosols with previous trunk version - - **Set to FALSE:** :raw-html:`

` - **Set to TRUE:** LHEATSTRG :raw-html:`

` - **Set to VALUE:** IAER=2011, DNATS=4 - - 2021-03-22 06:00:00 - - 24 - - OUTPUT_GRID=gaussian_grid :raw-html:`

` - **Grid Parameters**: NPZ=127, NPZP=128 - - FIELD_TABLE=field_table_thompson_noaero_tke_GOCART - DIAG_TABLE=diag_table_p8_gocart_micro - INPUT_NML=merra2_thompson.nml.IN - UFS_CONFIGURE=ufs.configure.atmaero_esmf.IN - FV3_RUN=control_run.IN - - RESTART_INTERVAL='12 -1' - ATMAQ ======= @@ -422,13 +362,6 @@ These tests use the default values set in the ``export_fv3``, ``export_rap_commo Current RRFS regression tests cover a wide variety of functionality and involve several physics tests. :numref:`Table %s ` (below) contains a selection of RTs for RRFS functionality. Blanks indicate that the value comes from the default setting file. These default values are listed in :numref:`Table %s ` above. -.. _rrfs-rts: - -.. csv-table:: *RRFS regression test descriptions* - :file: tables/rrfs-rts.csv - :widths: 20 20 30 50 10 10 10 - :header-rows: 1 - **Sample** ``CMAKE_FLAGS`` **Setting** .. code-block:: console @@ -533,7 +466,6 @@ These tests use the default values set in the ``export_fv3``, ``export_hafs``, ` ``export_hafs`` calls ``export_hafs_regional``, which calls ``export_hafs_datm_cdeps`` or ``export_hafs_docn_cdeps``, which calls ``export_fv3``. Values from ``export_fv3`` are set first, followed by values in ``export_hafs``, ``export_hafs_regional``, and then values in ``export_hafs_datm_cdeps`` or ``export_hafs_docn_cdeps``. - .. list-table:: *Default physics-related variables used in the HAFS configurations below* :widths: 10 50 :header-rows: 1 @@ -557,454 +489,6 @@ These tests use the default values set in the ``export_fv3``, ``export_hafs``, ` **Set to TRUE:** FV3, HAFS, DOCN_CDEPS :raw-html:`

` **Set to VALUE:** NTILES=1, ocn_model=docn, ocn_datamode=sstdata, pio_rearranger=box, DOCN_IN_CONFIGURE=docn_in, DOCN_STREAM_CONFIGURE=hafs_docn.streams.IN -.. _hafs-rts: - -.. list-table:: *HAFS regression test descriptions* - :widths: 50 10 30 50 10 10 10 10 10 - :header-rows: 1 - - * - Test |nbsp| Name |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| - - Description - - General Physics Parameters - - Detailed |nbsp| Physics |nbsp| Parameters |nbsp| (see |nbsp| namelist |nbsp| options `here `__ |nbsp| for variable definitions) - - Start |nbsp| Date |nbsp| |nbsp| |nbsp| |nbsp| - - Fcst Length (hours) - - Output Grid - - Configuration Files - - Other - * - `rhafs_global_1nest_atm `__ - - Compare HAFS global with 1 nest and atmosphere only results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=90 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, CPLOCN2ATM, NESTED :raw-html:`

` - **Set to VALUE:** - See ``export_hafs`` default values. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=global_latlon, OUTPUT_GRID_2=rotated_latlon :raw-html:`

` - **Grid Parameters**: INPES=4, JNPES=5, NPX=97, NPY=97, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=241, NPY_NEST02=241 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_global_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_global_multiple_4nests_atm `__ - - Compare HAFS global with 4 multiple nests and atmosphere only results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=90 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** WRITE_DOPOST, EXTERNAL_IC, NGGPS_IC, CPLOCN2ATM, NESTED :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs default values. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=global_latlon, OUTPUT_GRID_2=regional_latlon, OUTPUT_GRID_3=rotated_latlon, OUTPUT_GRID_4=rotated_latlon, OUTPUT_GRID_5=rotated_latlon :raw-html:`

` - **Grid Parameters**: INPES=4, JNPES=5, NPX=97, NPY=97, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=241, NPY_NEST02=241, INPES_NEST03=6, JNPES_NEST03=10, NPX_NEST03=241, NPY_NEST03=241, INPES_NEST04=6, JNPES_NEST04=10, NPX_NEST04=361, NPY_NEST04=361, INPES_NEST05=6, JNPES_NEST05=10, NPX_NEST05=361, NPY_NEST05=361 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_global_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - INPUT_NEST03_NML=input_nest_hafs.nml.IN - INPUT_NEST04_NML=input_nest_hafs.nml.IN - INPUT_NEST05_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_global_storm_following_1nest_atm `__ - - Compare HAFS global with 1 storm-following moving nest and atmosphere only results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, IS_MOVING_NEST=".false.,.true.", CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, CPLOCN2ATM, NESTED :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs default values. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=global_latlon, OUTPUT_GRID_2=rotated_latlon :raw-html:`

` - **Grid Parameters**: INPES=4, JNPES=5, NPX=97, NPY=97, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=73, NPY_NEST02=73 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_global_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_1nest_atm `__ - - Compare HAFS regional with 1 nest and atmosphere only results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=90 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLOCN2ATM, NESTED :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs default values. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=rotated_latlon, OUTPUT_GRID_2=rotated_latlon :raw-html:`

` - **Grid Parameters**: INPES=6, JNPES=10, NPX=241, NPY=241, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=361, NPY_NEST02=361 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_atm `__ - - Compare HAFS regional atmosphere only results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLOCN2ATM :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs default values. - - 2019-08-29 00:00:00 - - 6 - - OUTPUT_GRID=regional_latlon :raw-html:`

` - **Grid Parameters**: INPES=20, JNPES=12, NPX=721, NPY=601, NPZ=91, NPZP=$(($NPZ + 1)) - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_atm_ocn `__ - - Compare HAFS regional atmosphere-ocean coupled HYCOM results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf_nonsst" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLWAV, CPLWAV2ATM, CDEPS_DOCN :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLOCN2ATM, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_regional then export_hafs default values. - - 2019-08-29 00:00:00 - - 6 - - OUTPUT_GRID=regional_latlon :raw-html:`

` - **Grid Parameters**: INPES=20, JNPES=12, NPX=721, NPY=601, NPZ=91, NPZP=$(($NPZ + 1)) - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_ocn.IN" - FV3_RUN="hafs_fv3_run.IN hycom_hat10_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_atm_ocn_wav `__ - - Compare HAFS regional atmosphere-ocean-wave coupled results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf_nonsst" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLWAV2ATM, CDEPS_DOCN :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLOCN2ATM, CPLWAV, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_regional then export_hafs default values. - - 2019-08-29 00:00:00 - - 6 - - OUTPUT_GRID=regional_latlon :raw-html:`

` - **Grid Parameters**: INPES=20, JNPES=12, NPX=721, NPY=601, NPZ=91, NPZP=$(($NPZ + 1)) - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_ocn_wav.IN" - FV3_RUN="hafs_fv3_run.IN hycom_hat10_run.IN hafs_ww3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_atm_thompson_gfdlsf `__ - - Compare the results from HAFS regional atmosphere only using the Thompson microphysics scheme and GFDL surface layer scheme with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_thompson_tedmf_gfdlsf" - - **Microphysics:** IMP_PHYSICS=8 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, DO_SAT_ADJ, CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLOCN2ATM :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs default values. - - 2019-08-29 00:00:00 - - 6 - - OUTPUT_GRID=cubed_sphere_grid :raw-html:`

` - **Grid Parameters**: INPES=20, JNPES=12, NPX=721, NPY=601, NPZ=91, NPZP=$(($NPZ + 1)) - - FIELD_TABLE=field_table_hafs_thompson - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_atm_wav `__ - - Compare HAFS regional atmosphere-wave coupled results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLOCN2ATM, CDEPS_DOCN :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_regional then export_hafs default values. - - 2019-08-29 00:00:00 - - 6 - - OUTPUT_GRID=regional_latlon :raw-html:`

` - **Grid Parameters**: INPES=20, JNPES=12, NPX=721, NPY=601, NPZ=91, NPZP=$(($NPZ + 1)) - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_wav.IN" - FV3_RUN="hafs_fv3_run.IN hafs_ww3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_datm_cdeps `__ - - Compare HAFS regional coupled CDEPS data atmosphere from ERA5 with regional HYCOM results with previous trunk version - - N/A: No active atmospheric component - - **Set to FALSE:** CPLWAV, CDEPS_DOCN :raw-html:`

` - **Set to TRUE:** :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_datm_cdeps then export_hafs_regional then export_hafs default values. - - 2019-08-29 00:00:00 - - 24 - - OUTPUT_GRID=regional_latlon :raw-html:`

` - **Grid Parameters**: INPES=$INPES_dflt, JNPES=$JNPES_dflt - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs - INPUT_NML=input_regional_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_ocn.IN" - FV3_RUN="hafs_datm_cdeps_era5.IN hycom_hat10_run.IN" - DATM_STREAM_CONFIGURE=hafs_datm.streams.era5.IN - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_docn `__ - - Compare HAFS regional coupled with regional data ocean from MOM6 results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf_nonsst" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLWAV, CPLWAV2ATM :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLOCN2ATM, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_docn_cdeps then export_hafs_regional then export_hafs default values. - - 2019-08-29 00:00:00 - - 24 - - OUTPUT_GRID=regional_latlon :raw-html:`

` - **Grid Parameters**: INPES=20, JNPES=12, NPX=721, NPY=601, NPZ=91, NPZP=$(($NPZ + 1)) - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_docn.IN" - FV3_RUN="hafs_fv3_run.IN hafs_docn_cdeps_mom6.IN" - DOCN_STREAM_CONFIGURE=hafs_docn.streams.IN - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_docn_oisst `__ - - Compare HAFS regional coupled with global data ocean from OISST results with previous trunk version - - **Suite:** CCPP_SUITE=FV3_HAFS_v1_gfdlmp_tedmf_nonsst - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLWAV, CPLWAV2ATM :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLOCN2ATM, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_docn_cdeps then export_hafs_regional then export_hafs default values. - - 2019-08-29 00:00:00 - - 6 - - OUTPUT_GRID=regional_latlon :raw-html:`

` - **Grid Parameters**: INPES=20, JNPES=12, NPX=721, NPY=601, NPZ=91, NPZP=$(($NPZ + 1)) - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_docn.IN" - FV3_RUN="hafs_fv3_run.IN hafs_docn_cdeps_oisst.IN" - DOCN_STREAM_CONFIGURE=hafs_docn.streams.IN - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.true., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_specified_moving_1nest_atm `__ - - Compare HAFS regional with 1 specified moving nest and atmosphere only results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, IS_MOVING_NEST=".false.,.true.", CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** WRITE_DOPOST, EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLOCN2ATM :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs default values. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=rotated_latlon, OUTPUT_GRID_2=rotated_latlon_moving :raw-html:`

` - **Grid Parameters**: INPES=6, JNPES=10, NPX=241, NPY=241, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=361, NPY_NEST02=361 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_storm_following_1nest_atm `__ - - Compare HAFS regional with 1 storm-following moving nest and atmosphere only results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, IS_MOVING_NEST=".false.,.true.", CPLFLX, CPLWAV, CPLWAV2ATM, CPL_IMP_MRG, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLOCN2ATM :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs default values. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=rotated_latlon, OUTPUT_GRID_2=rotated_latlon_moving :raw-html:`

` - **Grid Parameters**: INPES=6, JNPES=10, NPX=241, NPY=241, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=361, NPY_NEST02=361 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_storm_following_1nest_atm_ocn `__ - - Compare HAFS regional with 1 storm-following moving nest and atmosphere-ocean coupled results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf_nonsst" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, IS_MOVING_NEST=".false.,.true.", CPLWAV, CPLWAV2ATM, USE_COLDSTART, CDEPS_DOCN :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLOCN2ATM, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_regional default values then export_hafs. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=regional_latlon, OUTPUT_GRID_2=regional_latlon_moving :raw-html:`

` - **Grid Parameters**: INPES=6, JNPES=10, NPX=241, NPY=241, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=361, NPY_NEST02=361 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_ocn.IN" - FV3_RUN="hafs_fv3_run.IN hycom_hat10_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_storm_following_1nest_atm_ocn_debug `__ - - Compare HAFS regional with 1 storm-following moving nest and atmosphere-ocean coupled results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf_nonsst" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, IS_MOVING_NEST=".false.,.true.", CPLWAV, CPLWAV2ATM, USE_COLDSTART, CDEPS_DOCN :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLOCN2ATM, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_regional default values then export_hafs. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=regional_latlon, OUTPUT_GRID_2=regional_latlon_moving :raw-html:`

` - **Grid Parameters**: INPES=6, JNPES=10, NPX=241, NPY=241, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=361, NPY_NEST02=361 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_ocn.IN" - FV3_RUN="hafs_fv3_run.IN hycom_hat10_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_storm_following_1nest_atm_ocn_debug `__ - - Compare HAFS regional with 1 storm-following moving nest and atmosphere-ocean coupled results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf_nonsst" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, IS_MOVING_NEST=".false.,.true.", CPLWAV2ATM, USE_COLDSTART, CDEPS_DOCN :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLOCN2ATM, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_regional default values then export_hafs. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=regional_latlon, OUTPUT_GRID_2=regional_latlon_moving :raw-html:`

` - **Grid Parameters**: INPES=$INPES_thrd, JNPES=$JNPES_thrd, INPES=6, JNPES=10, NPX=241, NPY=241, NPZ=64, NPZP=$(($NPZ + 1)) - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_ocn.IN" - FV3_RUN="hafs_fv3_run.IN hycom_hat10_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_storm_following_1nest_atm_ocn_wav `__ - - Compare HAFS regional with 1 storm-following moving nest and atmosphere-ocean-wave coupled results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf_nonsst" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=180 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, IS_MOVING_NEST=".false.,.true.", CPLWAV2ATM, USE_COLDSTART, CDEPS_DOCN :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLFLX, CPLOCN2ATM, CPLWAV, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs_regional default values then export_hafs. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=rotated_latlon, OUTPUT_GRID_2=rotated_latlon :raw-html:`

` - **Grid Parameters**: INPES=6, JNPES=10, NPX=241, NPY=241, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=361, NPY_NEST02=361 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm_ocn_wav.IN" - FV3_RUN="hafs_fv3_run.IN hycom_hat10_run.IN hafs_ww3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - * - `hafs_regional_telescopic_2nests_atm `__ - - Compare HAFS regional with two telescopic nests and atmosphere only results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_HAFS_v1_gfdlmp_tedmf" - - **Microphysics:** IMP_PHYSICS=11 - - **Time Step:** DT_ATMOS=90 - - **Set to FALSE:** MOUNTAIN, WARM_START, FULL_ZS_FILTER, CPLFLX, CPLWAV, CPLWAV2ATM, CMEPS, USE_COLDSTART :raw-html:`

` - **Set to TRUE:** EXTERNAL_IC, NGGPS_IC, REGIONAL, CPLOCN2ATM :raw-html:`

` - **Set to VALUE:** - Also, see export_hafs default values. - - 2020-08-25 12:00:00 - - 6 - - OUTPUT_GRID=rotated_latlon, OUTPUT_GRID_2=lambert_conformal, OUTPUT_GRID_3=regional_latlon :raw-html:`

` - **Grid Parameters**: INPES=6, JNPES=10, NPX=241, NPY=241, NPZ=64, NPZP=$(($NPZ + 1)), INPES_NEST02=6, JNPES_NEST02=10, NPX_NEST02=361, NPY_NEST02=361, INPES_NEST03=6, JNPES_NEST03=10, NPX_NEST03=361, NPY_NEST03=361 - - FIELD_TABLE=field_table_hafs - DIAG_TABLE=diag_table_hafs_template - INPUT_NML=input_regional_hafs.nml.IN - INPUT_NEST02_NML=input_nest_hafs.nml.IN - INPUT_NEST03_NML=input_nest_hafs.nml.IN - MODEL_CONFIGURE="model_configure_hafs.IN" - UFS_CONFIGURE="ufs.configure.hafs_atm.IN" - FV3_RUN="hafs_fv3_run.IN" - - RESTART_INTERVAL=1, atm_omp_num_threads=2, WARM_START=.false., READ_INCREMENT=.false., RES_LATLON_DYNAMICS="'fv3_increment.nc'" - **Sample** ``CMAKE_FLAGS`` **Setting** .. code-block:: console diff --git a/doc/UsersGuide/source/tables/rrfs-rts.csv b/doc/UsersGuide/source/tables/rrfs-rts.csv deleted file mode 100644 index df89f780fe..0000000000 --- a/doc/UsersGuide/source/tables/rrfs-rts.csv +++ /dev/null @@ -1,11 +0,0 @@ -Test |nbsp| Name |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp|,Description,Default Settings,Physics |nbsp| Parameters |nbsp| (see |nbsp| `namelist options `__ for variable definitions),Fcst Length (hours),FIELD_TABLE,Other -`rrfs_v1beta `__,Compare RRFS_v1beta results with previous trunk version,``export_rrfs_v1``, , , ,RESTART_INTERVAL="6 -1"; OUTPUT_FH='0 09 12' -`rrfs_v1beta_debug `__,Compare RRFS_v1beta debug results with previous trunk version,``export_rrfs_v1``,,1, ,OUTPUT_FH="0 1" -`rrfs_v1nssl `__,Compare RRFS_v1nssl results with previous trunk version,``export_rrfs_v1``,CCPP_SUITE=FV3_RRFS_v1nssl :raw-html:`

` IMP_PHYSICS=17 :raw-html:`

` **Set to FALSE:** LTAEROSOL :raw-html:`

` **Set to TRUE:** NSSL_CCN_ON; NSSL_HAIL_ON; NSSL_INVERTCCN :raw-html:`

` **Set to VALUE:** NWAT=7, ,field_table_nssl_tke,RESTART_INTERVAL="6 -1"\; OUTPUT_FH='0 09 12' -`rrfs_v1nssl_nohailnoccn `__,Compare RRFS_v1nssl_nohailnoccn results with previous trunk version,``export_rrfs_v1``,CCPP_SUITE=FV3_RRFS_v1nssl :raw-html:`

` IMP_PHYSICS=17 :raw-html:`

` **Set to FALSE:** NSSL_CCN_ON; NSSL_HAIL_ON; LTAEROSOL :raw-html:`

` **Set to TRUE:** NSSL_INVERTCCN :raw-html:`

` **Set to VALUE:** NWAT=6,,field_table_nssl_nohailnoccn_tke,RESTART_INTERVAL="6 -1"; OUTPUT_FH='0 09 12' -`conus13km_control `__,"HRRR physics on 13km domain, control",``export_hrrr_conus13km``, , , ,RESTART_INTERVAL=1; QUILTING_RESTART=.false. -`conus13km_debug `__,"HRRR physics on 13km domain, debug run",``export_hrrr_conus13km``,,1,,RESTART_INTERVAL=1; QUILTING_RESTART=.false. -`conus13km_restart_mismatch `__,"HRRR physics on 13km domain, restart run",``export_hrrr_conus13km``,,,,FHROT=1;RESTART_FILE_PREFIX="${SYEAR}${SMONTH}${SDAY}.$(printf "%02d" $(( ${SHOUR} + ${FHROT} )))0000"; RRFS_RESTART=YES; QUILTING_RESTART=.false. -`conus13km_2threads `__,"HRRR physics on 13km domain, two threads",``export_hrrr_conus13km``,,1,,RESTART_INTERVAL=1; atm_omp_num_threads=2; QUILTING_RESTART=.false.; WRTTASK_PER_GROUP=6 -`conus13km_debug_2threads `__,"HRRR physics on 13km domain, debug run with threads",``export_hrrr_conus13km``,,1, ,RESTART_INTERVAL=1; atm_omp_num_threads=2; WRTTASK_PER_GROUP=6; QUILTING_RESTART=.false. -`conus13km_radar_tten_debug `__,"HRRR physics on 13km domain, debug, with radar-derived temperature tendencies",``export_hrrr_conus13km``,,1,,"RESTART_INTERVAL=1; FH_DFI_RADAR='0.0\,0.25\,0.50\,0.75\,1.0'; QUILTING_RESTART=.false." \ No newline at end of file From 8b857fc283e25d58758173f2c0aa6dc65d69b7f7 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Tue, 22 Oct 2024 16:04:19 -0400 Subject: [PATCH 02/24] add HSD ch, rename RTConf ch, update index and bib --- .../source/Cases and Configurations.rst | 62 +++ doc/UsersGuide/source/ConfigParameters.rst | 177 ------ doc/UsersGuide/source/RTConfigurations.rst | 512 ++++++++++++++++++ doc/UsersGuide/source/index.rst | 3 +- doc/UsersGuide/source/references.bib | 11 + 5 files changed, 587 insertions(+), 178 deletions(-) create mode 100644 doc/UsersGuide/source/Cases and Configurations.rst delete mode 100644 doc/UsersGuide/source/ConfigParameters.rst create mode 100644 doc/UsersGuide/source/RTConfigurations.rst diff --git a/doc/UsersGuide/source/Cases and Configurations.rst b/doc/UsersGuide/source/Cases and Configurations.rst new file mode 100644 index 0000000000..408e7d7f82 --- /dev/null +++ b/doc/UsersGuide/source/Cases and Configurations.rst @@ -0,0 +1,62 @@ +.. |nbsp| unicode:: 0xA0 + :trim: + +.. role:: raw-html(raw) + :format: html + +.. _hsd: + +************************************** +Hierarchical System Development (HSD) +************************************** + +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, and +mediator). This chapter documents a few of the cases designed to support hierarchical system development (HSD) within the UFS. +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. + +.. _ufs-test: + +================ +``ufs_test.sh`` +================ + +The ``ufs-test.sh`` script .... + +.. COMMENT: Expand w/background info + + +.. _cape-2020: + +==================== +2020 July CAPE Case +==================== + +The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16: low Convective Available Potential Energy (CAPE) predictions during summertime. The NOAA Environmental Modeling Center (EMC) Model Evaluation Group (MEG) identified this concern, and . + +The case runs are initialized at 00z Jul 23, 2020 with a 24 hour forecast length. The corresponding namelist options that need to be changed are listed below. The app uses ./xmlchange to change the runtime settings. The settings that need to be modified to set up the start date, start time, and run time are listed below. + +Initial condition (IC) files are created from GFS operational dataset in NEMSIO format. The GFS analysis dataset is used as ‘truth’ to compare with simulated synoptic dynamic fields. The CAPE field is evaluated based on Rapid Refresh (RAP) analysis dataset and atmospheric sounding. + +Both MRW App v1.0 and GFS.v16.0.10 simulate a lower value of CAPE compared with RAP_ANL and sounding observation in this summertime case study. Further investigations (MEG 2021) show that this is related to the drier soil layers in GFS initial conditions. The SRW_RRFSv1alpha also underestimates the CAPE. + +References + +NOAA Environmental Modeling Center Model Evaluation Group (MEG) (2021). [Link] + +Sun X., D. Heinzeller, L. Bernardet, L. Pan, W. Li, D. Turner, and J. Brown. 2024: A Case Study Investigating the Low Summertime CAPE Behavior in the Global Forecast System. Weather and Forecasting. + +https://doi.org/10.1175/WAF-D-22-0208.1 + +https://journals.ametsoc.org/view/journals/wefo/39/1/WAF-D-22-0208.1.xml +Last name and initials of author(s) (if nine or more, the first author is followed by "and Coauthors"), year of publication, title of paper, title of journal (italicized),* volume of journal (bolded), issue or citation number (only if required for identification), page range, and DOI (if available). + +export dprefix="/scratch2/NAGAPE" +STMP="${dprefix}/stmp4" +PTMP="${dprefix}/stmp2" \ No newline at end of file diff --git a/doc/UsersGuide/source/ConfigParameters.rst b/doc/UsersGuide/source/ConfigParameters.rst deleted file mode 100644 index 0fb0881411..0000000000 --- a/doc/UsersGuide/source/ConfigParameters.rst +++ /dev/null @@ -1,177 +0,0 @@ -.. _ConfigParams: - -****************************************** -Configuration Parameters -****************************************** - -================================= -Build Configuration Parameters -================================= - -.. _dapp: - -Configuration Options -========================= - -``-DAPP``: - Sets the :term:`WM` configuration to build. - Valid values: ``ATM``, ``ATMW``, ``ATMAERO``, ``ATMAQ``, ``S2S``, ``S2SA``, ``S2SW``, ``S2SWA``, ``NG-GODAS``, ``HAFS``, ``HAFSW``, ``HAFS-ALL`` - - -.. _suites: - -Physics Options -======================= - -``-DCCPP_SUITES``: - Sets the physics suites that will be made available when the :term:`WM` is built. - - Physics suites supported in regression testing: - - | ``FV3_GFS_cpld_rasmgshocnsstnoahmp_ugwp`` - | ``FV3_GFS_v15p2`` - | ``FV3_GFS_v15_thompson_mynn`` - | ``FV3_GFS_v15_thompson_mynn_lam3km`` - | ``FV3_GFS_v16`` - | ``FV3_GFS_v16_csawmg`` - | ``FV3_GFS_v16_fv3wam`` - | ``FV3_GFS_v16_noahmp`` - | ``FV3_GFS_v16_ras`` - | ``FV3_GFS_v16_ugwpv1`` - | ``FV3_GFS_v17_p8`` - | ``FV3_GFS_v17_p8_rrtmgp`` - | ``FV3_GFS_v17_coupled_p8`` - | ``FV3_GFS_v17_coupled_p8_sfcocn`` - | ``FV3_HAFS_v0_gfdlmp_tedmf`` - | ``FV3_HAFS_v0_gfdlmp_tedmf_nonsst`` - | ``FV3_HAFS_v0_thompson_tedmf_gfdlsf`` - | ``FV3_HRRR`` - | ``FV3_HRRR_smoke`` - | ``FV3_RAP`` - | ``FV3_RAP_RRTMGP`` - | ``FV3_RAP_sfcdiff`` - | ``FV3_RRFS_v1beta`` - | ``FV3_RRFS_v1nssl`` - - Other valid values: - - | ``FV3_CPT_v0`` - | ``FV3_GFS_2017`` - | ``FV3_GFS_2017_csawmg`` - | ``FV3_GFS_2017_csawmgshoc`` - | ``FV3_GFS_2017_gfdlmp`` - | ``FV3_GFS_2017_gfdlmp_noahmp`` - | ``FV3_GFS_2017_gfdlmp_regional`` - | ``FV3_GFS_2017_gfdlmp_regional_c768`` - | ``FV3_GFS_2017_h2ophys`` - | ``FV3_GFS_2017_myj`` - | ``FV3_GFS_2017_ntiedtke`` - | ``FV3_GFS_2017_ozphys_2015`` - | ``FV3_GFS_2017_sas`` - | ``FV3_GFS_2017_satmedmf`` - | ``FV3_GFS_2017_satmedmfq`` - | ``FV3_GFS_2017_shinhong`` - | ``FV3_GFS_2017_stretched`` - | ``FV3_GFS_2017_ysu`` - | ``FV3_GFS_cpld_rasmgshoc`` - | ``FV3_GFS_cpld_rasmgshocnsst`` - | ``FV3_GFS_cpld_rasmgshocnsst_flake`` - | ``FV3_GFS_cpld_rasmgshocnsst_ugwp`` - | ``FV3_GFS_cpldnst_rasmgshoc`` - | ``FV3_GFS_rasmgshoc`` - | ``FV3_GFS_v15`` - | ``FV3_GFS_v15_gf`` - | ``FV3_GFS_v15_gf_thompson`` - | ``FV3_GFS_v15_mynn`` - | ``FV3_GFS_v15_ras`` - | ``FV3_GFS_v15_rasmgshoc`` - | ``FV3_GFS_v15_thompson`` - | ``FV3_GFS_v15p2_no_nsst`` - | ``FV3_GFS_v15plus`` - | ``FV3_GFS_v15plusras`` - | ``FV3_GFS_v16_coupled`` - | ``FV3_GFS_v16_coupled_noahmp`` - | ``FV3_GFS_v16_coupled_nsstNoahmp`` - | ``FV3_GFS_v16_coupled_nsstNoahmpUGWPv1`` - | ``FV3_GFS_v16_coupled_p8`` - | ``FV3_GFS_v16_coupled_p8_sfcocn`` - | ``FV3_GFS_v16_couplednsst`` - | ``FV3_GFS_v16_flake`` - | ``FV3_GFS_v16_no_nsst`` - | ``FV3_GFS_v16_nsstNoahmpUGWPv1`` - | ``FV3_GFS_v16_p8`` - | ``FV3_GFS_v16_thompson`` - | ``FV3_GFSv17alp_cpldnsstrasnoahmp`` - | ``FV3_GFSv17alp_cpldnsstrasugwpnoahmp`` - | ``FV3_GFSv17alp_cpldnsstsasugwpnoahmp`` - | ``FV3_GFSv17alpha_cpldnsstras`` - | ``FV3_GFSv17alpha_cpldnsstras_flake`` - | ``FV3_GFSv17alpha_cpldnsstras_ugwp`` - | ``FV3_GFSv17alpha_cpldnsstrasnoshal`` - | ``FV3_GFSv17alpha_cpldnsstsas`` - | ``FV3_GFSv17alpha_cpldnsstsas_ugwp`` - | ``FV3_GFSv17alpha_ras`` - | ``FV3_GFSv17alpha_ras_flake`` - | ``FV3_GFSv17alpha_ras_ugwp`` - | ``FV3_GFSv17alpha_sas`` - | ``FV3_RAP_cires_ugwp`` - | ``FV3_RAP_flake`` - | ``FV3_RAP_noah`` - | ``FV3_RAP_noah_sfcdiff_cires_ugwp`` - | ``FV3_RAP_noah_sfcdiff_ugwpv1`` - | ``FV3_RAP_noah_sfcdiff_unified_ugwp`` - | ``FV3_RAP_unified_ugwp`` - | ``FV3_RRFS_v1alpha`` - -.. _other-build-options: - -Other Build Options -======================= - -``-DCMEPS_AOFLUX``: (Default: OFF) - Enables atmosphere-ocean flux calculation in mediator. - Valid values: ``ON`` | ``OFF`` - - .. COMMENT: But when/why would you do this? - -``-DDEBUG``: (Default: OFF) - Enables DEBUG mode. - Valid values: ``ON`` | ``OFF`` - - .. COMMENT: And what extras does DEBUG mode provide (that VERBOSE) doesn't? - -``-D32BIT``: (Default: OFF) - Enables 32-bit, single precision arithmetic in dycore and fast physics. - Valid values: ``ON`` | ``OFF`` - - .. COMMENT: But when/why would you do this? - -``-DCCPP_32BIT``: (Default: OFF) - Enables 32-bit, single precision arithmetic in slow physics. - Valid values: ``ON`` | ``OFF`` - - .. COMMENT: But when/why would you do this? - -``-DMOVING_NEST``: (Default: OFF) - Enables moving nest code. - Valid values: ``ON`` | ``OFF`` - - .. COMMENT: But what does that mean? When/why is the moving nest used? - -``-DMULTI_GASES``: (Default: OFF) - Enable ``MULTI_GASES``. - Valid values: ``ON`` | ``OFF`` - - .. COMMENT: But what does this DO?! And when/why is it used? - - -.. COMMENT: Add any of the following options with -D in front??? - set(AVX2 ON CACHE BOOL "Enable AVX2 instruction set") - set(AVX OFF CACHE BOOL "Enable AVX-I instruction set") - set(SIMDMULTIARCH OFF CACHE BOOL "Enable multi-target SIMD instruction sets") - set(INLINE_POST OFF CACHE BOOL "Enable inline post") - set(OPENMP ON CACHE BOOL "Enable OpenMP threading") - set(PARALLEL_NETCDF OFF CACHE BOOL "Enable parallel NetCDF") - set(JEDI_DRIVER OFF CACHE BOOL "Enable JEDI as top level driver") - - diff --git a/doc/UsersGuide/source/RTConfigurations.rst b/doc/UsersGuide/source/RTConfigurations.rst new file mode 100644 index 0000000000..0d76dce392 --- /dev/null +++ b/doc/UsersGuide/source/RTConfigurations.rst @@ -0,0 +1,512 @@ +.. |nbsp| unicode:: 0xA0 + :trim: + +.. role:: raw-html(raw) + :format: html + +.. _Configurations: + +******************************* +Regresson Test Configurations +******************************* + +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, and +mediator). This chapter documents a few of the supported regression test (RT) configurations. For a full list of +supported RT 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 the full set of configurations supported for WM regression tests (RTs). + +.. _UFS-configurations-documented: + +.. list-table:: *Documented UFS Weather Model Configuration Categories* + :widths: 10 70 + :header-rows: 1 + + * - Configuration Category + - Description + * - :ref:`ATM ` + - Standalone Atmospheric Model (:term:`ATM`) + * - :ref:`ATMW ` + - Coupled :term:`ATM` and :term:`WW3` + * - :ref:`ATMAERO ` + - Coupled :term:`ATM` and :term:`GOCART` + * - :ref:`ATML ` + - Coupled :term:`ATM` and :term:`LND` + * - :ref:`LND ` + - Coupled :term:`CDEPS` - :term:`DATM` - :term:`LND` -:term:`CMEPS` + * - :ref:`RRFS ` + - :term:`ATM` with :term:`data assimilation` + * - :ref:`HAFS ` + - Coupled components may include :term:`CDEPS` - :term:`ATM` - :term:`HYCOM` - :term:`WW3` - :term:`MOM6` - :term:`CMEPS` + +This chapter details the supported build/run options for each supported configuration. +Click on the configuration category in :numref:`Table %s ` +to go to that section. Each configuration category includes sample code for setting ``CMAKE_FLAGS`` and ``CCPP_SUITES``. +Additionally, there is a list of preferred physics suites, examples of ``ufs.configure`` files, +and links to information on other input files required to run the model. + +============ +Background +============ + +Each RT configuration file (located in the ``ufs-weather-model/tests/tests`` +`directory `__) +sets default variables by calling setup functions from ``ufs-weather-model/tests/default_vars.sh`` +(see defaults `here `__). +Then, the RT configuration file sets test-specific variablesthese values will override +the defaults. For example, the ``control_c48`` test file sets a list of files that +it will use, calls the ``export_fv3`` function from ``default_vars.sh``, and then exports +test-specific variables. An excerpt is included below (``...`` indicates omitted lines): + +.. code-block:: console + + export LIST_FILES="sfcf000.nc \ + sfcf024.nc \ + atmf000.nc \ + atmf024.nc \ + RESTART/20210323.060000.coupler.res \ + RESTART/20210323.060000.fv_core.res.nc \ + ... + RESTART/20210323.060000.sfc_data.tile5.nc \ + RESTART/20210323.060000.sfc_data.tile6.nc" + + export_fv3 + + export INPES=1 + export JNPES=1 + export WRTTASK_PER_GROUP=2 + export NPZ=127 + export NPZP=128 + export NPX=49 + export NPY=49 + export DT_ATMOS=1200 + ... + +``default_vars.sh`` contains eight functions that set defaults for different types of tests. :numref:`Table %s ` describes what each function does. + +.. _def-funcs: + +.. list-table:: *default_vars.sh functions* + :widths: 10 70 + :header-rows: 1 + + * - Function Name + - Description + * - export_fv3 + - Set variables to the FV3 default values (first common variables, then model-specific ones). Different machines may have different defaults for some variables. + * - export_cpl + - Set variables to the default values for *coupled* / S2S configurations. + * - export_35d_run + - Set variables to the default values for EMC's weekly coupled benchmark 35d tests (see `rt_35d.conf `__). + * - export_datm_cdeps + - Set variables to the default values for configurations that use the data atmosphere (:term:`DATM`) component. + * - export_hafs_datm_cdeps + - Set variables to the default values for HAFS configurations that use the data atmosphere (DATM) component. + * - export_hafs_docn_cdeps + - Set variables to the default values for HAFS configurations that use the data ocean (:term:`DOCN`) component. + * - export_hafs_regional + - Set variables to the default values for regional HAFS configurations. + * - export_hafs + - Set variables to the default values for HAFS configurations. + +Multiple ``default_vars.sh`` functions may be called in a given test. Values set in one +function will be overridden when the same values are set in a subsequent function. + +The most up-to-date list of ``develop`` branch data required for each test is available in +the `UFS WM RT Data Bucket `__. +Users should click on "Browse Bucket" and navigate to the most recent date (in ``develop-YYYY-MM-DD`` format). +Then, users should select *Intel* or *GNU* based on the compiler used in the test they +want to run and then select the test name to see the required data. + +==================================== +Atmospheric Model Configurations +==================================== + +The atmospheric model configurations all use the UFS WM atmospheric component +and may couple it with other models (e.g., a wave or aerosol model). + +.. _atm-documented: + +ATM - Standalone Atmospheric Model +===================================== + +The standalone atmospheric model (:term:`ATM`) is an :term:`FV3`-based prognostic +atmospheric model that can be used for short- and medium-range research and operational +forecasts. In standalone mode, ``ATM`` is not coupled to any other model. + +Current ATM regression tests cover a wide variety of functionality and involve several +physics tests. :numref:`Table %s ` contains a small selection of ATM-only RTs; +it will be expanded to cover the full range of ATM-only supported configurations in time: + +.. _atm-rts: + +.. list-table:: *ATM regression test descriptions* + :widths: 10 40 10 10 15 5 + :header-rows: 1 + + * - Test Name + - Description + - Physics Suite (see `namelist options `__) + - DT_ATMOS + - Start Date + - Forecast Length (hours) + * - `control_c48 `__ + - Compare global control C48L127 results with previous trunk version + - FV3_GFS_v16 + - 1200 + - 2021-03-22 06:00:00 + - 24 + * - `control_p8 `__ + - Compare global control results with previous trunk version + - FV3_GFS_v17_p8 + - 720 + - 2021-03-22 06:00:00 + - 24 + * - `regional_control `__ + - FV3 regional control (hi-res 3km, small domain) test + - FV3_GFS_v15_thompson_mynn_lam3km + - 1800 + - 2016-10-03 00:00:00 + - 6 + +**Sample** ``CMAKE_FLAGS`` **Setting** + +.. code-block:: console + + export CMAKE_FLAGS="-DAPP=ATM -DCCPP_SUITES=FV3_GFS_v16,FV3_GFS_v17_p8,FV3_GFS_v15_thompson_mynn_lam3km -D32BIT=ON" + +**Supported Physics Suites** + +.. list-table:: *Physics suites used in the ATM configurations above* + :widths: 10 50 + :header-rows: 1 + + * - Physics Suite + - Description + * - FV3_GFS_v16 + - The :term:`CCPP` GFS_v16 physics suite is described in the CCPP documentation `here `__. + * - FV3_GFS_v17_p8 + - The CCPP GFS_v17_p8 physics suite is described in the CCPP documentation `here `__. + * - FV3_GFS_v15_thompson_mynn_lam3km + - The CCPP GFS_v15 physics suite with the Thompson Aerosol-Aware Cloud Microphysics Scheme + (see `here `__) and + Mynn Surface Layer Module (see `here `__) + tailored for a limited area model (LAM) 3-km resolution grid. + +**Additional Information** + +Input files required for ATM configurations can be viewed in :numref:`Section %s ` +or in the `UFS WM RT Data Bucket `__. +Information on ``ufs.configure`` files is available in :numref:`Section %s `, +and a sample ATM ``ufs.configure`` file (``ufs.configure.atm.IN``) is available +`here `__. + +.. _atmw-documented: + +ATMW +======= + +The ATMW configuration couples :term:`ATM` with :term:`WaveWatch III`. +These tests use default values set in the ``export_fv3`` function of ``default_vars.sh``. + +.. list-table:: *ATMW regression test descriptions* + :widths: 50 10 30 50 10 10 10 10 10 + :header-rows: 1 + + * - Test |nbsp| Name |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| + - Description + - General Physics Parameters + - Detailed |nbsp| Physics |nbsp| Parameters |nbsp| (see |nbsp| namelist |nbsp| options `here `__ |nbsp| for variable definitions) + - Start |nbsp| Date |nbsp| |nbsp| |nbsp| |nbsp| + - Fcst Length (hours) + - Output Grid + - Configuration Files + - Other + * - `atmwav_control_noaero_p8 `__ + - Compare global control results with previous trunk version + - **Suite:** CCPP_SUITE="FV3_GFS_v16" :raw-html:`

` + + **Microphysics:** IMP_PHYSICS=8 :raw-html:`

` + + **Time Step:** DT_ATMOS=720 :raw-html:`

` + + - **Set to FALSE:** LHEATSTRG, DO_UGWP_V1, DO_GSL_DRAG_LS_BL, DO_GSL_DRAG_TOFD, DO_UGWP_V1_OROG_ONLY, DO_UGWP_V0_NST_ONLY, LDIAG_UGWP, CA_GLOBAL, LANDICE, LGFDLMPRAD, DO_SAT_ADJ, MULTIGRID, USE_CICE_ALB, DO_RRTMGP :raw-html:`

` + **Set to TRUE:** USE_MERRA2, LSEASPRAY, DO_UGWP_V0, DO_GSL_DRAG_SS, DO_CA, CA_SGS, CA_TRIGGER, TILEDFIX, CPL, CPLWAV, CPLWAV2ATM, FRAC_GRID, WRITE_NSFLIP, DOGP_CLDOPTICS_LUT, DOGP_LWSCAT, DOGP_SGS_CNV, SATMEDMF :raw-html:`

` + **Set to VALUE:** IALB=2, IEMS=2, LSM=2, IOPT_DVEG=4, IOPT_CRS=2, IOPT_RAD=3, IOPT_ALB=1, IOPT_STC=3, IOPT_SFC=3, IOPT_TRS=2, IOPT_DIAG=2, D2_BG_K1=0.20, D2_BG_K2=0.04, PSM_BC=1, DDDMP=0.1, IAER=1011, KNOB_UGWP_VERSION=0, KNOB_UGWP_NSLOPE=1, NCA=1, NCELLS=5, NLIVES=12, NTHRESH=18, NSEED=1, NFRACSEED=0.5, NSPINUP=1, ISEED_CA=12345, FSICL=0, FSICS=0, DNATS=0, DZ_MIN=6, cap_dbug_flag=0, MIN_SEAICE=0.15, + - 2021-03-22 06:00:00 + - 12 + - OUTPUT_GRID=gaussian_grid :raw-html:`

` + **Grid Parameters**: INPES=$INPES_cpl_atmw, JNPES=$JNPES_cpl_atmw, NPZ=127, NPZP=128 + - FIELD_TABLE=field_table_thompson_noaero_tke + DIAG_TABLE=diag_table_p8_template + INPUT_NML=cpld_control.nml.IN + UFS_CONFIGURE=ufs.configure.atmw.IN + FV3_RUN=control_run.IN + - RUNTYPE=startup, med_model=cmeps, atm_model=fv3, wav_model=ww3 + +.. _atmaero-documented: + +ATMAERO +========= + +The ATMAERO configuration couples :term:`ATM` with :term:`GOCART`. +These tests use default values set in the ``export_fv3`` function of ``default_vars.sh``. + +.. attention:: + + Certain physics-related settings are common to all of the supported RRFS configurations. These values are set in each test's configuration file because they differ from the ``default_vars.sh`` values: + + General Physics Parameters: + * **Suite:** CCPP_SUITE= `FV3_GFS_v17_p8 `__ + * **Microphysics:** IMP_PHYSICS=8 + * **Time Step:** DT_ATMOS=720 + + Detailed Physics Parameters: + * **Set to FALSE:** DO_UGWP_V1, DO_GSL_DRAG_LS_BL, DO_GSL_DRAG_TOFD, DO_UGWP_V1_OROG_ONLY, DO_UGWP_V0_NST_ONLY, LDIAG_UGWP, CA_GLOBAL, LANDICE, LGFDLMPRAD, DO_SAT_ADJ, USE_CICE_ALB, DO_RRTMGP + * **Set to TRUE:** WRITE_DOPOST, CPL, CPLCHM, USE_MERRA2, LSEASPRAY, DO_UGWP_V0, DO_GSL_DRAG_SS, DO_CA, CA_SGS, CA_TRIGGER, TILEDFIX, FRAC_GRID, WRITE_NSFLIP, DOGP_CLDOPTICS_LUT, DOGP_LWSCAT, DOGP_SGS_CNV, SATMEDMF + * **Set to VALUE:** NSTF_NAME='2,0,0,0,0', atm_model='fv3', chm_model='gocart', DOMAINS_STACK_SIZE=8000000, IALB=2, IEMS=2, LSM=2, IOPT_DVEG=4, IOPT_CRS=2, IOPT_RAD=3, IOPT_ALB=1, IOPT_STC=3, IOPT_SFC=3, IOPT_TRS=2, IOPT_DIAG=2, D2_BG_K1=0.20, D2_BG_K2=0.04, PSM_BC=1, DDDMP=0.1, GWD_OPT=2, KNOB_UGWP_VERSION=0, KNOB_UGWP_NSLOPE=1, NCA=1, NCELLS=5, NLIVES=12, NTHRESH=18, NSEED=1, NFRACSEED=0.5, NSPINUP=1, ISEED_CA=12345, FSICL=0, FSICS=0, DZ_MIN=6, MIN_SEAICE=0.15 + + The "Detailed Physics Parameters" column in :numref:`Table %s ` details physics settings that differ from both the ``default_vars.sh`` values and these ATMAERO-specific defaults. + +ATMAQ +======= + +**COMING SOON!** + +.. _atml-documented: + +ATML +====== + +The ATML configuration couples :term:`ATM` with :term:`LND`. +These tests use default values set in the ``export_fv3`` function of ``default_vars.sh``. + +.. attention:: + There is an issue with ``-D32BIT=ON`` in the ATM-LND tests, and NoahMP requires r8 libraries. + +.. COMMENT: Should "r8" be "p8"? + +.. _atml-rts: + +.. list-table:: *ATML regression test descriptions* + :widths: 10 40 10 10 15 5 + :header-rows: 1 + + * - Test Name + - Description + - Physics Suite (see `namelist options `__) + - DT_ATMOS + - Start Date + - Forecast Length (hours) + * - control_p8_atmlnd_sbs + - Compare global control results with previous trunk version + - FV3_GFS_v17_p8 + - 720 + - 2021-03-22 06:00:00 + - 24 + +**Sample** ``CMAKE_FLAGS`` **Setting** + +.. code-block:: console + + export CMAKE_FLAGS="-DAPP=ATML -DCCPP_SUITES=FV3_GFS_v17_p8" + + +**Supported Physics Suites** + +.. list-table:: *Physics suites used in the ATM configurations above* + :widths: 10 50 + :header-rows: 1 + + * - Physics Suite + - Description + * - FV3_GFS_v17_p8 + - The :term:`CCPP` GFS_v17_p8 physics suite is described in the CCPP documentation `here `__. + +**Additional Information** + +Input files required for ATML configurations can be viewed in :numref:`Section %s (ATM) ` +and :numref:`Section %s (LND) ` or in the `UFS WM RT Data Bucket `__. +Information on ``ufs.configure`` files is available in :numref:`Section %s `, +and a sample ATML ``ufs.configure`` file (``ufs.configure.atm_lnd.IN``) is available +`here `__. + + +.. _rrfs-documented: + +======================================= +Rapid Refresh Forecast System (RRFS) +======================================= + +The RRFS configurations use an :term:`ATM`-only configuration on a high-resolution +regional grid with data assimilation capabilities. +These tests use the default values set in the ``export_fv3``, ``export_rap_common``, ``export_rrfs_v1``, and/or ``export_hrrr_conus13km`` functions of ``default_vars.sh`` unless other values are explicitly set in a given test file. In all tests, the values in ``export_fv3`` are set first. Depending on the test, some of these values may be overriden by ``export_rrfs_v1`` (which includes values from ``export_rap_common``) or ``export_hrrr_conus13km``. :numref:`Table %s ` compares the values set in ``export_fv3`` to the values set in the other functions. + +.. note:: + + ``export_rrfs_v1`` calls ``export_rap_common``, which calls ``export_fv3``. Values from ``export_fv3`` are set first, followed by values in ``export_rap_common`` and then values in ``export_rrfs_v1``. Values in italics indicate that the value is inherited from a previously-called function. + +.. _rrfs-default-vars-comparison: + +.. csv-table:: *RRFS Default Variables* + :file: tables/RRFSDefaultVariables.csv + :widths: 50 10 10 10 10 + :header-rows: 1 + :stub-columns: 1 + +Current RRFS regression tests cover a wide variety of functionality and involve several +physics tests. :numref:`Table %s ` (below) contains a selection of RTs for RRFS functionality. Blanks indicate that the value comes from the default setting file. These default values are listed in :numref:`Table %s ` above. + +**Sample** ``CMAKE_FLAGS`` **Setting** + +.. code-block:: console + + export CMAKE_FLAGS="-DAPP=ATM -DCCPP_SUITES=FV3_RAP,FV3_HRRR,FV3_RRFS_v1beta,FV3_RRFS_v1nssl -D32BIT=ON" + +**Supported Physics Suites** + +.. list-table:: *Physics suites used in the RRFS configurations above* + :widths: 10 50 + :header-rows: 1 + + * - Physics Suite + - Description + * - FV3_HRRR + - The FV3_HRRR physics suite is described in the :term:`CCPP` documentation `here `__. + * - FV3_RRFS_v1beta + - The FV3_RRFS_v1beta physics suite is described in the CCPP documentation `here `__. + * - FV3_RRFS_v1nssl + - The FV3_RRFS_v1nssl physics suite is similar to the *FV3_RRFS_v1beta* suite; however, it uses the NSSL 2-moment microphysics scheme instead of the Thompson microphysics scheme. + + +**Additional Information** + +Each test file lists the input files required for a given test. Input files required for RRFS ATM configurations can be downloaded from the `UFS WM RT Data Bucket `__. Users who wish to run additional (unsupported) cases may also find useful data in the `NOAA RRFS data bucket `__. + +Information on ``ufs.configure`` files is available in :numref:`Section %s `. The supported RRFS WM RTs use the same ``ufs.configure`` file that ATM-only tests do (``ufs.configure.atm.IN``). This file can be viewed in the ``ufs-weather-model/tests/parm`` `directory `__. + +Additionally, users can find examples of various RRFS configuration files in the ``ufs-weather-model/tests/parm`` `directory `__. These files include ``model_configure_*``, ``*_run.IN`` (input run), ``*.nml.IN`` (input namelist), ``field_table_*``, and ``diag_table_*`` files. + +.. _lnd-documented: + +======= +LND +======= + +The LND configuration couples :term:`DATM`, :term:`CDEPS`, and :term:`CMEPS` with :term:`LND`. These tests use default values set in the ``export_datm_cdeps`` function of ``default_vars.sh``. + +.. _lnd-rts: + +.. list-table:: *LND regression test descriptions* + :widths: 10 40 10 10 15 5 + :header-rows: 1 + + * - Test Name + - Description + - Physics Suite + - DT_ATMOS + - Start Date + - Forecast Length (hours) + * - datm_cdeps_lnd_gswp3 + - DATM_CDEPS_NOAHMP_GSWP3 - control + - N/A + - N/A + - 2000-01-01 00:00:00 + - 24 + * - datm_cdeps_lnd_gswp3_rst + - DATM_CDEPS_NOAHMP_GSWP3_RST - control restart + - N/A + - N/A + - 2000-01-01 12:00:00 + - 12 + +**Sample** ``CMAKE_FLAGS`` **Setting** + +.. code-block:: console + + export CMAKE_FLAGS="-DAPP=LND" + +**Additional Information** + +Input files required for LND configurations can be viewed in :numref:`Section %s (LND) ` +or in the `UFS WM RT Data Bucket `__. +Information on ``ufs.configure`` files is available in :numref:`Section %s `, +and a sample ATML ``ufs.configure`` file (``ufs.configure.atm_lnd.IN``) is available +`here `__. + + +============================================= +Seasonal to Subseasonal (S2S) Configurations +============================================= + +**COMING SOON!** + +============== +NG-GODAS +============== + +**COMING SOON!** + +.. _hafs-documented: + +======================================================== +Hurricane Analysis and Reforecast System Configurations +======================================================== + +The HAFS configuration uses an :term:`DATM`-only configuration. + +These tests use the default values set in the ``export_fv3``, ``export_hafs``, ``export_hafs_regional``, ``export_hafs_datm_cdeps``, and ``export_hafs_docn_cdeps`` functions of ``default_vars.sh`` unless other values are explicitly set in a given test file. In all tests, the values in ``export_fv3`` are set first. + +.. note:: + + ``export_hafs`` calls ``export_hafs_regional``, which calls ``export_hafs_datm_cdeps`` or ``export_hafs_docn_cdeps``, which calls ``export_fv3``. Values from ``export_fv3`` are set first, followed by values in ``export_hafs``, ``export_hafs_regional``, and then values in ``export_hafs_datm_cdeps`` or ``export_hafs_docn_cdeps``. + +.. list-table:: *Default physics-related variables used in the HAFS configurations below* + :widths: 10 50 + :header-rows: 1 + + * - Export Function + - Variables + * - export_hafs + - **Set to FALSE:** S2S, AQM, DATM_CDEPS, DOCN_CDEPS, HYBEDMF, CNVGWD, LTAEROSOL, LHEATSTRG, IS_MOVING_NEST :raw-html:`

` + **Set to TRUE:** FV3, HAFS, SATMEDMF, HURR_PBL, DO_GSL_DRAG_LS_BL, DO_GSL_DRAG_SS, DO_GSL_DRAG_TOFD, LRADAR, CPL_IMP_MRG :raw-html:`

` + **Set to VALUE:** NTILES=1, IMFSHALCNV=2, IMFDEEPCNV=2, MONINQ_FAC=-1.0, ISATMEDMF=1, IOPT_SFC=1, IOPT_DVEG=2, IOPT_CRS=1, IOPT_RAD=1, IOPT_ALB=2, IOPT_STC=1, LSM=1, IMP_PHYSICS=11, IAER=111, CDMBWD=1.0,1.0,1.0,1.0, FV_CORE_TAU=5., RF_CUTOFF=30.e2, RF_CUTOFF_NEST=50.e2, VORTEX_TRACKER=0, NTRACK=0, MOVE_CD_X=0, MOVE_CD_Y=0, NFHOUT=3, NFHMAX_HF=-1, NFHOUT_HF=3, NSOUT=-1, OUTPUT_FH=-1 + * - export_hafs_regional + - **Set to FALSE:** S2S, AQM, DOCN_CDEPS, WRITE_DOPOST, USE_COLDSTART, MULTIGRID :raw-html:`

` + **Set to TRUE:** FV3, HAFS, CPL, QUILTING, OUTPUT_HISTORY, CPL_IMP_MRG :raw-html:`

` + **Set to VALUE:** NTILES=1, FHMAX=6, ENS_NUM=1, DT_ATMOS=900, RESTART_INTERVAL=0, FHROT=0, coupling_interval_fast_sec=0, WRITE_GROUP=1, WRTTASK_PER_GROUP=6, NUM_FILES=2, FILENAME_BASE="'atm' 'sfc'", OUTPUT_GRID="'regional_latlon'", OUTPUT_FILE="'netcdf'", IDEFLATE=0, QUANTIZE_NSD=0, NFHOUT=3, NFHMAX_HF=-1, NFHOUT_HF=3, CEN_LON=-62.0, CEN_LAT=25.0, LON1=-114.5, LAT1=-5.0, LON2=-9.5, LAT2=55.0, DLON=0.03, DLAT=0.03, DIAG_TABLE=diag_table_hafs, FIELD_TABLE=field_table_hafs, WW3OUTDTHR=3, OUTPARS_WAV="WND HS T01 T02 DIR FP DP PHS PTP PDIR UST CHA USP", WAV_CUR='C', med_model=cmeps, pio_rearranger=box, CAP_DBUG_FLAG=0, CPLMODE=hafs, RUNTYPE=startup, MESH_WAV=mesh.hafs.nc, MODDEF_WAV=mod_def.natl_6m + * - export_hafs_datm_cdeps + - **Set to FALSE:** FV3, S2S, AQM, DOCN_CDEPS :raw-html:`

` + **Set to TRUE:** HAFS, DATM_CDEPS :raw-html:`

` + **Set to VALUE:** NTILES=1, atm_model=datm, DATM_IN_CONFIGURE=datm_in, DATM_STREAM_CONFIGURE=hafs_datm.streams.era5.IN + * - export_hafs_docn_cdeps + - **Set to FALSE:** S2S, AQM :raw-html:`

` + **Set to TRUE:** FV3, HAFS, DOCN_CDEPS :raw-html:`

` + **Set to VALUE:** NTILES=1, ocn_model=docn, ocn_datamode=sstdata, pio_rearranger=box, DOCN_IN_CONFIGURE=docn_in, DOCN_STREAM_CONFIGURE=hafs_docn.streams.IN + +**Sample** ``CMAKE_FLAGS`` **Setting** + +.. code-block:: console + + export CMAKE_FLAGS="-DAPP=HAFS" + +**Supported Physics Suites** + +.. list-table:: *Physics suites used in the HAFS configurations above* + :widths: 10 50 + :header-rows: 1 + + * - Physics Suite + - Description + * - FV3_HAFS_v1_gfdlmp_tedmf + - The FV3_HAFS_v1_gfdlmp_tedmf physics suite is described in the :term:`CCPP` documentation `here `__. + * - FV3_HAFS_v1_gfdlmp_tedmf_nonsst + - The FV3_HAFS_v1_gfdlmp_tedmf_nonsst physics suite is described in the CCPP documentation `here `__. + * - FV3_HAFS_v1_thompson_tedmf_gfdlsf + - The FV3_HAFS_v1_thompson_tedmf_gfdlsf physics suite is described in the CCPP documentation `here `__. + diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst index c6636e8452..c1bd6bdcc4 100644 --- a/doc/UsersGuide/source/index.rst +++ b/doc/UsersGuide/source/index.rst @@ -14,7 +14,8 @@ Welcome to the UFS Weather Model User's Guide CodeOverview BuildingAndRunning InputsOutputs - Configurations + RTConfigurations + Cases and Configurations ConfigParameters AutomatedTesting FAQ diff --git a/doc/UsersGuide/source/references.bib b/doc/UsersGuide/source/references.bib index 0015b43304..e893afb860 100644 --- a/doc/UsersGuide/source/references.bib +++ b/doc/UsersGuide/source/references.bib @@ -19,3 +19,14 @@ @article{BengtssonEtAl2020 url={https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2020MS002260}, year={2020}, } +@article{SunEtAl2024, + title={A Case Study Investigating the Low Summertime CAPE Behavior in the Global Forecast System}, + author={Sun X. and D. Heinzeller and L. Bernardet and L. Pan and W. Li and D. Turner and J. Brown.}, + journal={Weather and Forecasting}, + volume={39}, + number={1}, + pages={3-17}, + doi={https://doi.org/10.1175/WAF-D-22-0208.1}, + year={2024}, +} + From d9dfc5f517a31d34f795e2d1ef9a09232158f84e Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Tue, 22 Oct 2024 16:12:21 -0400 Subject: [PATCH 03/24] add back ConfParams doc --- doc/UsersGuide/source/ConfigParameters.rst | 177 +++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 doc/UsersGuide/source/ConfigParameters.rst diff --git a/doc/UsersGuide/source/ConfigParameters.rst b/doc/UsersGuide/source/ConfigParameters.rst new file mode 100644 index 0000000000..0fb0881411 --- /dev/null +++ b/doc/UsersGuide/source/ConfigParameters.rst @@ -0,0 +1,177 @@ +.. _ConfigParams: + +****************************************** +Configuration Parameters +****************************************** + +================================= +Build Configuration Parameters +================================= + +.. _dapp: + +Configuration Options +========================= + +``-DAPP``: + Sets the :term:`WM` configuration to build. + Valid values: ``ATM``, ``ATMW``, ``ATMAERO``, ``ATMAQ``, ``S2S``, ``S2SA``, ``S2SW``, ``S2SWA``, ``NG-GODAS``, ``HAFS``, ``HAFSW``, ``HAFS-ALL`` + + +.. _suites: + +Physics Options +======================= + +``-DCCPP_SUITES``: + Sets the physics suites that will be made available when the :term:`WM` is built. + + Physics suites supported in regression testing: + + | ``FV3_GFS_cpld_rasmgshocnsstnoahmp_ugwp`` + | ``FV3_GFS_v15p2`` + | ``FV3_GFS_v15_thompson_mynn`` + | ``FV3_GFS_v15_thompson_mynn_lam3km`` + | ``FV3_GFS_v16`` + | ``FV3_GFS_v16_csawmg`` + | ``FV3_GFS_v16_fv3wam`` + | ``FV3_GFS_v16_noahmp`` + | ``FV3_GFS_v16_ras`` + | ``FV3_GFS_v16_ugwpv1`` + | ``FV3_GFS_v17_p8`` + | ``FV3_GFS_v17_p8_rrtmgp`` + | ``FV3_GFS_v17_coupled_p8`` + | ``FV3_GFS_v17_coupled_p8_sfcocn`` + | ``FV3_HAFS_v0_gfdlmp_tedmf`` + | ``FV3_HAFS_v0_gfdlmp_tedmf_nonsst`` + | ``FV3_HAFS_v0_thompson_tedmf_gfdlsf`` + | ``FV3_HRRR`` + | ``FV3_HRRR_smoke`` + | ``FV3_RAP`` + | ``FV3_RAP_RRTMGP`` + | ``FV3_RAP_sfcdiff`` + | ``FV3_RRFS_v1beta`` + | ``FV3_RRFS_v1nssl`` + + Other valid values: + + | ``FV3_CPT_v0`` + | ``FV3_GFS_2017`` + | ``FV3_GFS_2017_csawmg`` + | ``FV3_GFS_2017_csawmgshoc`` + | ``FV3_GFS_2017_gfdlmp`` + | ``FV3_GFS_2017_gfdlmp_noahmp`` + | ``FV3_GFS_2017_gfdlmp_regional`` + | ``FV3_GFS_2017_gfdlmp_regional_c768`` + | ``FV3_GFS_2017_h2ophys`` + | ``FV3_GFS_2017_myj`` + | ``FV3_GFS_2017_ntiedtke`` + | ``FV3_GFS_2017_ozphys_2015`` + | ``FV3_GFS_2017_sas`` + | ``FV3_GFS_2017_satmedmf`` + | ``FV3_GFS_2017_satmedmfq`` + | ``FV3_GFS_2017_shinhong`` + | ``FV3_GFS_2017_stretched`` + | ``FV3_GFS_2017_ysu`` + | ``FV3_GFS_cpld_rasmgshoc`` + | ``FV3_GFS_cpld_rasmgshocnsst`` + | ``FV3_GFS_cpld_rasmgshocnsst_flake`` + | ``FV3_GFS_cpld_rasmgshocnsst_ugwp`` + | ``FV3_GFS_cpldnst_rasmgshoc`` + | ``FV3_GFS_rasmgshoc`` + | ``FV3_GFS_v15`` + | ``FV3_GFS_v15_gf`` + | ``FV3_GFS_v15_gf_thompson`` + | ``FV3_GFS_v15_mynn`` + | ``FV3_GFS_v15_ras`` + | ``FV3_GFS_v15_rasmgshoc`` + | ``FV3_GFS_v15_thompson`` + | ``FV3_GFS_v15p2_no_nsst`` + | ``FV3_GFS_v15plus`` + | ``FV3_GFS_v15plusras`` + | ``FV3_GFS_v16_coupled`` + | ``FV3_GFS_v16_coupled_noahmp`` + | ``FV3_GFS_v16_coupled_nsstNoahmp`` + | ``FV3_GFS_v16_coupled_nsstNoahmpUGWPv1`` + | ``FV3_GFS_v16_coupled_p8`` + | ``FV3_GFS_v16_coupled_p8_sfcocn`` + | ``FV3_GFS_v16_couplednsst`` + | ``FV3_GFS_v16_flake`` + | ``FV3_GFS_v16_no_nsst`` + | ``FV3_GFS_v16_nsstNoahmpUGWPv1`` + | ``FV3_GFS_v16_p8`` + | ``FV3_GFS_v16_thompson`` + | ``FV3_GFSv17alp_cpldnsstrasnoahmp`` + | ``FV3_GFSv17alp_cpldnsstrasugwpnoahmp`` + | ``FV3_GFSv17alp_cpldnsstsasugwpnoahmp`` + | ``FV3_GFSv17alpha_cpldnsstras`` + | ``FV3_GFSv17alpha_cpldnsstras_flake`` + | ``FV3_GFSv17alpha_cpldnsstras_ugwp`` + | ``FV3_GFSv17alpha_cpldnsstrasnoshal`` + | ``FV3_GFSv17alpha_cpldnsstsas`` + | ``FV3_GFSv17alpha_cpldnsstsas_ugwp`` + | ``FV3_GFSv17alpha_ras`` + | ``FV3_GFSv17alpha_ras_flake`` + | ``FV3_GFSv17alpha_ras_ugwp`` + | ``FV3_GFSv17alpha_sas`` + | ``FV3_RAP_cires_ugwp`` + | ``FV3_RAP_flake`` + | ``FV3_RAP_noah`` + | ``FV3_RAP_noah_sfcdiff_cires_ugwp`` + | ``FV3_RAP_noah_sfcdiff_ugwpv1`` + | ``FV3_RAP_noah_sfcdiff_unified_ugwp`` + | ``FV3_RAP_unified_ugwp`` + | ``FV3_RRFS_v1alpha`` + +.. _other-build-options: + +Other Build Options +======================= + +``-DCMEPS_AOFLUX``: (Default: OFF) + Enables atmosphere-ocean flux calculation in mediator. + Valid values: ``ON`` | ``OFF`` + + .. COMMENT: But when/why would you do this? + +``-DDEBUG``: (Default: OFF) + Enables DEBUG mode. + Valid values: ``ON`` | ``OFF`` + + .. COMMENT: And what extras does DEBUG mode provide (that VERBOSE) doesn't? + +``-D32BIT``: (Default: OFF) + Enables 32-bit, single precision arithmetic in dycore and fast physics. + Valid values: ``ON`` | ``OFF`` + + .. COMMENT: But when/why would you do this? + +``-DCCPP_32BIT``: (Default: OFF) + Enables 32-bit, single precision arithmetic in slow physics. + Valid values: ``ON`` | ``OFF`` + + .. COMMENT: But when/why would you do this? + +``-DMOVING_NEST``: (Default: OFF) + Enables moving nest code. + Valid values: ``ON`` | ``OFF`` + + .. COMMENT: But what does that mean? When/why is the moving nest used? + +``-DMULTI_GASES``: (Default: OFF) + Enable ``MULTI_GASES``. + Valid values: ``ON`` | ``OFF`` + + .. COMMENT: But what does this DO?! And when/why is it used? + + +.. COMMENT: Add any of the following options with -D in front??? + set(AVX2 ON CACHE BOOL "Enable AVX2 instruction set") + set(AVX OFF CACHE BOOL "Enable AVX-I instruction set") + set(SIMDMULTIARCH OFF CACHE BOOL "Enable multi-target SIMD instruction sets") + set(INLINE_POST OFF CACHE BOOL "Enable inline post") + set(OPENMP ON CACHE BOOL "Enable OpenMP threading") + set(PARALLEL_NETCDF OFF CACHE BOOL "Enable parallel NetCDF") + set(JEDI_DRIVER OFF CACHE BOOL "Enable JEDI as top level driver") + + From f7dd5adf371d9a6bd83bb5aa8eb4cd05ffb66cbe Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Tue, 22 Oct 2024 16:13:19 -0400 Subject: [PATCH 04/24] rm old Configurations doc --- doc/UsersGuide/source/Configurations.rst | 512 ----------------------- 1 file changed, 512 deletions(-) delete mode 100644 doc/UsersGuide/source/Configurations.rst diff --git a/doc/UsersGuide/source/Configurations.rst b/doc/UsersGuide/source/Configurations.rst deleted file mode 100644 index 0d76dce392..0000000000 --- a/doc/UsersGuide/source/Configurations.rst +++ /dev/null @@ -1,512 +0,0 @@ -.. |nbsp| unicode:: 0xA0 - :trim: - -.. role:: raw-html(raw) - :format: html - -.. _Configurations: - -******************************* -Regresson Test Configurations -******************************* - -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, and -mediator). This chapter documents a few of the supported regression test (RT) configurations. For a full list of -supported RT 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 the full set of configurations supported for WM regression tests (RTs). - -.. _UFS-configurations-documented: - -.. list-table:: *Documented UFS Weather Model Configuration Categories* - :widths: 10 70 - :header-rows: 1 - - * - Configuration Category - - Description - * - :ref:`ATM ` - - Standalone Atmospheric Model (:term:`ATM`) - * - :ref:`ATMW ` - - Coupled :term:`ATM` and :term:`WW3` - * - :ref:`ATMAERO ` - - Coupled :term:`ATM` and :term:`GOCART` - * - :ref:`ATML ` - - Coupled :term:`ATM` and :term:`LND` - * - :ref:`LND ` - - Coupled :term:`CDEPS` - :term:`DATM` - :term:`LND` -:term:`CMEPS` - * - :ref:`RRFS ` - - :term:`ATM` with :term:`data assimilation` - * - :ref:`HAFS ` - - Coupled components may include :term:`CDEPS` - :term:`ATM` - :term:`HYCOM` - :term:`WW3` - :term:`MOM6` - :term:`CMEPS` - -This chapter details the supported build/run options for each supported configuration. -Click on the configuration category in :numref:`Table %s ` -to go to that section. Each configuration category includes sample code for setting ``CMAKE_FLAGS`` and ``CCPP_SUITES``. -Additionally, there is a list of preferred physics suites, examples of ``ufs.configure`` files, -and links to information on other input files required to run the model. - -============ -Background -============ - -Each RT configuration file (located in the ``ufs-weather-model/tests/tests`` -`directory `__) -sets default variables by calling setup functions from ``ufs-weather-model/tests/default_vars.sh`` -(see defaults `here `__). -Then, the RT configuration file sets test-specific variablesthese values will override -the defaults. For example, the ``control_c48`` test file sets a list of files that -it will use, calls the ``export_fv3`` function from ``default_vars.sh``, and then exports -test-specific variables. An excerpt is included below (``...`` indicates omitted lines): - -.. code-block:: console - - export LIST_FILES="sfcf000.nc \ - sfcf024.nc \ - atmf000.nc \ - atmf024.nc \ - RESTART/20210323.060000.coupler.res \ - RESTART/20210323.060000.fv_core.res.nc \ - ... - RESTART/20210323.060000.sfc_data.tile5.nc \ - RESTART/20210323.060000.sfc_data.tile6.nc" - - export_fv3 - - export INPES=1 - export JNPES=1 - export WRTTASK_PER_GROUP=2 - export NPZ=127 - export NPZP=128 - export NPX=49 - export NPY=49 - export DT_ATMOS=1200 - ... - -``default_vars.sh`` contains eight functions that set defaults for different types of tests. :numref:`Table %s ` describes what each function does. - -.. _def-funcs: - -.. list-table:: *default_vars.sh functions* - :widths: 10 70 - :header-rows: 1 - - * - Function Name - - Description - * - export_fv3 - - Set variables to the FV3 default values (first common variables, then model-specific ones). Different machines may have different defaults for some variables. - * - export_cpl - - Set variables to the default values for *coupled* / S2S configurations. - * - export_35d_run - - Set variables to the default values for EMC's weekly coupled benchmark 35d tests (see `rt_35d.conf `__). - * - export_datm_cdeps - - Set variables to the default values for configurations that use the data atmosphere (:term:`DATM`) component. - * - export_hafs_datm_cdeps - - Set variables to the default values for HAFS configurations that use the data atmosphere (DATM) component. - * - export_hafs_docn_cdeps - - Set variables to the default values for HAFS configurations that use the data ocean (:term:`DOCN`) component. - * - export_hafs_regional - - Set variables to the default values for regional HAFS configurations. - * - export_hafs - - Set variables to the default values for HAFS configurations. - -Multiple ``default_vars.sh`` functions may be called in a given test. Values set in one -function will be overridden when the same values are set in a subsequent function. - -The most up-to-date list of ``develop`` branch data required for each test is available in -the `UFS WM RT Data Bucket `__. -Users should click on "Browse Bucket" and navigate to the most recent date (in ``develop-YYYY-MM-DD`` format). -Then, users should select *Intel* or *GNU* based on the compiler used in the test they -want to run and then select the test name to see the required data. - -==================================== -Atmospheric Model Configurations -==================================== - -The atmospheric model configurations all use the UFS WM atmospheric component -and may couple it with other models (e.g., a wave or aerosol model). - -.. _atm-documented: - -ATM - Standalone Atmospheric Model -===================================== - -The standalone atmospheric model (:term:`ATM`) is an :term:`FV3`-based prognostic -atmospheric model that can be used for short- and medium-range research and operational -forecasts. In standalone mode, ``ATM`` is not coupled to any other model. - -Current ATM regression tests cover a wide variety of functionality and involve several -physics tests. :numref:`Table %s ` contains a small selection of ATM-only RTs; -it will be expanded to cover the full range of ATM-only supported configurations in time: - -.. _atm-rts: - -.. list-table:: *ATM regression test descriptions* - :widths: 10 40 10 10 15 5 - :header-rows: 1 - - * - Test Name - - Description - - Physics Suite (see `namelist options `__) - - DT_ATMOS - - Start Date - - Forecast Length (hours) - * - `control_c48 `__ - - Compare global control C48L127 results with previous trunk version - - FV3_GFS_v16 - - 1200 - - 2021-03-22 06:00:00 - - 24 - * - `control_p8 `__ - - Compare global control results with previous trunk version - - FV3_GFS_v17_p8 - - 720 - - 2021-03-22 06:00:00 - - 24 - * - `regional_control `__ - - FV3 regional control (hi-res 3km, small domain) test - - FV3_GFS_v15_thompson_mynn_lam3km - - 1800 - - 2016-10-03 00:00:00 - - 6 - -**Sample** ``CMAKE_FLAGS`` **Setting** - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATM -DCCPP_SUITES=FV3_GFS_v16,FV3_GFS_v17_p8,FV3_GFS_v15_thompson_mynn_lam3km -D32BIT=ON" - -**Supported Physics Suites** - -.. list-table:: *Physics suites used in the ATM configurations above* - :widths: 10 50 - :header-rows: 1 - - * - Physics Suite - - Description - * - FV3_GFS_v16 - - The :term:`CCPP` GFS_v16 physics suite is described in the CCPP documentation `here `__. - * - FV3_GFS_v17_p8 - - The CCPP GFS_v17_p8 physics suite is described in the CCPP documentation `here `__. - * - FV3_GFS_v15_thompson_mynn_lam3km - - The CCPP GFS_v15 physics suite with the Thompson Aerosol-Aware Cloud Microphysics Scheme - (see `here `__) and - Mynn Surface Layer Module (see `here `__) - tailored for a limited area model (LAM) 3-km resolution grid. - -**Additional Information** - -Input files required for ATM configurations can be viewed in :numref:`Section %s ` -or in the `UFS WM RT Data Bucket `__. -Information on ``ufs.configure`` files is available in :numref:`Section %s `, -and a sample ATM ``ufs.configure`` file (``ufs.configure.atm.IN``) is available -`here `__. - -.. _atmw-documented: - -ATMW -======= - -The ATMW configuration couples :term:`ATM` with :term:`WaveWatch III`. -These tests use default values set in the ``export_fv3`` function of ``default_vars.sh``. - -.. list-table:: *ATMW regression test descriptions* - :widths: 50 10 30 50 10 10 10 10 10 - :header-rows: 1 - - * - Test |nbsp| Name |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| |nbsp| - - Description - - General Physics Parameters - - Detailed |nbsp| Physics |nbsp| Parameters |nbsp| (see |nbsp| namelist |nbsp| options `here `__ |nbsp| for variable definitions) - - Start |nbsp| Date |nbsp| |nbsp| |nbsp| |nbsp| - - Fcst Length (hours) - - Output Grid - - Configuration Files - - Other - * - `atmwav_control_noaero_p8 `__ - - Compare global control results with previous trunk version - - **Suite:** CCPP_SUITE="FV3_GFS_v16" :raw-html:`

` - - **Microphysics:** IMP_PHYSICS=8 :raw-html:`

` - - **Time Step:** DT_ATMOS=720 :raw-html:`

` - - - **Set to FALSE:** LHEATSTRG, DO_UGWP_V1, DO_GSL_DRAG_LS_BL, DO_GSL_DRAG_TOFD, DO_UGWP_V1_OROG_ONLY, DO_UGWP_V0_NST_ONLY, LDIAG_UGWP, CA_GLOBAL, LANDICE, LGFDLMPRAD, DO_SAT_ADJ, MULTIGRID, USE_CICE_ALB, DO_RRTMGP :raw-html:`

` - **Set to TRUE:** USE_MERRA2, LSEASPRAY, DO_UGWP_V0, DO_GSL_DRAG_SS, DO_CA, CA_SGS, CA_TRIGGER, TILEDFIX, CPL, CPLWAV, CPLWAV2ATM, FRAC_GRID, WRITE_NSFLIP, DOGP_CLDOPTICS_LUT, DOGP_LWSCAT, DOGP_SGS_CNV, SATMEDMF :raw-html:`

` - **Set to VALUE:** IALB=2, IEMS=2, LSM=2, IOPT_DVEG=4, IOPT_CRS=2, IOPT_RAD=3, IOPT_ALB=1, IOPT_STC=3, IOPT_SFC=3, IOPT_TRS=2, IOPT_DIAG=2, D2_BG_K1=0.20, D2_BG_K2=0.04, PSM_BC=1, DDDMP=0.1, IAER=1011, KNOB_UGWP_VERSION=0, KNOB_UGWP_NSLOPE=1, NCA=1, NCELLS=5, NLIVES=12, NTHRESH=18, NSEED=1, NFRACSEED=0.5, NSPINUP=1, ISEED_CA=12345, FSICL=0, FSICS=0, DNATS=0, DZ_MIN=6, cap_dbug_flag=0, MIN_SEAICE=0.15, - - 2021-03-22 06:00:00 - - 12 - - OUTPUT_GRID=gaussian_grid :raw-html:`

` - **Grid Parameters**: INPES=$INPES_cpl_atmw, JNPES=$JNPES_cpl_atmw, NPZ=127, NPZP=128 - - FIELD_TABLE=field_table_thompson_noaero_tke - DIAG_TABLE=diag_table_p8_template - INPUT_NML=cpld_control.nml.IN - UFS_CONFIGURE=ufs.configure.atmw.IN - FV3_RUN=control_run.IN - - RUNTYPE=startup, med_model=cmeps, atm_model=fv3, wav_model=ww3 - -.. _atmaero-documented: - -ATMAERO -========= - -The ATMAERO configuration couples :term:`ATM` with :term:`GOCART`. -These tests use default values set in the ``export_fv3`` function of ``default_vars.sh``. - -.. attention:: - - Certain physics-related settings are common to all of the supported RRFS configurations. These values are set in each test's configuration file because they differ from the ``default_vars.sh`` values: - - General Physics Parameters: - * **Suite:** CCPP_SUITE= `FV3_GFS_v17_p8 `__ - * **Microphysics:** IMP_PHYSICS=8 - * **Time Step:** DT_ATMOS=720 - - Detailed Physics Parameters: - * **Set to FALSE:** DO_UGWP_V1, DO_GSL_DRAG_LS_BL, DO_GSL_DRAG_TOFD, DO_UGWP_V1_OROG_ONLY, DO_UGWP_V0_NST_ONLY, LDIAG_UGWP, CA_GLOBAL, LANDICE, LGFDLMPRAD, DO_SAT_ADJ, USE_CICE_ALB, DO_RRTMGP - * **Set to TRUE:** WRITE_DOPOST, CPL, CPLCHM, USE_MERRA2, LSEASPRAY, DO_UGWP_V0, DO_GSL_DRAG_SS, DO_CA, CA_SGS, CA_TRIGGER, TILEDFIX, FRAC_GRID, WRITE_NSFLIP, DOGP_CLDOPTICS_LUT, DOGP_LWSCAT, DOGP_SGS_CNV, SATMEDMF - * **Set to VALUE:** NSTF_NAME='2,0,0,0,0', atm_model='fv3', chm_model='gocart', DOMAINS_STACK_SIZE=8000000, IALB=2, IEMS=2, LSM=2, IOPT_DVEG=4, IOPT_CRS=2, IOPT_RAD=3, IOPT_ALB=1, IOPT_STC=3, IOPT_SFC=3, IOPT_TRS=2, IOPT_DIAG=2, D2_BG_K1=0.20, D2_BG_K2=0.04, PSM_BC=1, DDDMP=0.1, GWD_OPT=2, KNOB_UGWP_VERSION=0, KNOB_UGWP_NSLOPE=1, NCA=1, NCELLS=5, NLIVES=12, NTHRESH=18, NSEED=1, NFRACSEED=0.5, NSPINUP=1, ISEED_CA=12345, FSICL=0, FSICS=0, DZ_MIN=6, MIN_SEAICE=0.15 - - The "Detailed Physics Parameters" column in :numref:`Table %s ` details physics settings that differ from both the ``default_vars.sh`` values and these ATMAERO-specific defaults. - -ATMAQ -======= - -**COMING SOON!** - -.. _atml-documented: - -ATML -====== - -The ATML configuration couples :term:`ATM` with :term:`LND`. -These tests use default values set in the ``export_fv3`` function of ``default_vars.sh``. - -.. attention:: - There is an issue with ``-D32BIT=ON`` in the ATM-LND tests, and NoahMP requires r8 libraries. - -.. COMMENT: Should "r8" be "p8"? - -.. _atml-rts: - -.. list-table:: *ATML regression test descriptions* - :widths: 10 40 10 10 15 5 - :header-rows: 1 - - * - Test Name - - Description - - Physics Suite (see `namelist options `__) - - DT_ATMOS - - Start Date - - Forecast Length (hours) - * - control_p8_atmlnd_sbs - - Compare global control results with previous trunk version - - FV3_GFS_v17_p8 - - 720 - - 2021-03-22 06:00:00 - - 24 - -**Sample** ``CMAKE_FLAGS`` **Setting** - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATML -DCCPP_SUITES=FV3_GFS_v17_p8" - - -**Supported Physics Suites** - -.. list-table:: *Physics suites used in the ATM configurations above* - :widths: 10 50 - :header-rows: 1 - - * - Physics Suite - - Description - * - FV3_GFS_v17_p8 - - The :term:`CCPP` GFS_v17_p8 physics suite is described in the CCPP documentation `here `__. - -**Additional Information** - -Input files required for ATML configurations can be viewed in :numref:`Section %s (ATM) ` -and :numref:`Section %s (LND) ` or in the `UFS WM RT Data Bucket `__. -Information on ``ufs.configure`` files is available in :numref:`Section %s `, -and a sample ATML ``ufs.configure`` file (``ufs.configure.atm_lnd.IN``) is available -`here `__. - - -.. _rrfs-documented: - -======================================= -Rapid Refresh Forecast System (RRFS) -======================================= - -The RRFS configurations use an :term:`ATM`-only configuration on a high-resolution -regional grid with data assimilation capabilities. -These tests use the default values set in the ``export_fv3``, ``export_rap_common``, ``export_rrfs_v1``, and/or ``export_hrrr_conus13km`` functions of ``default_vars.sh`` unless other values are explicitly set in a given test file. In all tests, the values in ``export_fv3`` are set first. Depending on the test, some of these values may be overriden by ``export_rrfs_v1`` (which includes values from ``export_rap_common``) or ``export_hrrr_conus13km``. :numref:`Table %s ` compares the values set in ``export_fv3`` to the values set in the other functions. - -.. note:: - - ``export_rrfs_v1`` calls ``export_rap_common``, which calls ``export_fv3``. Values from ``export_fv3`` are set first, followed by values in ``export_rap_common`` and then values in ``export_rrfs_v1``. Values in italics indicate that the value is inherited from a previously-called function. - -.. _rrfs-default-vars-comparison: - -.. csv-table:: *RRFS Default Variables* - :file: tables/RRFSDefaultVariables.csv - :widths: 50 10 10 10 10 - :header-rows: 1 - :stub-columns: 1 - -Current RRFS regression tests cover a wide variety of functionality and involve several -physics tests. :numref:`Table %s ` (below) contains a selection of RTs for RRFS functionality. Blanks indicate that the value comes from the default setting file. These default values are listed in :numref:`Table %s ` above. - -**Sample** ``CMAKE_FLAGS`` **Setting** - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=ATM -DCCPP_SUITES=FV3_RAP,FV3_HRRR,FV3_RRFS_v1beta,FV3_RRFS_v1nssl -D32BIT=ON" - -**Supported Physics Suites** - -.. list-table:: *Physics suites used in the RRFS configurations above* - :widths: 10 50 - :header-rows: 1 - - * - Physics Suite - - Description - * - FV3_HRRR - - The FV3_HRRR physics suite is described in the :term:`CCPP` documentation `here `__. - * - FV3_RRFS_v1beta - - The FV3_RRFS_v1beta physics suite is described in the CCPP documentation `here `__. - * - FV3_RRFS_v1nssl - - The FV3_RRFS_v1nssl physics suite is similar to the *FV3_RRFS_v1beta* suite; however, it uses the NSSL 2-moment microphysics scheme instead of the Thompson microphysics scheme. - - -**Additional Information** - -Each test file lists the input files required for a given test. Input files required for RRFS ATM configurations can be downloaded from the `UFS WM RT Data Bucket `__. Users who wish to run additional (unsupported) cases may also find useful data in the `NOAA RRFS data bucket `__. - -Information on ``ufs.configure`` files is available in :numref:`Section %s `. The supported RRFS WM RTs use the same ``ufs.configure`` file that ATM-only tests do (``ufs.configure.atm.IN``). This file can be viewed in the ``ufs-weather-model/tests/parm`` `directory `__. - -Additionally, users can find examples of various RRFS configuration files in the ``ufs-weather-model/tests/parm`` `directory `__. These files include ``model_configure_*``, ``*_run.IN`` (input run), ``*.nml.IN`` (input namelist), ``field_table_*``, and ``diag_table_*`` files. - -.. _lnd-documented: - -======= -LND -======= - -The LND configuration couples :term:`DATM`, :term:`CDEPS`, and :term:`CMEPS` with :term:`LND`. These tests use default values set in the ``export_datm_cdeps`` function of ``default_vars.sh``. - -.. _lnd-rts: - -.. list-table:: *LND regression test descriptions* - :widths: 10 40 10 10 15 5 - :header-rows: 1 - - * - Test Name - - Description - - Physics Suite - - DT_ATMOS - - Start Date - - Forecast Length (hours) - * - datm_cdeps_lnd_gswp3 - - DATM_CDEPS_NOAHMP_GSWP3 - control - - N/A - - N/A - - 2000-01-01 00:00:00 - - 24 - * - datm_cdeps_lnd_gswp3_rst - - DATM_CDEPS_NOAHMP_GSWP3_RST - control restart - - N/A - - N/A - - 2000-01-01 12:00:00 - - 12 - -**Sample** ``CMAKE_FLAGS`` **Setting** - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=LND" - -**Additional Information** - -Input files required for LND configurations can be viewed in :numref:`Section %s (LND) ` -or in the `UFS WM RT Data Bucket `__. -Information on ``ufs.configure`` files is available in :numref:`Section %s `, -and a sample ATML ``ufs.configure`` file (``ufs.configure.atm_lnd.IN``) is available -`here `__. - - -============================================= -Seasonal to Subseasonal (S2S) Configurations -============================================= - -**COMING SOON!** - -============== -NG-GODAS -============== - -**COMING SOON!** - -.. _hafs-documented: - -======================================================== -Hurricane Analysis and Reforecast System Configurations -======================================================== - -The HAFS configuration uses an :term:`DATM`-only configuration. - -These tests use the default values set in the ``export_fv3``, ``export_hafs``, ``export_hafs_regional``, ``export_hafs_datm_cdeps``, and ``export_hafs_docn_cdeps`` functions of ``default_vars.sh`` unless other values are explicitly set in a given test file. In all tests, the values in ``export_fv3`` are set first. - -.. note:: - - ``export_hafs`` calls ``export_hafs_regional``, which calls ``export_hafs_datm_cdeps`` or ``export_hafs_docn_cdeps``, which calls ``export_fv3``. Values from ``export_fv3`` are set first, followed by values in ``export_hafs``, ``export_hafs_regional``, and then values in ``export_hafs_datm_cdeps`` or ``export_hafs_docn_cdeps``. - -.. list-table:: *Default physics-related variables used in the HAFS configurations below* - :widths: 10 50 - :header-rows: 1 - - * - Export Function - - Variables - * - export_hafs - - **Set to FALSE:** S2S, AQM, DATM_CDEPS, DOCN_CDEPS, HYBEDMF, CNVGWD, LTAEROSOL, LHEATSTRG, IS_MOVING_NEST :raw-html:`

` - **Set to TRUE:** FV3, HAFS, SATMEDMF, HURR_PBL, DO_GSL_DRAG_LS_BL, DO_GSL_DRAG_SS, DO_GSL_DRAG_TOFD, LRADAR, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** NTILES=1, IMFSHALCNV=2, IMFDEEPCNV=2, MONINQ_FAC=-1.0, ISATMEDMF=1, IOPT_SFC=1, IOPT_DVEG=2, IOPT_CRS=1, IOPT_RAD=1, IOPT_ALB=2, IOPT_STC=1, LSM=1, IMP_PHYSICS=11, IAER=111, CDMBWD=1.0,1.0,1.0,1.0, FV_CORE_TAU=5., RF_CUTOFF=30.e2, RF_CUTOFF_NEST=50.e2, VORTEX_TRACKER=0, NTRACK=0, MOVE_CD_X=0, MOVE_CD_Y=0, NFHOUT=3, NFHMAX_HF=-1, NFHOUT_HF=3, NSOUT=-1, OUTPUT_FH=-1 - * - export_hafs_regional - - **Set to FALSE:** S2S, AQM, DOCN_CDEPS, WRITE_DOPOST, USE_COLDSTART, MULTIGRID :raw-html:`

` - **Set to TRUE:** FV3, HAFS, CPL, QUILTING, OUTPUT_HISTORY, CPL_IMP_MRG :raw-html:`

` - **Set to VALUE:** NTILES=1, FHMAX=6, ENS_NUM=1, DT_ATMOS=900, RESTART_INTERVAL=0, FHROT=0, coupling_interval_fast_sec=0, WRITE_GROUP=1, WRTTASK_PER_GROUP=6, NUM_FILES=2, FILENAME_BASE="'atm' 'sfc'", OUTPUT_GRID="'regional_latlon'", OUTPUT_FILE="'netcdf'", IDEFLATE=0, QUANTIZE_NSD=0, NFHOUT=3, NFHMAX_HF=-1, NFHOUT_HF=3, CEN_LON=-62.0, CEN_LAT=25.0, LON1=-114.5, LAT1=-5.0, LON2=-9.5, LAT2=55.0, DLON=0.03, DLAT=0.03, DIAG_TABLE=diag_table_hafs, FIELD_TABLE=field_table_hafs, WW3OUTDTHR=3, OUTPARS_WAV="WND HS T01 T02 DIR FP DP PHS PTP PDIR UST CHA USP", WAV_CUR='C', med_model=cmeps, pio_rearranger=box, CAP_DBUG_FLAG=0, CPLMODE=hafs, RUNTYPE=startup, MESH_WAV=mesh.hafs.nc, MODDEF_WAV=mod_def.natl_6m - * - export_hafs_datm_cdeps - - **Set to FALSE:** FV3, S2S, AQM, DOCN_CDEPS :raw-html:`

` - **Set to TRUE:** HAFS, DATM_CDEPS :raw-html:`

` - **Set to VALUE:** NTILES=1, atm_model=datm, DATM_IN_CONFIGURE=datm_in, DATM_STREAM_CONFIGURE=hafs_datm.streams.era5.IN - * - export_hafs_docn_cdeps - - **Set to FALSE:** S2S, AQM :raw-html:`

` - **Set to TRUE:** FV3, HAFS, DOCN_CDEPS :raw-html:`

` - **Set to VALUE:** NTILES=1, ocn_model=docn, ocn_datamode=sstdata, pio_rearranger=box, DOCN_IN_CONFIGURE=docn_in, DOCN_STREAM_CONFIGURE=hafs_docn.streams.IN - -**Sample** ``CMAKE_FLAGS`` **Setting** - -.. code-block:: console - - export CMAKE_FLAGS="-DAPP=HAFS" - -**Supported Physics Suites** - -.. list-table:: *Physics suites used in the HAFS configurations above* - :widths: 10 50 - :header-rows: 1 - - * - Physics Suite - - Description - * - FV3_HAFS_v1_gfdlmp_tedmf - - The FV3_HAFS_v1_gfdlmp_tedmf physics suite is described in the :term:`CCPP` documentation `here `__. - * - FV3_HAFS_v1_gfdlmp_tedmf_nonsst - - The FV3_HAFS_v1_gfdlmp_tedmf_nonsst physics suite is described in the CCPP documentation `here `__. - * - FV3_HAFS_v1_thompson_tedmf_gfdlsf - - The FV3_HAFS_v1_thompson_tedmf_gfdlsf physics suite is described in the CCPP documentation `here `__. - From cb3ba89f0e4979c26050532deccc3257a40f2a2b Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Fri, 25 Oct 2024 12:06:37 -0400 Subject: [PATCH 05/24] misc minor updates --- doc/UsersGuide/source/Cases and Configurations.rst | 13 +++++++++---- doc/UsersGuide/source/Introduction.rst | 2 ++ doc/UsersGuide/source/RTConfigurations.rst | 4 +--- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/UsersGuide/source/Cases and Configurations.rst b/doc/UsersGuide/source/Cases and Configurations.rst index 408e7d7f82..8e4efea591 100644 --- a/doc/UsersGuide/source/Cases and Configurations.rst +++ b/doc/UsersGuide/source/Cases and Configurations.rst @@ -6,9 +6,14 @@ .. _hsd: -************************************** -Hierarchical System Development (HSD) -************************************** +******************************************** +Hierarchical System Development (HSD) Cases +******************************************** + + + + + 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, and @@ -44,7 +49,7 @@ The case runs are initialized at 00z Jul 23, 2020 with a 24 hour forecast length Initial condition (IC) files are created from GFS operational dataset in NEMSIO format. The GFS analysis dataset is used as ‘truth’ to compare with simulated synoptic dynamic fields. The CAPE field is evaluated based on Rapid Refresh (RAP) analysis dataset and atmospheric sounding. -Both MRW App v1.0 and GFS.v16.0.10 simulate a lower value of CAPE compared with RAP_ANL and sounding observation in this summertime case study. Further investigations (MEG 2021) show that this is related to the drier soil layers in GFS initial conditions. The SRW_RRFSv1alpha also underestimates the CAPE. +Both MRW App v1.0 and GFS.v16.0.10 simulate a lower value of CAPE compared with RAP_ANL and sounding observation in this summertime case study. Further investigations (MEG 2021) show that this is related to the drier soil layers in GFS initial conditions. The SRW_RRFSv1alpha also underestimates the CAPE. (:cite:t:`SunEtAl2024`) References diff --git a/doc/UsersGuide/source/Introduction.rst b/doc/UsersGuide/source/Introduction.rst index b2d86b08c1..e5449d2150 100644 --- a/doc/UsersGuide/source/Introduction.rst +++ b/doc/UsersGuide/source/Introduction.rst @@ -59,6 +59,8 @@ This WM User's Guide is organized as follows: * :numref:`Chapter %s ` (Configurations) lists the currently supported configurations for the UFS WM. + * :numref:`Chapter %s ` (Hierarchical System Development) explains how to run test cases that support Hierarchical System Development. + * :numref:`Chapter %s ` (Configuration Parameters) lists the purpose and valid values for various configuration parameters. * :numref:`Chapter %s ` (Automated Testing) describes UFS WM automated testing options. diff --git a/doc/UsersGuide/source/RTConfigurations.rst b/doc/UsersGuide/source/RTConfigurations.rst index 0d76dce392..49da568cc2 100644 --- a/doc/UsersGuide/source/RTConfigurations.rst +++ b/doc/UsersGuide/source/RTConfigurations.rst @@ -270,8 +270,6 @@ These tests use default values set in the ``export_fv3`` function of ``default_v * **Set to FALSE:** DO_UGWP_V1, DO_GSL_DRAG_LS_BL, DO_GSL_DRAG_TOFD, DO_UGWP_V1_OROG_ONLY, DO_UGWP_V0_NST_ONLY, LDIAG_UGWP, CA_GLOBAL, LANDICE, LGFDLMPRAD, DO_SAT_ADJ, USE_CICE_ALB, DO_RRTMGP * **Set to TRUE:** WRITE_DOPOST, CPL, CPLCHM, USE_MERRA2, LSEASPRAY, DO_UGWP_V0, DO_GSL_DRAG_SS, DO_CA, CA_SGS, CA_TRIGGER, TILEDFIX, FRAC_GRID, WRITE_NSFLIP, DOGP_CLDOPTICS_LUT, DOGP_LWSCAT, DOGP_SGS_CNV, SATMEDMF * **Set to VALUE:** NSTF_NAME='2,0,0,0,0', atm_model='fv3', chm_model='gocart', DOMAINS_STACK_SIZE=8000000, IALB=2, IEMS=2, LSM=2, IOPT_DVEG=4, IOPT_CRS=2, IOPT_RAD=3, IOPT_ALB=1, IOPT_STC=3, IOPT_SFC=3, IOPT_TRS=2, IOPT_DIAG=2, D2_BG_K1=0.20, D2_BG_K2=0.04, PSM_BC=1, DDDMP=0.1, GWD_OPT=2, KNOB_UGWP_VERSION=0, KNOB_UGWP_NSLOPE=1, NCA=1, NCELLS=5, NLIVES=12, NTHRESH=18, NSEED=1, NFRACSEED=0.5, NSPINUP=1, ISEED_CA=12345, FSICL=0, FSICS=0, DZ_MIN=6, MIN_SEAICE=0.15 - - The "Detailed Physics Parameters" column in :numref:`Table %s ` details physics settings that differ from both the ``default_vars.sh`` values and these ATMAERO-specific defaults. ATMAQ ======= @@ -360,7 +358,7 @@ These tests use the default values set in the ``export_fv3``, ``export_rap_commo :stub-columns: 1 Current RRFS regression tests cover a wide variety of functionality and involve several -physics tests. :numref:`Table %s ` (below) contains a selection of RTs for RRFS functionality. Blanks indicate that the value comes from the default setting file. These default values are listed in :numref:`Table %s ` above. +physics tests. **Sample** ``CMAKE_FLAGS`` **Setting** From 0705cc71f52e50902169e10446f910f7d28436ea Mon Sep 17 00:00:00 2001 From: Joshua Kublnick Date: Wed, 30 Oct 2024 15:12:30 -0400 Subject: [PATCH 06/24] Added infoabout Baroclinic case and provided information on running Idealized cases in the UFS-WM --- .../source/Cases and Configurations.rst | 180 ++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 doc/UsersGuide/source/Cases and Configurations.rst diff --git a/doc/UsersGuide/source/Cases and Configurations.rst b/doc/UsersGuide/source/Cases and Configurations.rst new file mode 100644 index 0000000000..9179fd23c3 --- /dev/null +++ b/doc/UsersGuide/source/Cases and Configurations.rst @@ -0,0 +1,180 @@ +.. |nbsp| unicode:: 0xA0 + :trim: + +.. role:: raw-html(raw) + :format: html + +.. _hsd: + +******************************************** +Hierarchical System Development (HSD) Cases +******************************************** + + + + + + +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, and +mediator). This chapter documents a few of the cases designed to support hierarchical system development (HSD) within the UFS. +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. + +.. _ufs-test: + +================ +``ufs_test.sh`` +================ + +This section will include details on how to run idealized cases using the ``ufs-test.sh`` script. + +Clone the Repository +-------------------- + +To start, clone the branch containing the test cases: + +.. code-block:: console + + git clone --recursive -b feature/enable_test_cases https://github.com/natalie-perlin/ufs-weather-model.git + +After cloning, set up the environment: + +.. code-block:: console + + cd ufs-weather-model + export UFS_WM=$PWD # This variable is for convenience + cd tests-dev + +The tests are configured to be run on NOAA Tier1 platforms, and the configuration files for each platform are located at: + +.. code-block:: console + + ${UFS_WM}/tests-dev/machine_config/machine_.config + +This file loads the necessary Python and Rocoto modules for each platform. + +Baseline Configuration +---------------------- + +Another configuration file, ``${UFS_WM}/tests-dev/baseline_setup.yaml``, contains details for staged input data location, user-specific output directories, and batch job scheduling. Verify the following variables in this file: + +- ``dprefix``: Ensure the directory exists and you have write permissions. +- ``STMP``: Directory for baseline test outputs. +- ``PTMP``: Directory for runtime files. + +Running Tests +------------- + +Launch tests from the ``${UFS_WM}/tests-dev`` directory with the following command: + +.. code-block:: console + + ./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``). + +**Comand-line Options:** + +- ``-s``: Sync scripts (only required on the first run, it syncs scripts from ``./ufs-wm/tests`` to ``./ufs-wm/tests-dev``.). +- ``-c``: Create a baseline (necessary until baselines are staged). +- ``-k``: Keep runtime directories after test completion. +- ``-r``: Use Rocoto workflow manager. +- ``-n``: Run a single test case. + +Example Commands +---------------- + +To run the ``2020_CAPE`` test case with the ``intel`` compiler on ``Hera``, ``Orion``, or ``Gaea``: + +.. 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: + +.. 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, then 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 + +Accessing Run and Output Files +------------------------------ + +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. To monitor progress: + +.. code-block:: console + + tail -f + +Once the tests run successfully with the ``-c`` option (baseline created), future tests can compare results with the new baseline using ``-m`` instead of ``-c``. + +.. note:: + + After the initial run of ``ufs_test.sh`` with the ``-s`` option, you do not need to use it again. Once the baseline is created, you can also use the ``-m`` option to compare with the new baseline if additional testing is done within the same local clone. + +For further test management, you may save the test directory location in an environment variable for convenience: + +.. code-block:: console + + export UFS_WM_TEST=/path/to/expt_dirs/ufs_test + +.. _cape-2020: + +==================== +2020 July CAPE Case +==================== + +The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16: low Convective Available Potential Energy (CAPE) predictions during summertime. The NOAA Environmental Modeling Center (EMC) Model Evaluation Group (MEG) identified this concern, and . + +The case runs are initialized at 00z Jul 23, 2020 with a 24 hour forecast length. The corresponding namelist options that need to be changed are listed below. The app uses ./xmlchange to change the runtime settings. The settings that need to be modified to set up the start date, start time, and run time are listed below. + +Initial condition (IC) files are created from GFS operational dataset in NEMSIO format. The GFS analysis dataset is used as ‘truth’ to compare with simulated synoptic dynamic fields. The CAPE field is evaluated based on Rapid Refresh (RAP) analysis dataset and atmospheric sounding. + +Both MRW App v1.0 and GFS.v16.0.10 simulate a lower value of CAPE compared with RAP_ANL and sounding observation in this summertime case study. Further investigations (MEG 2021) show that this is related to the drier soil layers in GFS initial conditions. The SRW_RRFSv1alpha also underestimates the CAPE. (:cite:t:`SunEtAl2024`) + +References + +NOAA Environmental Modeling Center Model Evaluation Group (MEG) (2021). [Link] + +Sun X., D. Heinzeller, L. Bernardet, L. Pan, W. Li, D. Turner, and J. Brown. 2024: A Case Study Investigating the Low Summertime CAPE Behavior in the Global Forecast System. Weather and Forecasting. + +https://doi.org/10.1175/WAF-D-22-0208.1 + +https://journals.ametsoc.org/view/journals/wefo/39/1/WAF-D-22-0208.1.xml +Last name and initials of author(s) (if nine or more, the first author is followed by "and Coauthors"), year of publication, title of paper, title of journal (italicized),* volume of journal (bolded), issue or citation number (only if required for identification), page range, and DOI (if available). + +export dprefix="/scratch2/NAGAPE" +STMP="${dprefix}/stmp4" +PTMP="${dprefix}/stmp2" + +.. _baroclinicwave: + +============================ +Baroclinic Instability Case +============================ + +The baroclinic wave test case evaluates the performance of dry dynamical cores in atmospheric models, focusing on the idealized growth of a northern hemisphere wave. The initial zonal state is a quasi-realistic steady solution to the adiabatic, inviscid primitive equations, specified analytically. The test begins with an assessment of whether the models maintain this steady state, followed by a perturbation that induces baroclinic wave growth over several days. + +Four dynamical cores with varying resolutions are tested: NASA/NCAR’s Finite Volume package, NCAR’s spectral transform Eulerian and semi-Lagrangian cores in CAM3, and the German Weather Service’s GME model. These hydrostatic cores, which span a range of numerical methods, offer independent high-resolution reference solutions. The study analyzes each model's convergence characteristics and explores the uncertainty of the high-resolution results. + +Refernces + From b8bb06b400b0527a5fae255ab46f75ead9b0f867 Mon Sep 17 00:00:00 2001 From: Brandon Selbig Date: Thu, 31 Oct 2024 13:06:40 -0600 Subject: [PATCH 07/24] change file name --- .../{Cases and Configurations.rst => CasesConfigurations.rst} | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) rename doc/UsersGuide/source/{Cases and Configurations.rst => CasesConfigurations.rst} (99%) diff --git a/doc/UsersGuide/source/Cases and Configurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst similarity index 99% rename from doc/UsersGuide/source/Cases and Configurations.rst rename to doc/UsersGuide/source/CasesConfigurations.rst index 8e4efea591..f10c04469f 100644 --- a/doc/UsersGuide/source/Cases and Configurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -13,8 +13,6 @@ Hierarchical System Development (HSD) Cases - - 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, and mediator). This chapter documents a few of the cases designed to support hierarchical system development (HSD) within the UFS. @@ -64,4 +62,4 @@ Last name and initials of author(s) (if nine or more, the first author is follow export dprefix="/scratch2/NAGAPE" STMP="${dprefix}/stmp4" -PTMP="${dprefix}/stmp2" \ No newline at end of file +PTMP="${dprefix}/stmp2" From 0254e404692dd68f057702a1ebf2740d4eaf5e36 Mon Sep 17 00:00:00 2001 From: Brandon Selbig Date: Thu, 31 Oct 2024 14:21:11 -0600 Subject: [PATCH 08/24] jdk updates --- .../source/Cases and Configurations.rst | 180 ------------------ doc/UsersGuide/source/CasesConfigurations.rst | 119 +++++++++++- 2 files changed, 117 insertions(+), 182 deletions(-) delete mode 100644 doc/UsersGuide/source/Cases and Configurations.rst diff --git a/doc/UsersGuide/source/Cases and Configurations.rst b/doc/UsersGuide/source/Cases and Configurations.rst deleted file mode 100644 index 9179fd23c3..0000000000 --- a/doc/UsersGuide/source/Cases and Configurations.rst +++ /dev/null @@ -1,180 +0,0 @@ -.. |nbsp| unicode:: 0xA0 - :trim: - -.. role:: raw-html(raw) - :format: html - -.. _hsd: - -******************************************** -Hierarchical System Development (HSD) Cases -******************************************** - - - - - - -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, and -mediator). This chapter documents a few of the cases designed to support hierarchical system development (HSD) within the UFS. -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. - -.. _ufs-test: - -================ -``ufs_test.sh`` -================ - -This section will include details on how to run idealized cases using the ``ufs-test.sh`` script. - -Clone the Repository --------------------- - -To start, clone the branch containing the test cases: - -.. code-block:: console - - git clone --recursive -b feature/enable_test_cases https://github.com/natalie-perlin/ufs-weather-model.git - -After cloning, set up the environment: - -.. code-block:: console - - cd ufs-weather-model - export UFS_WM=$PWD # This variable is for convenience - cd tests-dev - -The tests are configured to be run on NOAA Tier1 platforms, and the configuration files for each platform are located at: - -.. code-block:: console - - ${UFS_WM}/tests-dev/machine_config/machine_.config - -This file loads the necessary Python and Rocoto modules for each platform. - -Baseline Configuration ----------------------- - -Another configuration file, ``${UFS_WM}/tests-dev/baseline_setup.yaml``, contains details for staged input data location, user-specific output directories, and batch job scheduling. Verify the following variables in this file: - -- ``dprefix``: Ensure the directory exists and you have write permissions. -- ``STMP``: Directory for baseline test outputs. -- ``PTMP``: Directory for runtime files. - -Running Tests -------------- - -Launch tests from the ``${UFS_WM}/tests-dev`` directory with the following command: - -.. code-block:: console - - ./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``). - -**Comand-line Options:** - -- ``-s``: Sync scripts (only required on the first run, it syncs scripts from ``./ufs-wm/tests`` to ``./ufs-wm/tests-dev``.). -- ``-c``: Create a baseline (necessary until baselines are staged). -- ``-k``: Keep runtime directories after test completion. -- ``-r``: Use Rocoto workflow manager. -- ``-n``: Run a single test case. - -Example Commands ----------------- - -To run the ``2020_CAPE`` test case with the ``intel`` compiler on ``Hera``, ``Orion``, or ``Gaea``: - -.. 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: - -.. 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, then 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 - -Accessing Run and Output Files ------------------------------- - -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. To monitor progress: - -.. code-block:: console - - tail -f - -Once the tests run successfully with the ``-c`` option (baseline created), future tests can compare results with the new baseline using ``-m`` instead of ``-c``. - -.. note:: - - After the initial run of ``ufs_test.sh`` with the ``-s`` option, you do not need to use it again. Once the baseline is created, you can also use the ``-m`` option to compare with the new baseline if additional testing is done within the same local clone. - -For further test management, you may save the test directory location in an environment variable for convenience: - -.. code-block:: console - - export UFS_WM_TEST=/path/to/expt_dirs/ufs_test - -.. _cape-2020: - -==================== -2020 July CAPE Case -==================== - -The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16: low Convective Available Potential Energy (CAPE) predictions during summertime. The NOAA Environmental Modeling Center (EMC) Model Evaluation Group (MEG) identified this concern, and . - -The case runs are initialized at 00z Jul 23, 2020 with a 24 hour forecast length. The corresponding namelist options that need to be changed are listed below. The app uses ./xmlchange to change the runtime settings. The settings that need to be modified to set up the start date, start time, and run time are listed below. - -Initial condition (IC) files are created from GFS operational dataset in NEMSIO format. The GFS analysis dataset is used as ‘truth’ to compare with simulated synoptic dynamic fields. The CAPE field is evaluated based on Rapid Refresh (RAP) analysis dataset and atmospheric sounding. - -Both MRW App v1.0 and GFS.v16.0.10 simulate a lower value of CAPE compared with RAP_ANL and sounding observation in this summertime case study. Further investigations (MEG 2021) show that this is related to the drier soil layers in GFS initial conditions. The SRW_RRFSv1alpha also underestimates the CAPE. (:cite:t:`SunEtAl2024`) - -References - -NOAA Environmental Modeling Center Model Evaluation Group (MEG) (2021). [Link] - -Sun X., D. Heinzeller, L. Bernardet, L. Pan, W. Li, D. Turner, and J. Brown. 2024: A Case Study Investigating the Low Summertime CAPE Behavior in the Global Forecast System. Weather and Forecasting. - -https://doi.org/10.1175/WAF-D-22-0208.1 - -https://journals.ametsoc.org/view/journals/wefo/39/1/WAF-D-22-0208.1.xml -Last name and initials of author(s) (if nine or more, the first author is followed by "and Coauthors"), year of publication, title of paper, title of journal (italicized),* volume of journal (bolded), issue or citation number (only if required for identification), page range, and DOI (if available). - -export dprefix="/scratch2/NAGAPE" -STMP="${dprefix}/stmp4" -PTMP="${dprefix}/stmp2" - -.. _baroclinicwave: - -============================ -Baroclinic Instability Case -============================ - -The baroclinic wave test case evaluates the performance of dry dynamical cores in atmospheric models, focusing on the idealized growth of a northern hemisphere wave. The initial zonal state is a quasi-realistic steady solution to the adiabatic, inviscid primitive equations, specified analytically. The test begins with an assessment of whether the models maintain this steady state, followed by a perturbation that induces baroclinic wave growth over several days. - -Four dynamical cores with varying resolutions are tested: NASA/NCAR’s Finite Volume package, NCAR’s spectral transform Eulerian and semi-Lagrangian cores in CAM3, and the German Weather Service’s GME model. These hydrostatic cores, which span a range of numerical methods, offer independent high-resolution reference solutions. The study analyzes each model's convergence characteristics and explores the uncertainty of the high-resolution results. - -Refernces - diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index f10c04469f..9179fd23c3 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -13,6 +13,8 @@ Hierarchical System Development (HSD) Cases + + 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, and mediator). This chapter documents a few of the cases designed to support hierarchical system development (HSD) within the UFS. @@ -30,10 +32,110 @@ For a full list of supported WM configurations, view the `rt.conf .config + +This file loads the necessary Python and Rocoto modules for each platform. + +Baseline Configuration +---------------------- + +Another configuration file, ``${UFS_WM}/tests-dev/baseline_setup.yaml``, contains details for staged input data location, user-specific output directories, and batch job scheduling. Verify the following variables in this file: + +- ``dprefix``: Ensure the directory exists and you have write permissions. +- ``STMP``: Directory for baseline test outputs. +- ``PTMP``: Directory for runtime files. + +Running Tests +------------- + +Launch tests from the ``${UFS_WM}/tests-dev`` directory with the following command: + +.. code-block:: console + + ./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``). + +**Comand-line Options:** + +- ``-s``: Sync scripts (only required on the first run, it syncs scripts from ``./ufs-wm/tests`` to ``./ufs-wm/tests-dev``.). +- ``-c``: Create a baseline (necessary until baselines are staged). +- ``-k``: Keep runtime directories after test completion. +- ``-r``: Use Rocoto workflow manager. +- ``-n``: Run a single test case. + +Example Commands +---------------- -.. COMMENT: Expand w/background info +To run the ``2020_CAPE`` test case with the ``intel`` compiler on ``Hera``, ``Orion``, or ``Gaea``: +.. 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: + +.. 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, then 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 + +Accessing Run and Output Files +------------------------------ + +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. To monitor progress: + +.. code-block:: console + + tail -f + +Once the tests run successfully with the ``-c`` option (baseline created), future tests can compare results with the new baseline using ``-m`` instead of ``-c``. + +.. note:: + + After the initial run of ``ufs_test.sh`` with the ``-s`` option, you do not need to use it again. Once the baseline is created, you can also use the ``-m`` option to compare with the new baseline if additional testing is done within the same local clone. + +For further test management, you may save the test directory location in an environment variable for convenience: + +.. code-block:: console + + export UFS_WM_TEST=/path/to/expt_dirs/ufs_test .. _cape-2020: @@ -63,3 +165,16 @@ Last name and initials of author(s) (if nine or more, the first author is follow export dprefix="/scratch2/NAGAPE" STMP="${dprefix}/stmp4" PTMP="${dprefix}/stmp2" + +.. _baroclinicwave: + +============================ +Baroclinic Instability Case +============================ + +The baroclinic wave test case evaluates the performance of dry dynamical cores in atmospheric models, focusing on the idealized growth of a northern hemisphere wave. The initial zonal state is a quasi-realistic steady solution to the adiabatic, inviscid primitive equations, specified analytically. The test begins with an assessment of whether the models maintain this steady state, followed by a perturbation that induces baroclinic wave growth over several days. + +Four dynamical cores with varying resolutions are tested: NASA/NCAR’s Finite Volume package, NCAR’s spectral transform Eulerian and semi-Lagrangian cores in CAM3, and the German Weather Service’s GME model. These hydrostatic cores, which span a range of numerical methods, offer independent high-resolution reference solutions. The study analyzes each model's convergence characteristics and explores the uncertainty of the high-resolution results. + +Refernces + From 1a52f2cb4a1e219ed77d50537bb8c30b1154f0f0 Mon Sep 17 00:00:00 2001 From: Joshua Kublnick Date: Fri, 8 Nov 2024 10:36:19 -0500 Subject: [PATCH 09/24] Updated Baroclinic wave information --- .../source/Cases and Configurations.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/doc/UsersGuide/source/Cases and Configurations.rst b/doc/UsersGuide/source/Cases and Configurations.rst index 9179fd23c3..fe88d89ef3 100644 --- a/doc/UsersGuide/source/Cases and Configurations.rst +++ b/doc/UsersGuide/source/Cases and Configurations.rst @@ -172,9 +172,18 @@ PTMP="${dprefix}/stmp2" Baroclinic Instability Case ============================ -The baroclinic wave test case evaluates the performance of dry dynamical cores in atmospheric models, focusing on the idealized growth of a northern hemisphere wave. The initial zonal state is a quasi-realistic steady solution to the adiabatic, inviscid primitive equations, specified analytically. The test begins with an assessment of whether the models maintain this steady state, followed by a perturbation that induces baroclinic wave growth over several days. +The paper "A baroclinic instability test case for atmospheric model dynamical cores" by Christiane Jablonowski and David L. Williamson outlines a test designed to evaluate the accuracy of various atmospheric models in simulating a specific type of wave, known as a baroclinic wave, that 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. -Four dynamical cores with varying resolutions are tested: NASA/NCAR’s Finite Volume package, NCAR’s spectral transform Eulerian and semi-Lagrangian cores in CAM3, and the German Weather Service’s GME model. These hydrostatic cores, which span a range of numerical methods, offer independent high-resolution reference solutions. The study analyzes each model's convergence characteristics and explores the uncertainty of the high-resolution results. +The simulation begins by setting 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 each model handles the wave’s development and movement. -Refernces +The study includes four different dynamical cores with varying grid resolutions: NASA/NCAR’s Finite Volume package, NCAR’s spectral transform Eulerian and semi Lagrangian cores from the CAM3 model, and the German Weather Service’s GME model. Each of these hydrostatic cores, which assume no vertical acceleration in the atmosphere, uses different numerical methods to simulate changes in atmospheric pressure, temperature, and wind. Higher resolution grids provide a more detailed look at these processes but require more computing power, while lower resolution grids offer broader, less precise results. +The test showed that models with higher resolutions, which captured atmospheric changes in finer detail, produced more accurate wave patterns that matched expected high resolution "reference solutions." However, the 1 degree resolution (used in lower resolution models) often missed some of the finer details in the wave's growth and behavior. By comparing each model’s results against these high resolution references, the study could analyze how well each model captured the core aspects of wave formation and its growth. + +To conclude, this test case 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 serve as benchmarks for model improvement, ultimately contributing to better simulations of atmospheric behavior in weather and climate predictions. + +References + +Jablonowski, C., & Williamson, D. L. (2006). A baroclinic instability test case for atmospheric model dynamical cores. Quarterly Journal of the Royal Meteorological Society, 132(621C), 2943-2975. https://doi.org/10.1256/qj.06.12 + +https://doi.org/10.1256/qj.06.12 \ No newline at end of file From 472ba13b0c0c68f90e36858628c51aae3d8ba195 Mon Sep 17 00:00:00 2001 From: Brandon Selbig Date: Tue, 12 Nov 2024 13:14:28 -0700 Subject: [PATCH 10/24] finish details for 2020 july cape case --- doc/UsersGuide/source/CasesConfigurations.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 9179fd23c3..581718c5d2 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -143,13 +143,15 @@ For further test management, you may save the test directory location in an envi 2020 July CAPE Case ==================== -The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16: low Convective Available Potential Energy (CAPE) predictions during summertime. The NOAA Environmental Modeling Center (EMC) Model Evaluation Group (MEG) identified this concern, and . +The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16 which is low Convective Available Potential Energy (CAPE) predictions during summertime. CAPE is an important index when it comes to forecasting storms and can be affected by a multitude of atmospheric variables. -The case runs are initialized at 00z Jul 23, 2020 with a 24 hour forecast length. The corresponding namelist options that need to be changed are listed below. The app uses ./xmlchange to change the runtime settings. The settings that need to be modified to set up the start date, start time, and run time are listed below. +This case study helped identify that the lower CAPE results from the GFS were due to the overall drier atmosphere that what was observed in the lowest 1km. This can be attributed to the bias within the initial conditions taken from the GDAS (global data assimilation system) that have a drier soil moisture. -Initial condition (IC) files are created from GFS operational dataset in NEMSIO format. The GFS analysis dataset is used as ‘truth’ to compare with simulated synoptic dynamic fields. The CAPE field is evaluated based on Rapid Refresh (RAP) analysis dataset and atmospheric sounding. +When compared to the older version of the GFS (v15.2) we see the difference can be attributed to an excessive boundary layer cloud cover that leads to a drop in net radiation at the surface and thus less latent heat flux. This makes for less heat and moisture being fed back to the low levels and ultimately changes the overall vertical -Both MRW App v1.0 and GFS.v16.0.10 simulate a lower value of CAPE compared with RAP_ANL and sounding observation in this summertime case study. Further investigations (MEG 2021) show that this is related to the drier soil layers in GFS initial conditions. The SRW_RRFSv1alpha also underestimates the CAPE. (:cite:t:`SunEtAl2024`) +profile of the atmosphere which changes CAPE values. And in the GFS’s case it results in lower CAPE. All these conditions and biases occuring make this a great case to experiment with as changing the different values talked about above can make for some varying results in the CAPE. See for yourself if you can get + +the outcome to be close to real life observations! References From 933d5800a14db3d8244e9f08906049c9d760f98d Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Wed, 13 Nov 2024 14:59:43 -0500 Subject: [PATCH 11/24] update/rename cases&configs ch --- doc/UsersGuide/source/CasesConfigurations.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index f10c04469f..3e77d3b25c 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -10,9 +10,6 @@ Hierarchical System Development (HSD) Cases ******************************************** - - - 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, and mediator). This chapter documents a few of the cases designed to support hierarchical system development (HSD) within the UFS. @@ -41,9 +38,9 @@ The ``ufs-test.sh`` script .... 2020 July CAPE Case ==================== -The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16: low Convective Available Potential Energy (CAPE) predictions during summertime. The NOAA Environmental Modeling Center (EMC) Model Evaluation Group (MEG) identified this concern, and . +The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16: low Convective Available Potential Energy (CAPE) predictions during summertime. The NOAA Environmental Modeling Center (EMC) Model Evaluation Group (MEG) identified this concern, and ... (:cite:t:`SunEtAl2024`). -The case runs are initialized at 00z Jul 23, 2020 with a 24 hour forecast length. The corresponding namelist options that need to be changed are listed below. The app uses ./xmlchange to change the runtime settings. The settings that need to be modified to set up the start date, start time, and run time are listed below. +The case runs are initialized at 00z Jul 23, 2020 with a 24 hour forecast length. The corresponding namelist options that need to be changed are listed below. The app uses ``./xmlchange`` to change the runtime settings. The settings that need to be modified to set up the start date, start time, and run time are listed below. Initial condition (IC) files are created from GFS operational dataset in NEMSIO format. The GFS analysis dataset is used as ‘truth’ to compare with simulated synoptic dynamic fields. The CAPE field is evaluated based on Rapid Refresh (RAP) analysis dataset and atmospheric sounding. From 7d2889e50a492a88c3f8651adc602ac3c13e2fc7 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Wed, 13 Nov 2024 22:04:03 -0500 Subject: [PATCH 12/24] update TOC --- doc/UsersGuide/source/CasesConfigurations.rst | 17 +++++++++-------- doc/UsersGuide/source/index.rst | 6 +----- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index e1e111961d..08274b0750 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -1,6 +1,3 @@ -.. |nbsp| unicode:: 0xA0 - :trim: - .. role:: raw-html(raw) :format: html @@ -10,9 +7,11 @@ Hierarchical System Development (HSD) Cases ******************************************** +Hierarchical System Development ... _____ADD MORE HERE_____ ... + 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, and -mediator). This chapter documents a few of the cases designed to support hierarchical system development (HSD) within the UFS. +model to a fully coupled model with multiple earth system components (e.g., atmosphere, ocean, sea-ice, land, mediator). +This chapter documents a few of the cases designed to support hierarchical system development (HSD) within the UFS. For a full list of supported WM configurations, view the `rt.conf `__ file. .. attention:: @@ -32,13 +31,13 @@ This section will include details on how to run idealized cases using the ``ufs- Clone the Repository -------------------- -To start, clone the branch containing the test cases: +To start, recursively clone the repository: .. code-block:: console - git clone --recursive -b feature/enable_test_cases https://github.com/natalie-perlin/ufs-weather-model.git + git clone --recursive -b develop https://github.com/ufs-community/ufs-weather-model.git -After cloning, set up the environment: +After cloning, users may save (or "export") the path to the UFS WM in an environment variable: .. code-block:: console @@ -46,6 +45,8 @@ After cloning, set up the environment: export UFS_WM=$PWD # This variable is for convenience cd tests-dev +Although this step is optional, users may find it convenient when navigating between directories. This documentation will use ``${UFS_WM}``, but users may choose to type out the full path. + The tests are configured to be run on NOAA Tier1 platforms, and the configuration files for each platform are located at: .. code-block:: console diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst index f55abf25b8..01fb5c191b 100644 --- a/doc/UsersGuide/source/index.rst +++ b/doc/UsersGuide/source/index.rst @@ -14,13 +14,9 @@ Welcome to the UFS Weather Model User's Guide CodeOverview BuildingAndRunning InputsOutputs -<<<<<<< HEAD RTConfigurations - Cases and Configurations -======= - Configurations + CasesConfigurations modules ->>>>>>> be4544ee28f8fad7bc2cdb207dc62f89c4aa2bb2 ConfigParameters AutomatedTesting FAQ From 87bb385886a91b2d35cc1d2f226d9b5742150099 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Wed, 13 Nov 2024 23:18:51 -0500 Subject: [PATCH 13/24] edit instructions for HSD --- doc/UsersGuide/source/CasesConfigurations.rst | 93 ++++++++++++------- 1 file changed, 61 insertions(+), 32 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 08274b0750..44386b1349 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -36,33 +36,35 @@ 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 - cd ufs-weather-model - export UFS_WM=$PWD # This variable is for convenience - cd tests-dev + 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. -Although this step is optional, users may find it convenient when navigating between directories. This documentation will use ``${UFS_WM}``, but users may choose to type out the full path. +Machine Configuration +----------------------- -The tests are configured to be run on NOAA Tier1 platforms, and the configuration files for each platform are located at: +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 -This file loads the necessary Python and Rocoto modules for each platform. +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. Baseline Configuration ---------------------- -Another configuration file, ``${UFS_WM}/tests-dev/baseline_setup.yaml``, contains details for staged input data location, user-specific output directories, and batch job scheduling. Verify the following variables in this file: +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``: Ensure the directory exists and you have write permissions. -- ``STMP``: Directory for baseline test outputs. -- ``PTMP``: Directory for runtime files. +* ``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``) Running Tests ------------- @@ -71,63 +73,90 @@ Launch tests from the ``${UFS_WM}/tests-dev`` directory with the following comma .. 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``). +* ````: 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``). **Comand-line Options:** -- ``-s``: Sync scripts (only required on the first run, it syncs scripts from ``./ufs-wm/tests`` to ``./ufs-wm/tests-dev``.). -- ``-c``: Create a baseline (necessary until baselines are staged). -- ``-k``: Keep runtime directories after test completion. -- ``-r``: Use Rocoto workflow manager. -- ``-n``: Run a single test case. +- ``-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. -Example Commands ----------------- +Examples +^^^^^^^^^^ -To run the ``2020_CAPE`` test case with the ``intel`` compiler on ``Hera``, ``Orion``, or ``Gaea``: +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: +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, then use the ``-l`` argument: +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 -Accessing Run and Output Files ------------------------------- +Checking Results +----------------- -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. To monitor progress: +When the test case finishes running, users should see console output that includes a ``SUCCESS`` message: .. code-block:: console + :emphasize-lines: 2 - tail -f + 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 -Once the tests run successfully with the ``-c`` option (baseline created), future tests can compare results with the new baseline using ``-m`` instead of ``-c``. +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. -.. note:: +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: - After the initial run of ``ufs_test.sh`` with the ``-s`` option, you do not need to use it again. Once the baseline is created, you can also use the ``-m`` option to compare with the new baseline if additional testing is done within the same local clone. +.. 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, you may save the test directory location in an environment variable for convenience: +For further test management, users may save the test directory location in an environment variable: .. code-block:: console From a6de59c2ad9a99fbb6556c3c85c75cbc4eb5b412 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Wed, 13 Nov 2024 23:37:24 -0500 Subject: [PATCH 14/24] update bibliography and HSD intro --- doc/UsersGuide/source/CasesConfigurations.rst | 63 ++++++++++--------- doc/UsersGuide/source/references.bib | 2 +- 2 files changed, 35 insertions(+), 30 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 44386b1349..56b0ccf083 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -7,12 +7,21 @@ Hierarchical System Development (HSD) Cases ******************************************** -Hierarchical System Development ... _____ADD MORE HERE_____ ... +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. -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 a few of the cases designed to support hierarchical system development (HSD) within the UFS. -For a full list of supported WM configurations, view the `rt.conf `__ file. +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 `July 2020 CAPE Case ` + * The `Baroclinic Instability Case ` + +For a full list of supported WM configurations, view the `rt.conf `_ file. .. attention:: @@ -22,9 +31,9 @@ For a full list of supported WM configurations, view the `rt.conf `` 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 Configuration +---------------------- + +they need to add export FHMAX=120 (or 240) in https://github.com/ufs-community/ufs-weather-model/blob/develop/tests-dev/test_cases/tests/baroclinic_wave, and then can update https://github.com/ufs-community/ufs-weather-model/blob/29c2703c715ebdb47bbd4bcc811db340eae530e5/tests-dev/test_cases/tests/baroclinic_wave#L51 to range out , in increments of 6, to the FHMAX they set. + +Can FHMAX be any value, or does it need to be a multiple of 24 or 120? +3:25 +Also, do you have a definition for HSD somewhere? + + +Cameron Book + 3:27 PM +multip of 24 is probably best. and the dev recommended 5/6 days or 10 days. in that range. + Baseline Configuration ---------------------- @@ -165,7 +188,7 @@ For further test management, users may save the test directory location in an en .. _cape-2020: ==================== -2020 July CAPE Case +July 2020 CAPE Case ==================== The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16, which is low Convective Available Potential Energy (CAPE) predictions during summertime (:cite:t:`SunEtAl2024`). CAPE is an important index when it comes to forecasting storms and can be affected by a multitude of atmospheric variables. @@ -173,27 +196,9 @@ The July 2020 CAPE case illustrates one of the shortcomings of the Global Foreca This case study helped identify that the lower CAPE results from the GFS were due to the overall drier atmosphere than what was observed in the lowest 1km. This can be attributed to the bias within the initial conditions taken from the Global Data Assimilation System (GDAS) that have a drier soil moisture. When compared to the older version of the GFS (v15.2), we see the difference can be attributed to an excessive boundary layer cloud cover that leads to a drop in net radiation at the surface and thus less latent heat flux. This makes for less heat and moisture being fed back to the low levels and ultimately changes the overall vertical +profile of the atmosphere which changes CAPE values. And in the GFS’s case it results in lower CAPE. All these conditions and biases occuring make this a great case to experiment with as changing the different values talked about above can make for some varying results in the CAPE. See for yourself if you can get the outcome to be close to real life observations! -profile of the atmosphere which changes CAPE values. And in the GFS’s case it results in lower CAPE. All these conditions and biases occuring make this a great case to experiment with as changing the different values talked about above can make for some varying results in the CAPE. See for yourself if you can get - -the outcome to be close to real life observations! - -References - -NOAA Environmental Modeling Center Model Evaluation Group (MEG) (2021). [Link] - -Sun X., D. Heinzeller, L. Bernardet, L. Pan, W. Li, D. Turner, and J. Brown. 2024: A Case Study Investigating the Low Summertime CAPE Behavior in the Global Forecast System. Weather and Forecasting. - -https://doi.org/10.1175/WAF-D-22-0208.1 - -https://journals.ametsoc.org/view/journals/wefo/39/1/WAF-D-22-0208.1.xml -Last name and initials of author(s) (if nine or more, the first author is followed by "and Coauthors"), year of publication, title of paper, title of journal (italicized),* volume of journal (bolded), issue or citation number (only if required for identification), page range, and DOI (if available). - -export dprefix="/scratch2/NAGAPE" -STMP="${dprefix}/stmp4" -PTMP="${dprefix}/stmp2" - -.. _baroclinicwave: +.. _baroclinic-wave: ============================ Baroclinic Instability Case diff --git a/doc/UsersGuide/source/references.bib b/doc/UsersGuide/source/references.bib index e893afb860..efc799d528 100644 --- a/doc/UsersGuide/source/references.bib +++ b/doc/UsersGuide/source/references.bib @@ -21,7 +21,7 @@ @article{BengtssonEtAl2020 } @article{SunEtAl2024, title={A Case Study Investigating the Low Summertime CAPE Behavior in the Global Forecast System}, - author={Sun X. and D. Heinzeller and L. Bernardet and L. Pan and W. Li and D. Turner and J. Brown.}, + author={X. Sun and D. Heinzeller and L. Bernardet and L. Pan and W. Li and D. Turner and J. Brown.}, journal={Weather and Forecasting}, volume={39}, number={1}, From 13ee1c0c9dd1238e02387c0f4c3da9a1374b2442 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Wed, 13 Nov 2024 23:51:16 -0500 Subject: [PATCH 15/24] add test config info --- doc/UsersGuide/source/CasesConfigurations.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 56b0ccf083..8f477f5a0a 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -69,16 +69,14 @@ where ```` corresponds to the name of the platform. These configuratio Test Configuration ---------------------- -they need to add export FHMAX=120 (or 240) in https://github.com/ufs-community/ufs-weather-model/blob/develop/tests-dev/test_cases/tests/baroclinic_wave, and then can update https://github.com/ufs-community/ufs-weather-model/blob/29c2703c715ebdb47bbd4bcc811db340eae530e5/tests-dev/test_cases/tests/baroclinic_wave#L51 to range out , in increments of 6, to the FHMAX they set. +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``. -Can FHMAX be any value, or does it need to be a multiple of 24 or 120? -3:25 -Also, do you have a definition for HSD somewhere? +.. 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' -Cameron Book - 3:27 PM -multip of 24 is probably best. and the dev recommended 5/6 days or 10 days. in that range. +In general, it is preferable to make ``FHMAX`` a multiple of 24. Baseline Configuration ---------------------- From a9ae084f96c40da58c43f576b9f50e7af572590a Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Thu, 14 Nov 2024 00:04:01 -0500 Subject: [PATCH 16/24] update bibliography and baroclinic wave summary --- doc/UsersGuide/source/CasesConfigurations.rst | 69 +++++++++---------- doc/UsersGuide/source/references.bib | 10 +++ 2 files changed, 43 insertions(+), 36 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 8f477f5a0a..3780217838 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -29,6 +29,39 @@ For a full list of supported WM configurations, view the `rt.conf Date: Thu, 14 Nov 2024 08:42:11 -0500 Subject: [PATCH 17/24] update baroclinic wave case --- doc/UsersGuide/source/CasesConfigurations.rst | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 3780217838..7ec9d84683 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -18,8 +18,8 @@ Currently, users can find information on: * :ref:`Running the HSD cases using ufs_test.sh ` and * Two HSD cases: - * The `July 2020 CAPE Case ` - * The `Baroclinic Instability Case ` + * The :ref:`July 2020 CAPE Case ` + * The :ref:`Baroclinic Instability Case ` For a full list of supported WM configurations, view the `rt.conf `_ file. @@ -49,18 +49,15 @@ profile of the atmosphere which changes CAPE values. And in the GFS’s case it 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 specific type of wave, known as a baroclinic wave, that 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 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. -.. COMMENT: Perhaps not necessary? - The study includes four different dynamical cores with varying grid resolutions: NASA/NCAR's Finite Volume package, NCAR's spectral transform Eulerian and semi Lagrangian cores from the CAM3 model, and the German Weather Service's GME model. Each of these hydrostatic cores, which assume no vertical acceleration in the atmosphere, use different numerical methods to simulate changes in atmospheric pressure, temperature, and wind. Higher resolution grids provide a more detailed look at these processes but require more computing power, while lower resolution grids offer broader, less precise results. - - The test showed that models with higher resolutions, which captured atmospheric changes in finer detail, produced more accurate wave patterns that matched expected high resolution "reference solutions." However, the 1 degree resolution (used in lower resolution models) often missed some of the finer details in the wave's growth and behavior. By comparing each model's results against these high resolution references, the study could analyze how well each model captured the core aspects of wave formation and its growth. - 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. -.. COMMENT: Need info on this case specifically +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 (``export_tiled``) and for the `Unified Gravity Wave Physics `_ (``export_ugwpv1``) version 1. These initial values are all set based on values from `default_vars.sh `_. + +The test is set to run a 24-hour forecast from 2019-12-03 at 0z using the `FV3_GFS_v17_p8_ugwpv1 `_ physics suite. 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. .. _ufs-test: @@ -68,7 +65,7 @@ This test provides a standard way to assess how different atmospheric models han Running the HSD Cases Using ``ufs_test.sh`` ============================================ -This section will include details on how to run idealized cases using the ``ufs-test.sh`` script. +This section explains how to run the idealized cases described above using the ``ufs-test.sh`` script. Clone the Repository -------------------- @@ -88,6 +85,8 @@ After cloning, users may save (or "export") the path to the UFS WM in an environ 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 ----------------------- @@ -99,6 +98,8 @@ The HSD cases are configured to be run on NOAA Tier-1 platforms, and the configu 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 ---------------------- @@ -111,6 +112,8 @@ The July 2020 CAPE case can be run as-is without adjusting the configuration. Ho In general, it is preferable to make ``FHMAX`` a multiple of 24. +.. _baseline-config: + Baseline Configuration ---------------------- @@ -120,6 +123,8 @@ Users may need to modify the baseline configuration file (``${UFS_WM}/tests-dev/ * ``STMP``: Directory for baseline test output (typically ``${dprefix}/stmp4``) * ``PTMP``: Directory for runtime files (typically ``${dprefix}/stmp2``) +.. _run-tests: + Running Tests ------------- From 7da1017c1c3a61065543b0808baa1c04aef6f9e0 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Thu, 14 Nov 2024 09:21:05 -0500 Subject: [PATCH 18/24] update CAPE case --- doc/UsersGuide/source/CasesConfigurations.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 7ec9d84683..8b5cf5baeb 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -36,12 +36,17 @@ For a full list of supported WM configurations, view the `rt.conf `_ physics suite and default values from the WM's `default_vars.sh `_ ``export_fv3_v16`` function. -This case study helped identify that the lower CAPE results from the GFS were due to the overall drier atmosphere than what was observed in the lowest 1km. This can be attributed to the bias within the initial conditions taken from the Global Data Assimilation System (GDAS) that have a drier soil moisture. +The July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16: low Convective Available Potential Energy (CAPE) predictions during summertime (:cite:t:`SunEtAl2024`). CAPE is an important index for forecasting storms and can be affected by a multitude of atmospheric variables. + +.. COMMENT: Such as...? ^ + surface energy budget, soil properties, and near-surface and upper-level meteorological fields? + +This case study originally helped identify that the lower CAPE results from the GFS were due to the overall drier atmosphere than what was observed in the lowest 1 km. This can be attributed to the bias within the initial conditions taken from the Global Data Assimilation System (GDAS) that have a drier soil moisture. When compared to the older version of the GFS (v15.2), we see the difference can be attributed to an excessive boundary layer cloud cover that leads to a drop in net radiation at the surface and thus less latent heat flux. This makes for less heat and moisture being fed back to the low levels and ultimately changes the overall vertical -profile of the atmosphere which changes CAPE values. And in the GFS’s case it results in lower CAPE. All these conditions and biases occuring make this a great case to experiment with as changing the different values talked about above can make for some varying results in the CAPE. See for yourself if you can get the outcome to be close to real life observations! +profile of the atmosphere, which changes CAPE values. And in the GFS's case it results in lower CAPE. All these conditions and biases occuring make this a great case to experiment with as changing the different values talked about above can make for some varying results in the CAPE. .. _baroclinic-wave: @@ -55,7 +60,7 @@ The simulation sets the model's atmosphere to an initial steady state, designed 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 (``export_tiled``) and for the `Unified Gravity Wave Physics `_ (``export_ugwpv1``) version 1. These initial values are all set based on values from `default_vars.sh `_. +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 24-hour forecast from 2019-12-03 at 0z using the `FV3_GFS_v17_p8_ugwpv1 `_ physics suite. 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. From e995553452c667cae4bd3faa6dc1652f2c0b4c22 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Thu, 14 Nov 2024 15:10:31 -0500 Subject: [PATCH 19/24] update 2020 CAPE case --- doc/UsersGuide/source/CasesConfigurations.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 8b5cf5baeb..2bbb7bde4f 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -38,15 +38,7 @@ 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 July 2020 CAPE case illustrates one of the shortcomings of the Global Forecast System (GFS) v16: low Convective Available Potential Energy (CAPE) predictions during summertime (:cite:t:`SunEtAl2024`). CAPE is an important index for forecasting storms and can be affected by a multitude of atmospheric variables. - -.. COMMENT: Such as...? ^ - surface energy budget, soil properties, and near-surface and upper-level meteorological fields? - -This case study originally helped identify that the lower CAPE results from the GFS were due to the overall drier atmosphere than what was observed in the lowest 1 km. This can be attributed to the bias within the initial conditions taken from the Global Data Assimilation System (GDAS) that have a drier soil moisture. - -When compared to the older version of the GFS (v15.2), we see the difference can be attributed to an excessive boundary layer cloud cover that leads to a drop in net radiation at the surface and thus less latent heat flux. This makes for less heat and moisture being fed back to the low levels and ultimately changes the overall vertical -profile of the atmosphere, which changes CAPE values. And in the GFS's case it results in lower CAPE. All these conditions and biases occuring make this a great case to experiment with as changing the different values talked about above can make for some varying results in the CAPE. +The July 2020 CAPE case illustrates 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 results in less latent heat and moisture being fed back to the lower levels of the atmosphere and ultimately changes the overall vertical profile of the atmosphere, which lowers CAPE values relative to the older GFS v15.2. Users may wish to run this case and then experiment with different initial conditions, a coupled land surface model (LSM), or other factors to explore factors that improve or worsen this 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: @@ -146,7 +138,7 @@ where: * ````: Name of the test case (e.g., ``2020_CAPE`` or ``baroclinic_wave``). * ````: Compiler used for the tests (``intel`` or ``gnu``). -**Comand-line Options:** +**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). From 018225becc47ae02e6fd75ebb00e1af6e0a93c21 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Thu, 14 Nov 2024 16:48:59 -0500 Subject: [PATCH 20/24] add data info --- doc/UsersGuide/source/CasesConfigurations.rst | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/doc/UsersGuide/source/CasesConfigurations.rst b/doc/UsersGuide/source/CasesConfigurations.rst index 2bbb7bde4f..89535c51b3 100644 --- a/doc/UsersGuide/source/CasesConfigurations.rst +++ b/doc/UsersGuide/source/CasesConfigurations.rst @@ -38,7 +38,9 @@ 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 July 2020 CAPE case illustrates 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 results in less latent heat and moisture being fed back to the lower levels of the atmosphere and ultimately changes the overall vertical profile of the atmosphere, which lowers CAPE values relative to the older GFS v15.2. Users may wish to run this case and then experiment with different initial conditions, a coupled land surface model (LSM), or other factors to explore factors that improve or worsen this 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. +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: @@ -54,7 +56,20 @@ This test provides a standard way to assess how different atmospheric models han 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 24-hour forecast from 2019-12-03 at 0z using the `FV3_GFS_v17_p8_ugwpv1 `_ physics suite. 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. +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: @@ -177,6 +192,8 @@ To run multiple cases at once, copy ``test_cases.yaml`` from the test cases dire 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 ----------------- From 6730f45ad7d3464a87699e1e0dec479580a89851 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Fri, 15 Nov 2024 16:40:51 -0500 Subject: [PATCH 21/24] refactor HSD docs --- doc/UsersGuide/source/CAPE2020.rst | 90 +++++++ doc/UsersGuide/source/CasesConfigurations.rst | 235 ------------------ doc/UsersGuide/source/HSD.rst | 33 +++ doc/UsersGuide/source/baroclinic_wave.rst | 94 +++++++ .../source/doc-snippets/clone_hsd.rst | 14 ++ .../doc-snippets/hsd_baseline_config.rst | 5 + .../source/doc-snippets/hsd_check_results.rst | 38 +++ .../source/doc-snippets/hsd_data.rst | 6 + .../doc-snippets/hsd_machine_config.rst | 7 + .../source/doc-snippets/hsd_notes.rst | 9 + .../source/doc-snippets/hsd_run_multiple.rst | 6 + .../source/doc-snippets/hsd_run_tests.rst | 26 ++ doc/UsersGuide/source/index.rst | 2 +- 13 files changed, 329 insertions(+), 236 deletions(-) create mode 100644 doc/UsersGuide/source/CAPE2020.rst delete mode 100644 doc/UsersGuide/source/CasesConfigurations.rst create mode 100644 doc/UsersGuide/source/HSD.rst create mode 100644 doc/UsersGuide/source/baroclinic_wave.rst create mode 100644 doc/UsersGuide/source/doc-snippets/clone_hsd.rst create mode 100644 doc/UsersGuide/source/doc-snippets/hsd_baseline_config.rst create mode 100644 doc/UsersGuide/source/doc-snippets/hsd_check_results.rst create mode 100644 doc/UsersGuide/source/doc-snippets/hsd_data.rst create mode 100644 doc/UsersGuide/source/doc-snippets/hsd_machine_config.rst create mode 100644 doc/UsersGuide/source/doc-snippets/hsd_notes.rst create mode 100644 doc/UsersGuide/source/doc-snippets/hsd_run_multiple.rst create mode 100644 doc/UsersGuide/source/doc-snippets/hsd_run_tests.rst 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 From 305d43f646494b4c7f3bcc891d741893d6b4c572 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Fri, 15 Nov 2024 17:25:36 -0500 Subject: [PATCH 22/24] update WM docs to use extlinks --- doc/UsersGuide/source/BuildingAndRunning.rst | 8 +++----- doc/UsersGuide/source/CodeOverview.rst | 2 +- doc/UsersGuide/source/FAQ.rst | 2 +- doc/UsersGuide/source/Introduction.rst | 4 ++-- doc/UsersGuide/source/conf.py | 9 +++++++++ 5 files changed, 16 insertions(+), 9 deletions(-) diff --git a/doc/UsersGuide/source/BuildingAndRunning.rst b/doc/UsersGuide/source/BuildingAndRunning.rst index 02bfb2a846..a1c35b31b6 100644 --- a/doc/UsersGuide/source/BuildingAndRunning.rst +++ b/doc/UsersGuide/source/BuildingAndRunning.rst @@ -452,7 +452,7 @@ Running the Model .. attention:: Although the following discussions are general, users may not be able to execute the script successfully "as is" unless they are on a - `Tier-1 platform `__. + :wm-wiki:`Tier-1 platform `. .. _UsingRegressionTest: @@ -504,8 +504,7 @@ or (2) create a new file (e.g., ``my_rt.conf``), add the tests, and execute ``./ On NOAA RDHPCS ------------------ -On `Tier-1 platforms `__, users can run +On :wm-wiki:`Tier-1 platforms `, users can run regression tests by editing the ``rt.conf`` file and executing: .. code-block:: console @@ -733,8 +732,7 @@ operational requirement test. The only difference is that the ``opnReqTest`` scr The ``tests/opnReqTests`` directory contains opnReqTest-specific lower-level scripts used to set up run configurations. -On `Tier-1 platforms `_, tests can +On :wm-wiki:`Tier-1 platforms `, tests can be run by invoking .. code-block:: console diff --git a/doc/UsersGuide/source/CodeOverview.rst b/doc/UsersGuide/source/CodeOverview.rst index 852186292a..c05263fc06 100644 --- a/doc/UsersGuide/source/CodeOverview.rst +++ b/doc/UsersGuide/source/CodeOverview.rst @@ -31,7 +31,7 @@ Currently, Level 1 (or Tier-1) platforms for regression testing are: * Hercules (Intel/GNU compilers) * AWS Docker container (Intel) -More information is available in the `UFS WM wiki `__. +More information is available in the :wm-wiki:`UFS WM wiki `. Level 2-4 Systems =================== diff --git a/doc/UsersGuide/source/FAQ.rst b/doc/UsersGuide/source/FAQ.rst index 939f057bd6..0fbb7977d8 100644 --- a/doc/UsersGuide/source/FAQ.rst +++ b/doc/UsersGuide/source/FAQ.rst @@ -10,7 +10,7 @@ How do I build and run a single test of the UFS Weather Model? An efficient way to build and run the UFS Weather Model is to use the regression test (``rt.sh``). This script is widely used by model developers on Tier 1 and 2 platforms -and is described in the UFS WM GitHub `wiki `_. The advantages to this approach are: +and is described in the UFS WM GitHub :wm-wiki:`wiki `. The advantages to this approach are: * It does not require a workflow, pre- or post-processing steps. * The batch submission script is generated. diff --git a/doc/UsersGuide/source/Introduction.rst b/doc/UsersGuide/source/Introduction.rst index c894590710..c82ebc3af4 100644 --- a/doc/UsersGuide/source/Introduction.rst +++ b/doc/UsersGuide/source/Introduction.rst @@ -45,9 +45,9 @@ The UFS WM code is portable and can be used with Linux or Mac operating systems .. COMMENT: Is the cellular automata stochastic scheme now supported? .. COMMENT: Which horizontal/vertical levels & placements are supported? Just the default ones? -Those wishing to contribute development to the UFS WM should become familiar with the procedures for running the model as a standalone component and for executing the regression tests described in the UFS WM GitHub `wiki `__ to make sure no inadvertent changes to the results have been introduced during the development process. +Those wishing to contribute development to the UFS WM should become familiar with the procedures for running the model as a standalone component and for executing the regression tests described in the UFS WM GitHub :wm-wiki:`wiki ` to make sure no inadvertent changes to the results have been introduced during the development process. -Support for the UFS WM is provided through the `UFS Forum `__ by the Developmental Testbed Center (DTC) and other groups involved in UFS development, such as NOAA's Environmental Modeling Center (:term:`EMC`), NOAA research laboratories (GFDL, NSSL, ESRL, and AOML), and :term:`NCAR`. UFS users and developers are encouraged not only to post questions, but also to help address questions posted by other members of the community. +Support for the UFS WM is provided through the :wm-repo:`UFS Forum ` by the Developmental Testbed Center (DTC) and other groups involved in UFS development, such as NOAA's Environmental Modeling Center (:term:`EMC`), NOAA research laboratories (GFDL, NSSL, ESRL, and AOML), and :term:`NCAR`. UFS users and developers are encouraged not only to post questions, but also to help address questions posted by other members of the community. This WM User's Guide is organized as follows: diff --git a/doc/UsersGuide/source/conf.py b/doc/UsersGuide/source/conf.py index ae16c27be2..7f7988e0af 100644 --- a/doc/UsersGuide/source/conf.py +++ b/doc/UsersGuide/source/conf.py @@ -47,6 +47,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', + 'sphinx.ext.extlinks', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', @@ -249,6 +250,14 @@ def warn_undocumented_members(app, what, name, obj, options, lines): intersphinx_mapping = {'landda': ('https://land-da-workflow.readthedocs.io/en/latest/', None), } +# -- Options for extlinks extension --------------------------------------- + +extlinks_detect_hardcoded_links = True +extlinks = {'nco': ('https://www.nco.ncep.noaa.gov/idsb/implementation_standards/%s', '%s'), + 'wm-repo': ('https://github.com/ufs-community/ufs-weather-model/%s', '%s'), + 'wm-wiki': ('https://github.com/ufs-community/ufs-weather-model/wiki/%s','%s'), + } + # -- Options for todo extension ---------------------------------------------- # If true, `todo` and `todoList` produce output, else they produce nothing. From 2399d6c710a0461d130f0f004fdbd8cfb5de17ff Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Fri, 15 Nov 2024 17:42:22 -0500 Subject: [PATCH 23/24] update CAPE expt for different resolutions --- doc/UsersGuide/source/CAPE2020.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/UsersGuide/source/CAPE2020.rst b/doc/UsersGuide/source/CAPE2020.rst index 2cc065da8f..3e6ee0c2aa 100644 --- a/doc/UsersGuide/source/CAPE2020.rst +++ b/doc/UsersGuide/source/CAPE2020.rst @@ -19,10 +19,13 @@ Obtaining Data for the July 2020 CAPE Case .. include:: ./doc-snippets/hsd_data.rst +.. _chgres-data: + User-Generated Data --------------------- -Users can enable the WM to run using GFS initial conditions (ICs) from the UFS Case Studies page. +Users can enable the WM to run using GFS initial conditions (ICs) from the UFS Case Studies page. Users can use these files + .. _run-cape: @@ -47,7 +50,13 @@ Machine Configuration Test Configuration ---------------------- -The July 2020 CAPE case can be run as-is without adjusting the configuration. +The July 2020 CAPE case can be run as-is without adjusting the configuration. If users choose to run the case at higher resolutions, they can generate GFS ICs at C192, C384, or C768 resolutions following the instructions :ref:`above `. However, they will also need to adapt the experiment configuration files (``${UFS_WM}/tests-dev/test_cases/tests/2020_CAPE`` and potentially ``${UFS_WM}/tests-dev/test_cases/exp_conf/2020_CAPE``). Configurations at these higher resolutions are untested, and users can expect to do some troubleshooting to make them work. + +It is recommended that users view the :wm-repo:`control_c192 `, :wm-repo:`control_c384 `, or :wm-repo:`control_c768 ` test files as a starting point. Those test files will provide guidance on variable settings and model_configure/input namelist settings. Additionally, users will need to ensure that the ``FV3_RUN`` file (named ``2020_CAPE.IN`` for the 2020_CAPE experiment) points to the correct input data. Users can modify the ``parm/fv3_conf`` files associated with the sample ``control_*`` tests to enable use of v2 surface data (as in the :wm-repo:`control_c48.v2.sfc ` or 2020_CAPE cases). + +.. attention:: + + Although it is *possible* to adjust the July 2020 CAPE case to run at non-default resolutions, this is unsupported functionality. Users may experiment with the capability but will need to commit to significant troubleshooting/experimentation to run the case at those resolutions. Baseline Configuration ---------------------- From 39e5508a46f6d58ad20a54f750ff9ad599d0a1b3 Mon Sep 17 00:00:00 2001 From: gspetro-NOAA Date: Fri, 15 Nov 2024 17:54:33 -0500 Subject: [PATCH 24/24] add Jet instructions --- doc/UsersGuide/source/baroclinic_wave.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/UsersGuide/source/baroclinic_wave.rst b/doc/UsersGuide/source/baroclinic_wave.rst index 99ed13877d..ffa5e16802 100644 --- a/doc/UsersGuide/source/baroclinic_wave.rst +++ b/doc/UsersGuide/source/baroclinic_wave.rst @@ -55,6 +55,15 @@ It is recommended that users adjust certain values in the baroclinic wave case. In general, it is preferable to make ``FHMAX`` a multiple of 24. +On Jet, users will also need to adjust ``${UFS_WM}/tests/fv3_conf/compile_slurm.IN_jet`` in order to manage memory requirements for longer runs of the ``baroclinic_wave`` test. Users will need to change the number of tasks per node from 8 to 6 and add ``#SBATCH --mem=0``. + +The file should say: + +.. code-block:: console + + #SBATCH --ntasks-per-node=6`` + #SBATCH --mem=0 + Baseline Configuration ----------------------