From e0c82bf656abca81e851a67e95c613fae76c16af Mon Sep 17 00:00:00 2001 From: Valbona Kunkel Date: Mon, 13 Jan 2020 17:56:43 -0500 Subject: [PATCH 01/11] update chapter about model development with info from Wiki --- .../source/ContributingDevelopment.rst | 280 ++++++++++++++++++ 1 file changed, 280 insertions(+) diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst index 1f7a985969..9d851e4c19 100644 --- a/doc/UsersGuide/source/ContributingDevelopment.rst +++ b/doc/UsersGuide/source/ContributingDevelopment.rst @@ -13,4 +13,284 @@ Contributing Development * What are the requirements for a code to be accepted? * What platforms are supported + +================================ + ufs-community/ufs-weather-model +================================ + +----------------------- + Prerequisite libraries: +----------------------- + +Below is the list of libraries that are required to compile the model and run regression tests: + ++-------------+---------------------------------------------------------------------+---------+----------------+ +| Library name| source |version | env variables | ++=============+=====================================================================+=========+================+ +| bacio |https://github.com/NOAA-EMC/NCEPLIBS-bacio | 2.0.3 | $BACIO_LIB4 | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| sp |https://github.com/NOAA-EMC/NCEPLIBS-sp | 2.0.3 | $SP_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| w3nco |https://github.com/NOAA-EMC/NCEPLIBS-w3nco | 2.0.7 | $W3NCO_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| w3emc |https://github.com/NOAA-EMC/NCEPLIBS-w3emc | 2.3.1 | $W3EMC_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| nemsio |https://github.com/NOAA-EMC/NCEPLIBS-nemsio | 2.2.4 | $NEMSIO_INC | ++ + + + + +| | | | $NEMSIO_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| g2 |https://github.com/NOAA-EMC/NCEPLIBS-g2 |3.1.1 | $G2_LIB4 | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| g2tmpl |https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl(required for inline post)|1.5.1 | $G2TMPL_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| crtm |https://github.com/NOAA-EMC/EMC_crtm (required for inline post) |2.2.6 | $CRTM_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| post | http://github.com/NOAA-EMC/EMC_post (required for inline post) | 8.0.0 | $POST_INC | ++ + + + + +| | | | $POST_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ + +External libraries: + + ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| Library name| source |version | env variables | ++=============+==============================================================+=========+=========================+ +| | | |$ESMFMKFILE, | ++ + + + + +| | | |$ESMF_F90COMPILEPATHS, | ++ + + + + +|esmf |https://www.earthsystemcog.org/projects/esmf/download_800 | 8.0.0 |$ESMF_F90ESMFLINKPATHS, | ++ + + + + +| | | |$(ESMF_F90ESMFLINKRPATHS)| ++ + + + + +| | | |$(ESMF_F90ESMFLINKLIBS) | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| | | 4.5.0 | | ++ + + + + +| NetCDF |https://www.unidata.ucar.edu/downloads/netcdf/index.jsp | 4.6.1 |$NETCDF or($NETCDF_DIR) | ++ + + + + +| | | 4.6.3 | | ++ + + + + +| | | 4.7.0 | | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| | | 1.8.14 | | ++ + + + + +|HDF5 | https://www.hdfgroup.org/downloads/hdf5/ | 1.8.16 | $HDF5 | ++ + + + + +| | | 1.10.1 | | ++ + + + + +| | | 1.10.4 | | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|jasper | https://github.com/mdadams/jasper | 1.900.1 | $JASPER_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|zlib | https://github.com/madler/zlib | 1.2.11 | $Z_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|libpng | http://www.libpng.org/pub/png/libpng.html | 1.2.44 | $PNG_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ + + +Compiler: + + ++--------------------+------------------------------------------------------------------+ +|Compiler name | Branch name | ++====================+==================================================================+ +| Intel | 16.0.3.210,16.3.210,18.0.1.163, 18.0.3.222,18.0.5.274, 19.0.2 | ++--------------------+------------------------------------------------------------------+ +|impi | 2018.0.4, 2018.4.274,18.0.1, 2019.2.187 | ++--------------------+------------------------------------------------------------------+ + + +These libraries are available on several platforms including Hera, Cheyenne and WCOSS. Installing these libraries on jet and gaea is a work in progress. + +In addition to these libraries, other software is required such as a compiler (Intel or GNU), MPI library (impi), HDF5, cmake, Python, Perl and Ruby to compile the model and run regression tests. + +----------------------- +Making code changes using a forking workflow +----------------------- + +If developers would like to make code changes, they need to make a personal fork, set up upstream remote (for merging with the original ufs-weather-model), and create a branch for ufs-weather-model and each of the subcomponent repositories they want to change. They can then make code changes, perform testing and commit the changes to the branch in their personal fork. It is suggested that they merge their branch with the develop branch of the original repositories periodically to get the latest updates and bug fixes. + +If developers would like to get their code committed back to the original repository, it is suggested to follow the steps below: + + # Create an issue in the authoritative repository. For example to commit code changes to fv3atm, please go to https://github.com/NOAA-EMC/fv3atm, under NOAA-EMC/fv3atm and find the “Issues” tab next to the “Code” tab. Click on “Issues” and a new page will appear. On the right side of the page, there is a green “New issue” button. Clicking on that will lead to a new issue page. Fill out the title, comments to describe the code changes, and also please provide personal fork and branch information. Lastly, click on the “Submit new issue” button, so that the new issue is created. + + # When the development is mature, tests have been conducted, and the developer is satisfied with the results, create a pull request to commit the code changes. + + * Merge developer’s branch to the latest ufs-weather-model develop branch in authoritative repository. If changes are made in model sub-components, developers need to merge their branches to branches with the corresponding authoritative repository (or original repository for some components). For this, code management practices of the subcomponents need to be followed. + + * Regression tests need to pass on at least one supported platform. + + * For each component branch where developers make changes, developers need to go to their personal fork on GitHub and click on the “New pull request” button. When a new page “Compare changes” appears, developers will choose the branch in their fork with code changes to commit and the branch in upstream repository that the changes will be committed to. The code differences between the two branches will be displayed. Developers can review the differences and click on “submit pull request” to make the pull request. After code changes are committed to the component repository, developers will make pull requests to ufs-weather-model repository. + +It is suggested that the developers inform all the related code managers as the hierarchy structure of the ufs-weather-model repository may require collaboration among the code managers. + +----------------------- +Engaging in the code review process +----------------------- + +When code managers receive a pull request to commit the code changes, it is recommended that they add at least two code reviewers to review the code. The reviewers will write comments about the code changes and give a recommendation as to whether the code changes can be committed. What kinds of code changes will be accepted in the repository is beyond the scope of this document; future ufs-weather-model code management may have detailed answer for that. + +Reviewers may suggest some code changes during the review process. Developers need to respond to these comments in order to get code changes committed. If developers make further changes to their branch, reviewers need to check the code changes again. When both reviewers give recommendation to commit the code, code managers will merge the changes into the repository. + +----------------------- +Conducting regression tests +----------------------- + +Only developers that are running on a limited set of platforms (Hera, Cheyenne, WCOSS) can compile and run regression tests using the ufs-weather-model. + +To run regression test using rt.sh + +.. code-block:: console + + % cd ufs-weather-model/tests + % ./rt.sh -f + +Regression test log files (ufs-weather-model/tests/Compile_$(MACHINE_ID).log and ufs-weather-model/tests/RegressionTests_$(MACHINE_ID).log ) will be updated. + +To create new baseline: + +.. code-block:: console + + % cd ufs-weather-model/tests + % ./rt.sh -f -c + + * To run regression test using NEMSCompsetRun + +.. code-block:: console + + % cd ufs-weather-model + % ./NEMS/NEMSCompsetRun -f + +Regression test log files (ufs-weather-model/log/$MACHINE_ID/* ) will be updated. + +To create new baseline: + +.. code-block:: console + + % cd ufs-weather-model + % ./NEMS/NEMSCompsetRun--baseline fv3 --platform=${PLATFORM} + + +The value of ${PLATFORM} can be found in ufs-weather-model/compsets/platforms.input. + +Developers need to commit the regression test log files to their branch before making pull request. + +----------------------- +Compiling the code and running a test +----------------------- + +Currently developers running on Hera, Cheyenne or WCOSS can compile and run tests using the ufs-weather-model. In the document below, ufs-weather-model directory points to a branch in the developer’s personal fork. + + * Compile and run a test using rt.sh + + i) compile the code + +Developers can compile the ufs-weather-model using the compile script ufs_weather_model/tests/compile.sh. To compile the code: + +.. code-block:: console + + % git clone --recursive https://github.com/ufs-community/ufs-weather-model + % cd ufs-weather-model/tests + % ./compile.sh PATHTR MACHINE_ID MAKE_OPT BUILD_NR + + +Where: + +.. code-block:: console + + PATHTR: the full path of FV3 directory under ufs-weather-model + MACHINE_ID: machine ID, e.g: wcoss_cray, hera.intel + MAKE_OPT: compile options, default (‘’, empty string) is for 64-bit OpenMP non-hydrostatic build using AVX2, other options are: + - ‘DEBUG=Y’: turn on debug option + - ‘VERBOSE=Y’: turn on VERBOSE mode to get additional details on compile + - ‘OPENMP=Y’: use openmp + - ‘AVX2=Y’: use AVX2 in Intel Haswell for better performance. + - ‘HYDRO=Y’: hydrostatic mode + - ‘CCPP=Y’: using ccpp framework and physics + - ‘STATIC=Y’: when CCPP=Y, using static build instead of dynamic build + - ‘SUITE=xxx': CCPP physics suite, e.g. “FV3_GFS_2017_gfdlmp” + BUILD_NR: the number of build (there might be several copies of the executable). The final executable would be fv3_${BUILD_NR}.exe + + +Example: + +.. code-block:: console + + % ./compile.sh /gpfs/hps/emc/global/noscrub/First.Last/ufs-weather-model/FV3 wcoss_cray '' 1 + +The executable generated from the compile.sh can be used in global workflow to run experiments. + + ii) run a regression test + +Developers can run a single regression test from the regression test suite. The full list of the regression tests can be found at: + +.. code-block:: console + + us-weather-model/tests/fv3_conf + +To run a specific regression test: + +.. code-block:: console + + %cd ufs_weather_model/tests + % cp rt.conf rt.conf1 + +Edit the rt.conf1 file, keep the test developers intended to run and remove all the rest tests. + +COMPILE | fv3 | standard| wcoss_cray | | +RUN | fv3_control | standard| | | + + +To compile and run the test, do + +.. code-block:: console + + % ./rt.sh -l rt.conf1 + +The code will be compiled and run on wcoss_cray. A log directory will be shown at: ufs-weather-model/tests /log_$MACHINE_ID. If there are compile errors, please check file: compile_${BUILD_NR}.log under above log directory. If the code is successfully compiled, but the job failed, please go to above log directory to look for rt_${test_number}_${test_id}.log for details. + + * Compile and run a test using NEMSCompsetRun + + i) Compile the code + +.. code-block:: console + + % cd ufs-weather-model + % ./NEMS/NEMSAppBuilder app=coupledFV3_WW3 + +ii) Run a regression test + +NEMSCompsetRun runs the same tests as rt.sh. The two share the same baseline results. To run a single test using NEMSCompsetRun: + +.. code-block:: console + + % cd ufs-weather-model + % ./NEMS/NEMSCompsetRun “{test_name}” + +The test name can be found in compsets/all.input. + + + + + + + + + + + + + + + + + + + + + + + From 3a58dfa1febe58e684daff3af46b36f03afa149e Mon Sep 17 00:00:00 2001 From: Valbona Kunkel Date: Wed, 15 Jan 2020 22:03:40 -0500 Subject: [PATCH 02/11] fixed all bugs --- doc/UsersGuide/.DS_Store | Bin 0 -> 8196 bytes doc/UsersGuide/source/.DS_Store | Bin 0 -> 6148 bytes .../source/ContributingDevelopment.rst | 24 +++++++++--------- 3 files changed, 12 insertions(+), 12 deletions(-) create mode 100644 doc/UsersGuide/.DS_Store create mode 100644 doc/UsersGuide/source/.DS_Store diff --git a/doc/UsersGuide/.DS_Store b/doc/UsersGuide/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..392a5fb37fa76753a158aecb8bed88b734880de1 GIT binary patch literal 8196 zcmeHMU2GIp6h5c4Wo9V!77OhlTQ<}xV1fSH)3-v*_O5xD6>0bJ35`IJF{J& z7Mu8D4E{Z+VDv>36H}j1OnfrN7yM7OM%3`&gAe-RqtR&Mx%bXCcA<}I6Xqs!&%O7Y zbMHOhd^2~?EC66{&TIy#1ptLEF4;P&Zcwsg3Fgfe3+{5&`~xh||SoB9!w|idP3!A_X8>O2eX1 zoALnR6Axt~l=D&wSDI614;Z>)m|~!GCw-iolT3tiUP|c>DBS_Wl`+gvP^?aVabXUa zkTR+x1R?~kM}X(r za(vi!O)uZ;{wl z=Ird_bLTF|Xfb?aKxI+%7pcE2#=^%7?yyYZ_%nSn_>z|k!CzepUR$U4->)4Uu``~V zvd>!MtkS30`>8vSwPq;J;f&|xrd)rVRb>n(lXHx~>Tw)y?2iQ2>43M6`Cc~Y6NclA z<$UXiMRxX#l_YC&-NmRkUKFRt-lZ;7SsMr+Se*2wG?RVdkTwK4Ql4%>Y z>fssNx6_U_l()@ba@6oMmTTJX#4$qC4eW<)E2~!Ff;#9LQ`X|G~Mg^kproO+}HL+M(}KnV}5& z6t5iFt?gBruMR#+w_J?qEn1txOm)aH(v~BKI;YauxeudxR5BL-Q!g8#{tyqWKFpfL1 z9q+;pOkfZ8VG{fC2&QldkK!1bXyF7-qKkPvjc0KdpTzU{3_g!9;4AnBUcz_rGQNi& z;K%q0eu|&rH~2mNAop2P;PN5aFVuLATE&zNpVyL;H==Cp-utxV|4P~KDmYK8Hr`Ub zsjhyyJxjN;=nnpqN`gC*9D+0jQixl)jE$Vp`j%U@*bs5cI$it}6nM_oauz9z zIx!>`k8M|oFD&df#O_dt)T~6zwR2ZYV{3@Ns_5?7tHoFuQB@J$);3LJrNm{a?d&3L zIk8r1_ji*P_|v9}m9&OfQdJlhb8tllz6F=yL-?GycNMO|Pw)%;hCr;Vz|F+EIM(BB z*noR*FE(Qfw&8y44*7QwAH)HCh&VWgCvY53p@EN}Lk#qA8qW{|=kOdpfluMn#KULt zIlO=uiHon|YxpKE6fv*Az&R=L?PBK5q_VE#xf3*AVC!<1sJBWGSR?mQ%k%#OD}VoA zCA*Eb5g`yE@NXc1rO8yXmu6n+ea&<2I9;dc;)UDIODSBa66rWek&csG`ooagaWdsT ciBQfH1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3 zem<@ulZcFPQ@L2!n>{z**++&mCkOWA81W14cNZlEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ zLs35+`xjp>T0 Date: Fri, 17 Jan 2020 13:54:40 -0500 Subject: [PATCH 03/11] Delete .DS_Store --- doc/UsersGuide/.DS_Store | Bin 8196 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 doc/UsersGuide/.DS_Store diff --git a/doc/UsersGuide/.DS_Store b/doc/UsersGuide/.DS_Store deleted file mode 100644 index 392a5fb37fa76753a158aecb8bed88b734880de1..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 8196 zcmeHMU2GIp6h5c4Wo9V!77OhlTQ<}xV1fSH)3-v*_O5xD6>0bJ35`IJF{J& z7Mu8D4E{Z+VDv>36H}j1OnfrN7yM7OM%3`&gAe-RqtR&Mx%bXCcA<}I6Xqs!&%O7Y zbMHOhd^2~?EC66{&TIy#1ptLEF4;P&Zcwsg3Fgfe3+{5&`~xh||SoB9!w|idP3!A_X8>O2eX1 zoALnR6Axt~l=D&wSDI614;Z>)m|~!GCw-iolT3tiUP|c>DBS_Wl`+gvP^?aVabXUa zkTR+x1R?~kM}X(r za(vi!O)uZ;{wl z=Ird_bLTF|Xfb?aKxI+%7pcE2#=^%7?yyYZ_%nSn_>z|k!CzepUR$U4->)4Uu``~V zvd>!MtkS30`>8vSwPq;J;f&|xrd)rVRb>n(lXHx~>Tw)y?2iQ2>43M6`Cc~Y6NclA z<$UXiMRxX#l_YC&-NmRkUKFRt-lZ;7SsMr+Se*2wG?RVdkTwK4Ql4%>Y z>fssNx6_U_l()@ba@6oMmTTJX#4$qC4eW<)E2~!Ff;#9LQ`X|G~Mg^kproO+}HL+M(}KnV}5& z6t5iFt?gBruMR#+w_J?qEn1txOm)aH(v~BKI;YauxeudxR5BL-Q!g8#{tyqWKFpfL1 z9q+;pOkfZ8VG{fC2&QldkK!1bXyF7-qKkPvjc0KdpTzU{3_g!9;4AnBUcz_rGQNi& z;K%q0eu|&rH~2mNAop2P;PN5aFVuLATE&zNpVyL;H==Cp-utxV|4P~KDmYK8Hr`Ub zsjhyyJxjN;=nnpqN`gC*9D+0jQixl)jE$Vp`j%U@*bs5cI$it}6nM_oauz9z zIx!>`k8M|oFD&df#O_dt)T~6zwR2ZYV{3@Ns_5?7tHoFuQB@J$);3LJrNm{a?d&3L zIk8r1_ji*P_|v9}m9&OfQdJlhb8tllz6F=yL-?GycNMO|Pw)%;hCr;Vz|F+EIM(BB z*noR*FE(Qfw&8y44*7QwAH)HCh&VWgCvY53p@EN}Lk#qA8qW{|=kOdpfluMn#KULt zIlO=uiHon|YxpKE6fv*Az&R=L?PBK5q_VE#xf3*AVC!<1sJBWGSR?mQ%k%#OD}VoA zCA*Eb5g`yE@NXc1rO8yXmu6n+ea&<2I9;dc;)UDIODSBa66rWek&csG`ooagaWdsT ciBQf Date: Fri, 17 Jan 2020 14:06:04 -0500 Subject: [PATCH 04/11] Delete .DS_Store --- doc/UsersGuide/source/.DS_Store | Bin 6148 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 doc/UsersGuide/source/.DS_Store diff --git a/doc/UsersGuide/source/.DS_Store b/doc/UsersGuide/source/.DS_Store deleted file mode 100644 index 5008ddfcf53c02e82d7eee2e57c38e5672ef89f6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3 zem<@ulZcFPQ@L2!n>{z**++&mCkOWA81W14cNZlEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ zLs35+`xjp>T0 Date: Tue, 28 Jan 2020 13:15:09 -0500 Subject: [PATCH 05/11] update the file ContributingDevelopment.rst --- .../source/ContributingDevelopment.rst | 198 +++++++++++++++++- 1 file changed, 193 insertions(+), 5 deletions(-) diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst index 1f7a985969..2dcd1e4f9d 100644 --- a/doc/UsersGuide/source/ContributingDevelopment.rst +++ b/doc/UsersGuide/source/ContributingDevelopment.rst @@ -4,13 +4,201 @@ Contributing Development ************************* -* Overview; big picture +The ufs-weather-model repository contains the model code and external links needed to build the Unified Forecast System (UFS) atmosphere model and associated components, including the WaveWatch III model. This weather model is used in several of the UFS applications, including the medium-range weather application, the short-range weather application, and the sub-seasonal to seasonal application. -* Opening issues +------------------------ + Prerequisite libraries: +------------------------ -* Description of development workflow (fork, branch, commit, test, PR submission, review) +Below is the list of libraries that are required to compile the model and run regression tests: -* What are the requirements for a code to be accepted? ++-------------+---------------------------------------------------------------------+---------+----------------+ +| Library name| source |version | env variables | ++=============+=====================================================================+=========+================+ +| bacio |https://github.com/NOAA-EMC/NCEPLIBS-bacio | 2.0.3 | $BACIO_LIB4 | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| sp |https://github.com/NOAA-EMC/NCEPLIBS-sp | 2.0.3 | $SP_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| w3nco |https://github.com/NOAA-EMC/NCEPLIBS-w3nco | 2.0.7 | $W3NCO_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| w3emc |https://github.com/NOAA-EMC/NCEPLIBS-w3emc | 2.3.1 | $W3EMC_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| nemsio |https://github.com/NOAA-EMC/NCEPLIBS-nemsio | 2.2.4 | $NEMSIO_INC | ++ + + + + +| | | | $NEMSIO_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| g2 |https://github.com/NOAA-EMC/NCEPLIBS-g2 |3.1.1 | $G2_LIB4 | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| g2tmpl |https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl(required for inline post)|1.5.1 | $G2TMPL_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| crtm |https://github.com/NOAA-EMC/EMC_crtm (required for inline post) |2.2.6 | $CRTM_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| post | http://github.com/NOAA-EMC/EMC_post (required for inline post) | 8.0.0 | $POST_INC | ++ + + + + +| | | | $POST_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ -* What platforms are supported +External libraries: + + ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| Library name| source |version | env variables | ++=============+==============================================================+=========+=========================+ +| | | |$ESMFMKFILE, | ++ + + + + +| | | |$ESMF_F90COMPILEPATHS, | ++ + + + + +|esmf |https://www.earthsystemcog.org/projects/esmf/download_800 | 8.0.0 |$ESMF_F90ESMFLINKPATHS, | ++ + + + + +| | | |$(ESMF_F90ESMFLINKRPATHS)| ++ + + + + +| | | |$(ESMF_F90ESMFLINKLIBS) | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| | | 4.5.0 | | ++ + + + + +| NetCDF |https://www.unidata.ucar.edu/downloads/netcdf/index.jsp | 4.6.1 |$NETCDF or($NETCDF_DIR) | ++ + + + + +| | | 4.6.3 | | ++ + + + + +| | | 4.7.0 | | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| | | 1.8.14 | | ++ + + + + +|HDF5 | https://www.hdfgroup.org/downloads/hdf5/ | 1.8.16 | $HDF5 | ++ + + + + +| | | 1.10.1 | | ++ + + + + +| | | 1.10.4 | | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|jasper | https://github.com/mdadams/jasper | 1.900.1 | $JASPER_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|zlib | https://github.com/madler/zlib | 1.2.11 | $Z_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|libpng | http://www.libpng.org/pub/png/libpng.html | 1.2.44 | $PNG_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ + + +Compiler: + + ++--------------------+------------------------------------------------------------------+ +|Compiler name | Branch name | ++====================+==================================================================+ +| Intel | 16.0.3.210,16.3.210,18.0.1.163, 18.0.3.222,18.0.5.274, 19.0.2 | ++--------------------+------------------------------------------------------------------+ +|impi | 2018.0.4, 2018.4.274,18.0.1, 2019.2.187 | ++--------------------+------------------------------------------------------------------+ + + +These libraries are available on several platforms including Hera, Cheyenne and WCOSS. Installing these libraries on jet and gaea is a work in progress. Users who need to build the libraries. [https://github.com/NOAA-EMC/NCEPLIBS/wiki/Cloning-and-Compiling-NCEPLIBS] + +In addition to these libraries, other software is required such as a compiler (Intel or GNU), MPI library (impi), HDF5, cmake, Python, Perl and Ruby to compile the model and run regression tests. + +--------------------------------------------- +Making code changes using a forking workflow +--------------------------------------------- + +If developers would like to make code changes, they need to make a personal fork, set up upstream remote (for merging with the original ufs-weather-model), and create a branch for ufs-weather-model and each of the subcomponent repositories they want to change. They can then make code changes, perform testing and commit the changes to the branch in their personal fork. It is suggested that they merge their branch with the develop branch of the original repositories periodically to get the latest updates and bug fixes. + +If developers would like to get their code committed back to the original repository, it is suggested to follow the steps below: + +1. Create an issue in the authoritative repository. For example to commit code changes to fv3atm, please go to https://github.com/NOAA-EMC/fv3atm, under NOAA-EMC/fv3atm and find the “Issues” tab next to the “Code” tab. Click on “Issues” and a new page will appear. On the right side of the page, there is a green “New issue” button. Clicking on that will lead to a new issue page. Fill out the title, comments to describe the code changes, and also please provide personal fork and branch information. Lastly, click on the “Submit new issue” button, so that the new issue is created. + +2. When the development is mature, tests have been conducted, and the developer is satisfied with the results, create a pull request to commit the code changes. + + * Merge developer’s branch to the latest ufs-weather-model develop branch in authoritative repository. If changes are made in model sub-components, developers need to merge their branches to branches with the corresponding authoritative repository (or original repository for some components). For this, code management practices of the subcomponents need to be followed. + + * Regression tests associated with the ufs-weather-model are available in Tier 1 and Tier 2 platforms as described in https://github.com/ufs-community/ufs-weather-model/wiki/Weather-Model-Platform-and-Compiler-Support. If the developer has access to these platforms, the developer should pass the regression test on at least one supported platform. If the developer does not have access to these platforms, this should be stated in the PR so the code manager(s) can conduct the tests. + + * For each component branch where developers make changes, developers need to go to their personal fork on GitHub and click on the “New pull request” button. When a new page “Compare changes” appears, developers will choose the branch in their fork with code changes to commit and the branch in upstream repository that the changes will be committed to. Also developers in the commit comment must add the github issue title and number created in 1) in the comment box. The code differences between the two branches will be displayed. Developers can review the differences and click on “submit pull request” to make the pull request. After code changes are committed to the component repository, developers will make pull requests to ufs-weather-model repository. + +3. When PRs are created, the creator must temporarily modify .gitmodules to point to his/her fork and branch if updates are required for submodules. + +4. Merging code from PRs with submodules requires coordination with the person making the PRs. From the "innermost" nested PR up to the top-level PR, the PRs need to be merged as-is. After each merge, the person creating the PRs has to update his/her local code to check out the merged version, revert the change to .gitmodules, and push this to GitHub to update the PR. And so on and so forth. + +5. Checking out the code ufs_release_1.0 should always be as follows: + +.. code-block:: console + + git clone https://github.com/ufs-community/ufs-weather-model + cd ufs-weather-model + git checkout ufs_release_1.00 + git submodule update --init --recursive + +6. Checking out a PR with id ID for testing it should always be as follows: + +.. code-block:: console + + git clone https://github.com/ufs-community/ufs-weather-model + cd ufs-weather-model + git fetch origin pull/ID/head:BRANCHNAME + git checkout BRANCHNAME + git submodule update --init --recursive + +It is suggested that the developers inform all the related code managers as the hierarchy structure of the ufs-weather-model repository may require collaboration among the code managers. + +----------------------------------- +Engaging in the code review process +----------------------------------- + +When code managers receive a pull request to commit the code changes, it is recommended that they add at least two code reviewers to review the code and at least one of the reviewers has write permission. The reviewers will write comments about the code changes and give a recommendation as to whether the code changes can be committed. What kinds of code changes will be accepted in the repository is beyond the scope of this document; future ufs-weather-model code management may have detailed answer for that. + +Reviewers may suggest some code changes during the review process. Developers need to respond to these comments in order to get code changes committed. If developers make further changes to their branch, reviewers need to check the code changes again. When both reviewers give recommendation to commit the code, code managers will merge the changes into the repository. + +---------------------------- +Conducting regression tests +---------------------------- + +Only developers that are running on a limited set of platforms (Hera, Cheyenne, WCOSS) can compile and run regression tests using the ufs-weather-model. + +To run regression test using rt.sh + +rt.sh is a bash shell file to run the RT and has the following options: + +.. code-block:: console + + Usage: $0 -c | -f | -s | -l | -m | -r | -e | -h + -c create new baseline results for + -f run full suite of regression tests + -s run standard suite of regression tests + -l run test specified in + -m compare against new baseline results + -r use Rocoto workflow manager + -e use ecFlow workflow manager + -h display this help + +.. code-block:: console + + % cd ufs-weather-model/tests + % ./rt.sh -f + +Regression test log files (ufs-weather-model/tests/Compile_$(MACHINE_ID).log and ufs-weather-model/tests/RegressionTests_$(MACHINE_ID).log ) will be updated. + +To create new baseline: + +.. code-block:: console + + % cd ufs-weather-model/tests + % ./rt.sh -f -c + + * To run regression test using NEMSCompsetRun + +.. code-block:: console + + % cd ufs-weather-model + % ./NEMS/NEMSCompsetRun -f + +Regression test log files (ufs-weather-model/log/$MACHINE_ID/* ) will be updated. + +To create new baseline: + +.. code-block:: console + + % cd ufs-weather-model + % ./NEMS/NEMSCompsetRun--baseline fv3 --platform=${PLATFORM} + + +The value of ${PLATFORM} can be found in ufs-weather-model/compsets/platforms.input. + +Developers need to commit the regression test log files to their branch before making pull request. From 9b80926d4dc76c6ffd81887950ad7e1f2b2f66fd Mon Sep 17 00:00:00 2001 From: valbonakunkel-noaa <36248012+valbonakunkel-noaa@users.noreply.github.com> Date: Tue, 28 Jan 2020 13:57:17 -0500 Subject: [PATCH 06/11] Delete ContributingDevelopment.rst --- .../source/ContributingDevelopment.rst | 484 ------------------ 1 file changed, 484 deletions(-) delete mode 100644 doc/UsersGuide/source/ContributingDevelopment.rst diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst deleted file mode 100644 index 3d93e253ce..0000000000 --- a/doc/UsersGuide/source/ContributingDevelopment.rst +++ /dev/null @@ -1,484 +0,0 @@ -.. _ContributingDevelopment: - -************************* -Contributing Development -************************* - -The ufs-weather-model repository contains the model code and external links needed to build the Unified Forecast System (UFS) atmosphere model and associated components, including the WaveWatch III model. This weather model is used in several of the UFS applications, including the medium-range weather application, the short-range weather application, and the sub-seasonal to seasonal application. - ------------------------- - Prerequisite libraries: ------------------------- - -Below is the list of libraries that are required to compile the model and run regression tests: - -+-------------+---------------------------------------------------------------------+---------+----------------+ -| Library name| source |version | env variables | -+=============+=====================================================================+=========+================+ -| bacio |https://github.com/NOAA-EMC/NCEPLIBS-bacio | 2.0.3 | $BACIO_LIB4 | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| sp |https://github.com/NOAA-EMC/NCEPLIBS-sp | 2.0.3 | $SP_LIBd | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| w3nco |https://github.com/NOAA-EMC/NCEPLIBS-w3nco | 2.0.7 | $W3NCO_LIBd | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| w3emc |https://github.com/NOAA-EMC/NCEPLIBS-w3emc | 2.3.1 | $W3EMC_LIBd | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| nemsio |https://github.com/NOAA-EMC/NCEPLIBS-nemsio | 2.2.4 | $NEMSIO_INC | -+ + + + + -| | | | $NEMSIO_LIB | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| g2 |https://github.com/NOAA-EMC/NCEPLIBS-g2 |3.1.1 | $G2_LIB4 | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| g2tmpl |https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl(required for inline post)|1.5.1 | $G2TMPL_LIB | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| crtm |https://github.com/NOAA-EMC/EMC_crtm (required for inline post) |2.2.6 | $CRTM_LIB | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| post | http://github.com/NOAA-EMC/EMC_post (required for inline post) | 8.0.0 | $POST_INC | -+ + + + + -| | | | $POST_LIB | -+-------------+---------------------------------------------------------------------+---------+----------------+ - -External libraries: - - -+-------------+--------------------------------------------------------------+---------+-------------------------+ -| Library name| source |version | env variables | -+=============+==============================================================+=========+=========================+ -| | | |$ESMFMKFILE, | -+ + + + + -| | | |$ESMF_F90COMPILEPATHS, | -+ + + + + -|esmf |https://www.earthsystemcog.org/projects/esmf/download_800 | 8.0.0 |$ESMF_F90ESMFLINKPATHS, | -+ + + + + -| | | |$(ESMF_F90ESMFLINKRPATHS)| -+ + + + + -| | | |$(ESMF_F90ESMFLINKLIBS) | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -| | | 4.5.0 | | -+ + + + + -| NetCDF |https://www.unidata.ucar.edu/downloads/netcdf/index.jsp | 4.6.1 |$NETCDF or($NETCDF_DIR) | -+ + + + + -| | | 4.6.3 | | -+ + + + + -| | | 4.7.0 | | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -| | | 1.8.14 | | -+ + + + + -|HDF5 | https://www.hdfgroup.org/downloads/hdf5/ | 1.8.16 | $HDF5 | -+ + + + + -| | | 1.10.1 | | -+ + + + + -| | | 1.10.4 | | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -|jasper | https://github.com/mdadams/jasper | 1.900.1 | $JASPER_LIB | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -|zlib | https://github.com/madler/zlib | 1.2.11 | $Z_LIB | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -|libpng | http://www.libpng.org/pub/png/libpng.html | 1.2.44 | $PNG_LIB | -+-------------+--------------------------------------------------------------+---------+-------------------------+ - - -Compiler: - - -+--------------------+------------------------------------------------------------------+ -|Compiler name | Branch name | -+====================+==================================================================+ -| Intel | 16.0.3.210,16.3.210,18.0.1.163, 18.0.3.222,18.0.5.274, 19.0.2 | -+--------------------+------------------------------------------------------------------+ -|impi | 2018.0.4, 2018.4.274,18.0.1, 2019.2.187 | -+--------------------+------------------------------------------------------------------+ - - -These libraries are available on several platforms including Hera, Cheyenne and WCOSS. Installing these libraries on jet and gaea is a work in progress. Users who need to build the libraries. [https://github.com/NOAA-EMC/NCEPLIBS/wiki/Cloning-and-Compiling-NCEPLIBS] - -In addition to these libraries, other software is required such as a compiler (Intel or GNU), MPI library (impi), HDF5, cmake, Python, Perl and Ruby to compile the model and run regression tests. - ---------------------------------------------- -Making code changes using a forking workflow ---------------------------------------------- - -If developers would like to make code changes, they need to make a personal fork, set up upstream remote (for merging with the original ufs-weather-model), and create a branch for ufs-weather-model and each of the subcomponent repositories they want to change. They can then make code changes, perform testing and commit the changes to the branch in their personal fork. It is suggested that they merge their branch with the develop branch of the original repositories periodically to get the latest updates and bug fixes. - -If developers would like to get their code committed back to the original repository, it is suggested to follow the steps below: - -1. Create an issue in the authoritative repository. For example to commit code changes to fv3atm, please go to https://github.com/NOAA-EMC/fv3atm, under NOAA-EMC/fv3atm and find the “Issues” tab next to the “Code” tab. Click on “Issues” and a new page will appear. On the right side of the page, there is a green “New issue” button. Clicking on that will lead to a new issue page. Fill out the title, comments to describe the code changes, and also please provide personal fork and branch information. Lastly, click on the “Submit new issue” button, so that the new issue is created. - -2. When the development is mature, tests have been conducted, and the developer is satisfied with the results, create a pull request to commit the code changes. - - * Merge developer’s branch to the latest ufs-weather-model develop branch in authoritative repository. If changes are made in model sub-components, developers need to merge their branches to branches with the corresponding authoritative repository (or original repository for some components). For this, code management practices of the subcomponents need to be followed. - - * Regression tests associated with the ufs-weather-model are available in Tier 1 and Tier 2 platforms as described in https://github.com/ufs-community/ufs-weather-model/wiki/Weather-Model-Platform-and-Compiler-Support. If the developer has access to these platforms, the developer should pass the regression test on at least one supported platform. If the developer does not have access to these platforms, this should be stated in the PR so the code manager(s) can conduct the tests. - - * For each component branch where developers make changes, developers need to go to their personal fork on GitHub and click on the “New pull request” button. When a new page “Compare changes” appears, developers will choose the branch in their fork with code changes to commit and the branch in upstream repository that the changes will be committed to. Also developers in the commit comment must add the github issue title and number created in 1) in the comment box. The code differences between the two branches will be displayed. Developers can review the differences and click on “submit pull request” to make the pull request. After code changes are committed to the component repository, developers will make pull requests to ufs-weather-model repository. - -3. When PRs are created, the creator must temporarily modify .gitmodules to point to his/her fork and branch if updates are required for submodules. - -4. Merging code from PRs with submodules requires coordination with the person making the PRs. From the "innermost" nested PR up to the top-level PR, the PRs need to be merged as-is. After each merge, the person creating the PRs has to update his/her local code to check out the merged version, revert the change to .gitmodules, and push this to GitHub to update the PR. And so on and so forth. - -5. Checking out the code ufs_release_1.0 should always be as follows: - -.. code-block:: console - - git clone https://github.com/ufs-community/ufs-weather-model - cd ufs-weather-model - git checkout ufs_release_1.00 - git submodule update --init --recursive - -6. Checking out a PR with id ID for testing it should always be as follows: - -.. code-block:: console - - git clone https://github.com/ufs-community/ufs-weather-model - cd ufs-weather-model - git fetch origin pull/ID/head:BRANCHNAME - git checkout BRANCHNAME - git submodule update --init --recursive - -It is suggested that the developers inform all the related code managers as the hierarchy structure of the ufs-weather-model repository may require collaboration among the code managers. - ------------------------------------ -Engaging in the code review process ------------------------------------ - -When code managers receive a pull request to commit the code changes, it is recommended that they add at least two code reviewers to review the code and at least one of the reviewers has write permission. The reviewers will write comments about the code changes and give a recommendation as to whether the code changes can be committed. What kinds of code changes will be accepted in the repository is beyond the scope of this document; future ufs-weather-model code management may have detailed answer for that. - -Reviewers may suggest some code changes during the review process. Developers need to respond to these comments in order to get code changes committed. If developers make further changes to their branch, reviewers need to check the code changes again. When both reviewers give recommendation to commit the code, code managers will merge the changes into the repository. - ----------------------------- -Conducting regression tests ----------------------------- - -Only developers that are running on a limited set of platforms (Hera, Cheyenne, WCOSS) can compile and run regression tests using the ufs-weather-model. - -To run regression test using rt.sh - -rt.sh is a bash shell file to run the RT and has the following options: - -.. code-block:: console - - Usage: $0 -c | -f | -s | -l | -m | -r | -e | -h - -c create new baseline results for - -f run full suite of regression tests - -s run standard suite of regression tests - -l run test specified in - -m compare against new baseline results - -r use Rocoto workflow manager - -e use ecFlow workflow manager - -h display this help - -.. code-block:: console - - % cd ufs-weather-model/tests - % ./rt.sh -f - -Regression test log files (ufs-weather-model/tests/Compile_$(MACHINE_ID).log and ufs-weather-model/tests/RegressionTests_$(MACHINE_ID).log ) will be updated. - -To create new baseline: - -.. code-block:: console - - % cd ufs-weather-model/tests - % ./rt.sh -f -c - - * To run regression test using NEMSCompsetRun - -.. code-block:: console - - % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun -f - -Regression test log files (ufs-weather-model/log/$MACHINE_ID/* ) will be updated. - -To create new baseline: - -.. code-block:: console - - % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun--baseline fv3 --platform=${PLATFORM} - - -The value of ${PLATFORM} can be found in ufs-weather-model/compsets/platforms.input. - -Developers need to commit the regression test log files to their branch before making pull request. - -================================ - ufs-community/ufs-weather-model -================================ - ------------------------------- - Prerequisite libraries: ------------------------------- - -Below is the list of libraries that are required to compile the model and run regression tests: - -+-------------+---------------------------------------------------------------------+---------+----------------+ -| Library name| source |version | env variables | -+=============+=====================================================================+=========+================+ -| bacio |https://github.com/NOAA-EMC/NCEPLIBS-bacio | 2.0.3 | $BACIO_LIB4 | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| sp |https://github.com/NOAA-EMC/NCEPLIBS-sp | 2.0.3 | $SP_LIBd | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| w3nco |https://github.com/NOAA-EMC/NCEPLIBS-w3nco | 2.0.7 | $W3NCO_LIBd | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| w3emc |https://github.com/NOAA-EMC/NCEPLIBS-w3emc | 2.3.1 | $W3EMC_LIBd | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| nemsio |https://github.com/NOAA-EMC/NCEPLIBS-nemsio | 2.2.4 | $NEMSIO_INC | -+ + + + + -| | | | $NEMSIO_LIB | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| g2 |https://github.com/NOAA-EMC/NCEPLIBS-g2 |3.1.1 | $G2_LIB4 | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| g2tmpl |https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl(required for inline post)|1.5.1 | $G2TMPL_LIB | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| crtm |https://github.com/NOAA-EMC/EMC_crtm (required for inline post) |2.2.6 | $CRTM_LIB | -+-------------+---------------------------------------------------------------------+---------+----------------+ -| post | http://github.com/NOAA-EMC/EMC_post (required for inline post) | 8.0.0 | $POST_INC | -+ + + + + -| | | | $POST_LIB | -+-------------+---------------------------------------------------------------------+---------+----------------+ - -External libraries: - - -+-------------+--------------------------------------------------------------+---------+-------------------------+ -| Library name| source |version | env variables | -+=============+==============================================================+=========+=========================+ -| | | |$ESMFMKFILE, | -+ + + + + -| | | |$ESMF_F90COMPILEPATHS, | -+ + + + + -|esmf |https://www.earthsystemcog.org/projects/esmf/download_800 | 8.0.0 |$ESMF_F90ESMFLINKPATHS, | -+ + + + + -| | | |$(ESMF_F90ESMFLINKRPATHS)| -+ + + + + -| | | |$(ESMF_F90ESMFLINKLIBS) | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -| | | 4.5.0 | | -+ + + + + -| NetCDF |https://www.unidata.ucar.edu/downloads/netcdf/index.jsp | 4.6.1 |$NETCDF or($NETCDF_DIR) | -+ + + + + -| | | 4.6.3 | | -+ + + + + -| | | 4.7.0 | | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -| | | 1.8.14 | | -+ + + + + -|HDF5 | https://www.hdfgroup.org/downloads/hdf5/ | 1.8.16 | $HDF5 | -+ + + + + -| | | 1.10.1 | | -+ + + + + -| | | 1.10.4 | | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -|jasper | https://github.com/mdadams/jasper | 1.900.1 | $JASPER_LIB | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -|zlib | https://github.com/madler/zlib | 1.2.11 | $Z_LIB | -+-------------+--------------------------------------------------------------+---------+-------------------------+ -|libpng | http://www.libpng.org/pub/png/libpng.html | 1.2.44 | $PNG_LIB | -+-------------+--------------------------------------------------------------+---------+-------------------------+ - - -Compiler: - - -+--------------------+------------------------------------------------------------------+ -|Compiler name | Branch name | -+====================+==================================================================+ -| Intel | 16.0.3.210,16.3.210,18.0.1.163, 18.0.3.222,18.0.5.274, 19.0.2 | -+--------------------+------------------------------------------------------------------+ -|impi | 2018.0.4, 2018.4.274,18.0.1, 2019.2.187 | -+--------------------+------------------------------------------------------------------+ - - -These libraries are available on several platforms including Hera, Cheyenne and WCOSS. Installing these libraries on jet and gaea is a work in progress. - -In addition to these libraries, other software is required such as a compiler (Intel or GNU), MPI library (impi), HDF5, cmake, Python, Perl and Ruby to compile the model and run regression tests. - --------------------------------------------- -Making code changes using a forking workflow --------------------------------------------- - -If developers would like to make code changes, they need to make a personal fork, set up upstream remote (for merging with the original ufs-weather-model), and create a branch for ufs-weather-model and each of the subcomponent repositories they want to change. They can then make code changes, perform testing and commit the changes to the branch in their personal fork. It is suggested that they merge their branch with the develop branch of the original repositories periodically to get the latest updates and bug fixes. - -If developers would like to get their code committed back to the original repository, it is suggested to follow the steps below: - - # Create an issue in the authoritative repository. For example to commit code changes to fv3atm, please go to https://github.com/NOAA-EMC/fv3atm, under NOAA-EMC/fv3atm and find the “Issues” tab next to the “Code” tab. Click on “Issues” and a new page will appear. On the right side of the page, there is a green “New issue” button. Clicking on that will lead to a new issue page. Fill out the title, comments to describe the code changes, and also please provide personal fork and branch information. Lastly, click on the “Submit new issue” button, so that the new issue is created. - - # When the development is mature, tests have been conducted, and the developer is satisfied with the results, create a pull request to commit the code changes. - - * Merge developer’s branch to the latest ufs-weather-model develop branch in authoritative repository. If changes are made in model sub-components, developers need to merge their branches to branches with the corresponding authoritative repository (or original repository for some components). For this, code management practices of the subcomponents need to be followed. - - * Regression tests need to pass on at least one supported platform. - - * For each component branch where developers make changes, developers need to go to their personal fork on GitHub and click on the “New pull request” button. When a new page “Compare changes” appears, developers will choose the branch in their fork with code changes to commit and the branch in upstream repository that the changes will be committed to. The code differences between the two branches will be displayed. Developers can review the differences and click on “submit pull request” to make the pull request. After code changes are committed to the component repository, developers will make pull requests to ufs-weather-model repository. - -It is suggested that the developers inform all the related code managers as the hierarchy structure of the ufs-weather-model repository may require collaboration among the code managers. - ------------------------------------ -Engaging in the code review process ------------------------------------ - -When code managers receive a pull request to commit the code changes, it is recommended that they add at least two code reviewers to review the code. The reviewers will write comments about the code changes and give a recommendation as to whether the code changes can be committed. What kinds of code changes will be accepted in the repository is beyond the scope of this document; future ufs-weather-model code management may have detailed answer for that. - -Reviewers may suggest some code changes during the review process. Developers need to respond to these comments in order to get code changes committed. If developers make further changes to their branch, reviewers need to check the code changes again. When both reviewers give recommendation to commit the code, code managers will merge the changes into the repository. - ---------------------------- -Conducting regression tests ---------------------------- - -Only developers that are running on a limited set of platforms (Hera, Cheyenne, WCOSS) can compile and run regression tests using the ufs-weather-model. - -To run regression test using rt.sh - -.. code-block:: console - - % cd ufs-weather-model/tests - % ./rt.sh -f - -Regression test log files (ufs-weather-model/tests/Compile_$(MACHINE_ID).log and ufs-weather-model/tests/RegressionTests_$(MACHINE_ID).log ) will be updated. - -To create new baseline: - -.. code-block:: console - - % cd ufs-weather-model/tests - % ./rt.sh -f -c - - * To run regression test using NEMSCompsetRun - -.. code-block:: console - - % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun -f - -Regression test log files (ufs-weather-model/log/$MACHINE_ID/* ) will be updated. - -To create new baseline: - -.. code-block:: console - - % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun--baseline fv3 --platform=${PLATFORM} - - -The value of ${PLATFORM} can be found in ufs-weather-model/compsets/platforms.input. - -Developers need to commit the regression test log files to their branch before making pull request. - -------------------------------------- -Compiling the code and running a test -------------------------------------- - -Currently developers running on Hera, Cheyenne or WCOSS can compile and run tests using the ufs-weather-model. In the document below, ufs-weather-model directory points to a branch in the developer’s personal fork. - - * Compile and run a test using rt.sh - - i) compile the code - -Developers can compile the ufs-weather-model using the compile script ufs_weather_model/tests/compile.sh. To compile the code: - -.. code-block:: console - - % git clone --recursive https://github.com/ufs-community/ufs-weather-model - % cd ufs-weather-model/tests - % ./compile.sh PATHTR MACHINE_ID MAKE_OPT BUILD_NR - - -Where: - -.. code-block:: console - - PATHTR: the full path of FV3 directory under ufs-weather-model - MACHINE_ID: machine ID, e.g: wcoss_cray, hera.intel - MAKE_OPT: compile options, default (‘’, empty string) is for 64-bit OpenMP non-hydrostatic build using AVX2, other options are: - - ‘DEBUG=Y’: turn on debug option - - ‘VERBOSE=Y’: turn on VERBOSE mode to get additional details on compile - - ‘OPENMP=Y’: use openmp - - ‘AVX2=Y’: use AVX2 in Intel Haswell for better performance. - - ‘HYDRO=Y’: hydrostatic mode - - ‘CCPP=Y’: using ccpp framework and physics - - ‘STATIC=Y’: when CCPP=Y, using static build instead of dynamic build - - ‘SUITE=xxx': CCPP physics suite, e.g. “FV3_GFS_2017_gfdlmp” - BUILD_NR: the number of build (there might be several copies of the executable). The final executable would be fv3_${BUILD_NR}.exe - - -Example: - -.. code-block:: console - - % ./compile.sh /gpfs/hps/emc/global/noscrub/First.Last/ufs-weather-model/FV3 wcoss_cray '' 1 - -The executable generated from the compile.sh can be used in global workflow to run experiments. - - ii) run a regression test - -Developers can run a single regression test from the regression test suite. The full list of the regression tests can be found at: - -.. code-block:: console - - us-weather-model/tests/fv3_conf - -To run a specific regression test: - -.. code-block:: console - - %cd ufs_weather_model/tests - % cp rt.conf rt.conf1 - -Edit the rt.conf1 file, keep the test developers intended to run and remove all the rest tests. - -COMPILE | fv3 | standard| wcoss_cray | | -RUN | fv3_control | standard| | | - - -To compile and run the test, do - -.. code-block:: console - - % ./rt.sh -l rt.conf1 - -The code will be compiled and run on wcoss_cray. A log directory will be shown at: ufs-weather-model/tests /log_$MACHINE_ID. If there are compile errors, please check file: compile_${BUILD_NR}.log under above log directory. If the code is successfully compiled, but the job failed, please go to above log directory to look for rt_${test_number}_${test_id}.log for details. - - * Compile and run a test using NEMSCompsetRun - - i) Compile the code - -.. code-block:: console - - % cd ufs-weather-model - % ./NEMS/NEMSAppBuilder app=coupledFV3_WW3 - -ii) Run a regression test - -NEMSCompsetRun runs the same tests as rt.sh. The two share the same baseline results. To run a single test using NEMSCompsetRun: - -.. code-block:: console - - % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun “{test_name}” - -The test name can be found in compsets/all.input. - - - - - - - - - - - - - - - - - - - - - - - - From 46d14dd4811f41920535615fae0857a1c723b5e0 Mon Sep 17 00:00:00 2001 From: valbonakunkel-noaa <36248012+valbonakunkel-noaa@users.noreply.github.com> Date: Tue, 28 Jan 2020 13:58:32 -0500 Subject: [PATCH 07/11] Add files via upload --- .../source/ContributingDevelopment.rst | 204 ++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 doc/UsersGuide/source/ContributingDevelopment.rst diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst new file mode 100644 index 0000000000..2dcd1e4f9d --- /dev/null +++ b/doc/UsersGuide/source/ContributingDevelopment.rst @@ -0,0 +1,204 @@ +.. _ContributingDevelopment: + +************************* +Contributing Development +************************* + +The ufs-weather-model repository contains the model code and external links needed to build the Unified Forecast System (UFS) atmosphere model and associated components, including the WaveWatch III model. This weather model is used in several of the UFS applications, including the medium-range weather application, the short-range weather application, and the sub-seasonal to seasonal application. + +------------------------ + Prerequisite libraries: +------------------------ + +Below is the list of libraries that are required to compile the model and run regression tests: + ++-------------+---------------------------------------------------------------------+---------+----------------+ +| Library name| source |version | env variables | ++=============+=====================================================================+=========+================+ +| bacio |https://github.com/NOAA-EMC/NCEPLIBS-bacio | 2.0.3 | $BACIO_LIB4 | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| sp |https://github.com/NOAA-EMC/NCEPLIBS-sp | 2.0.3 | $SP_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| w3nco |https://github.com/NOAA-EMC/NCEPLIBS-w3nco | 2.0.7 | $W3NCO_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| w3emc |https://github.com/NOAA-EMC/NCEPLIBS-w3emc | 2.3.1 | $W3EMC_LIBd | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| nemsio |https://github.com/NOAA-EMC/NCEPLIBS-nemsio | 2.2.4 | $NEMSIO_INC | ++ + + + + +| | | | $NEMSIO_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| g2 |https://github.com/NOAA-EMC/NCEPLIBS-g2 |3.1.1 | $G2_LIB4 | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| g2tmpl |https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl(required for inline post)|1.5.1 | $G2TMPL_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| crtm |https://github.com/NOAA-EMC/EMC_crtm (required for inline post) |2.2.6 | $CRTM_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ +| post | http://github.com/NOAA-EMC/EMC_post (required for inline post) | 8.0.0 | $POST_INC | ++ + + + + +| | | | $POST_LIB | ++-------------+---------------------------------------------------------------------+---------+----------------+ + +External libraries: + + ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| Library name| source |version | env variables | ++=============+==============================================================+=========+=========================+ +| | | |$ESMFMKFILE, | ++ + + + + +| | | |$ESMF_F90COMPILEPATHS, | ++ + + + + +|esmf |https://www.earthsystemcog.org/projects/esmf/download_800 | 8.0.0 |$ESMF_F90ESMFLINKPATHS, | ++ + + + + +| | | |$(ESMF_F90ESMFLINKRPATHS)| ++ + + + + +| | | |$(ESMF_F90ESMFLINKLIBS) | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| | | 4.5.0 | | ++ + + + + +| NetCDF |https://www.unidata.ucar.edu/downloads/netcdf/index.jsp | 4.6.1 |$NETCDF or($NETCDF_DIR) | ++ + + + + +| | | 4.6.3 | | ++ + + + + +| | | 4.7.0 | | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +| | | 1.8.14 | | ++ + + + + +|HDF5 | https://www.hdfgroup.org/downloads/hdf5/ | 1.8.16 | $HDF5 | ++ + + + + +| | | 1.10.1 | | ++ + + + + +| | | 1.10.4 | | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|jasper | https://github.com/mdadams/jasper | 1.900.1 | $JASPER_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|zlib | https://github.com/madler/zlib | 1.2.11 | $Z_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ +|libpng | http://www.libpng.org/pub/png/libpng.html | 1.2.44 | $PNG_LIB | ++-------------+--------------------------------------------------------------+---------+-------------------------+ + + +Compiler: + + ++--------------------+------------------------------------------------------------------+ +|Compiler name | Branch name | ++====================+==================================================================+ +| Intel | 16.0.3.210,16.3.210,18.0.1.163, 18.0.3.222,18.0.5.274, 19.0.2 | ++--------------------+------------------------------------------------------------------+ +|impi | 2018.0.4, 2018.4.274,18.0.1, 2019.2.187 | ++--------------------+------------------------------------------------------------------+ + + +These libraries are available on several platforms including Hera, Cheyenne and WCOSS. Installing these libraries on jet and gaea is a work in progress. Users who need to build the libraries. [https://github.com/NOAA-EMC/NCEPLIBS/wiki/Cloning-and-Compiling-NCEPLIBS] + +In addition to these libraries, other software is required such as a compiler (Intel or GNU), MPI library (impi), HDF5, cmake, Python, Perl and Ruby to compile the model and run regression tests. + +--------------------------------------------- +Making code changes using a forking workflow +--------------------------------------------- + +If developers would like to make code changes, they need to make a personal fork, set up upstream remote (for merging with the original ufs-weather-model), and create a branch for ufs-weather-model and each of the subcomponent repositories they want to change. They can then make code changes, perform testing and commit the changes to the branch in their personal fork. It is suggested that they merge their branch with the develop branch of the original repositories periodically to get the latest updates and bug fixes. + +If developers would like to get their code committed back to the original repository, it is suggested to follow the steps below: + +1. Create an issue in the authoritative repository. For example to commit code changes to fv3atm, please go to https://github.com/NOAA-EMC/fv3atm, under NOAA-EMC/fv3atm and find the “Issues” tab next to the “Code” tab. Click on “Issues” and a new page will appear. On the right side of the page, there is a green “New issue” button. Clicking on that will lead to a new issue page. Fill out the title, comments to describe the code changes, and also please provide personal fork and branch information. Lastly, click on the “Submit new issue” button, so that the new issue is created. + +2. When the development is mature, tests have been conducted, and the developer is satisfied with the results, create a pull request to commit the code changes. + + * Merge developer’s branch to the latest ufs-weather-model develop branch in authoritative repository. If changes are made in model sub-components, developers need to merge their branches to branches with the corresponding authoritative repository (or original repository for some components). For this, code management practices of the subcomponents need to be followed. + + * Regression tests associated with the ufs-weather-model are available in Tier 1 and Tier 2 platforms as described in https://github.com/ufs-community/ufs-weather-model/wiki/Weather-Model-Platform-and-Compiler-Support. If the developer has access to these platforms, the developer should pass the regression test on at least one supported platform. If the developer does not have access to these platforms, this should be stated in the PR so the code manager(s) can conduct the tests. + + * For each component branch where developers make changes, developers need to go to their personal fork on GitHub and click on the “New pull request” button. When a new page “Compare changes” appears, developers will choose the branch in their fork with code changes to commit and the branch in upstream repository that the changes will be committed to. Also developers in the commit comment must add the github issue title and number created in 1) in the comment box. The code differences between the two branches will be displayed. Developers can review the differences and click on “submit pull request” to make the pull request. After code changes are committed to the component repository, developers will make pull requests to ufs-weather-model repository. + +3. When PRs are created, the creator must temporarily modify .gitmodules to point to his/her fork and branch if updates are required for submodules. + +4. Merging code from PRs with submodules requires coordination with the person making the PRs. From the "innermost" nested PR up to the top-level PR, the PRs need to be merged as-is. After each merge, the person creating the PRs has to update his/her local code to check out the merged version, revert the change to .gitmodules, and push this to GitHub to update the PR. And so on and so forth. + +5. Checking out the code ufs_release_1.0 should always be as follows: + +.. code-block:: console + + git clone https://github.com/ufs-community/ufs-weather-model + cd ufs-weather-model + git checkout ufs_release_1.00 + git submodule update --init --recursive + +6. Checking out a PR with id ID for testing it should always be as follows: + +.. code-block:: console + + git clone https://github.com/ufs-community/ufs-weather-model + cd ufs-weather-model + git fetch origin pull/ID/head:BRANCHNAME + git checkout BRANCHNAME + git submodule update --init --recursive + +It is suggested that the developers inform all the related code managers as the hierarchy structure of the ufs-weather-model repository may require collaboration among the code managers. + +----------------------------------- +Engaging in the code review process +----------------------------------- + +When code managers receive a pull request to commit the code changes, it is recommended that they add at least two code reviewers to review the code and at least one of the reviewers has write permission. The reviewers will write comments about the code changes and give a recommendation as to whether the code changes can be committed. What kinds of code changes will be accepted in the repository is beyond the scope of this document; future ufs-weather-model code management may have detailed answer for that. + +Reviewers may suggest some code changes during the review process. Developers need to respond to these comments in order to get code changes committed. If developers make further changes to their branch, reviewers need to check the code changes again. When both reviewers give recommendation to commit the code, code managers will merge the changes into the repository. + +---------------------------- +Conducting regression tests +---------------------------- + +Only developers that are running on a limited set of platforms (Hera, Cheyenne, WCOSS) can compile and run regression tests using the ufs-weather-model. + +To run regression test using rt.sh + +rt.sh is a bash shell file to run the RT and has the following options: + +.. code-block:: console + + Usage: $0 -c | -f | -s | -l | -m | -r | -e | -h + -c create new baseline results for + -f run full suite of regression tests + -s run standard suite of regression tests + -l run test specified in + -m compare against new baseline results + -r use Rocoto workflow manager + -e use ecFlow workflow manager + -h display this help + +.. code-block:: console + + % cd ufs-weather-model/tests + % ./rt.sh -f + +Regression test log files (ufs-weather-model/tests/Compile_$(MACHINE_ID).log and ufs-weather-model/tests/RegressionTests_$(MACHINE_ID).log ) will be updated. + +To create new baseline: + +.. code-block:: console + + % cd ufs-weather-model/tests + % ./rt.sh -f -c + + * To run regression test using NEMSCompsetRun + +.. code-block:: console + + % cd ufs-weather-model + % ./NEMS/NEMSCompsetRun -f + +Regression test log files (ufs-weather-model/log/$MACHINE_ID/* ) will be updated. + +To create new baseline: + +.. code-block:: console + + % cd ufs-weather-model + % ./NEMS/NEMSCompsetRun--baseline fv3 --platform=${PLATFORM} + + +The value of ${PLATFORM} can be found in ufs-weather-model/compsets/platforms.input. + +Developers need to commit the regression test log files to their branch before making pull request. + From a144a2f3216893103c62882300097cfdc6498c73 Mon Sep 17 00:00:00 2001 From: valbonakunkel-noaa <36248012+valbonakunkel-noaa@users.noreply.github.com> Date: Wed, 29 Jan 2020 14:35:47 -0500 Subject: [PATCH 08/11] Update ContributingDevelopment.rst --- .../source/ContributingDevelopment.rst | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst index 2dcd1e4f9d..b6a54f1254 100644 --- a/doc/UsersGuide/source/ContributingDevelopment.rst +++ b/doc/UsersGuide/source/ContributingDevelopment.rst @@ -90,7 +90,7 @@ Compiler: +--------------------+------------------------------------------------------------------+ -These libraries are available on several platforms including Hera, Cheyenne and WCOSS. Installing these libraries on jet and gaea is a work in progress. Users who need to build the libraries. [https://github.com/NOAA-EMC/NCEPLIBS/wiki/Cloning-and-Compiling-NCEPLIBS] +These libraries are available on several platforms including Hera, Cheyenne and WCOSS. Installing these libraries on jet and gaea is a work in progress. Information how to build the libraries can be found at [https://github.com/NOAA-EMC/NCEPLIBS/wiki/Cloning-and-Compiling-NCEPLIBS] In addition to these libraries, other software is required such as a compiler (Intel or GNU), MPI library (impi), HDF5, cmake, Python, Perl and Ruby to compile the model and run regression tests. @@ -98,7 +98,7 @@ In addition to these libraries, other software is required such as a compiler (I Making code changes using a forking workflow --------------------------------------------- -If developers would like to make code changes, they need to make a personal fork, set up upstream remote (for merging with the original ufs-weather-model), and create a branch for ufs-weather-model and each of the subcomponent repositories they want to change. They can then make code changes, perform testing and commit the changes to the branch in their personal fork. It is suggested that they merge their branch with the develop branch of the original repositories periodically to get the latest updates and bug fixes. +If developers would like to make code changes, they need to make a personal fork, set up upstream remote (for merging with the original ufs-weather-model), and create a branch for ufs-weather-model and each of the subcomponent repositories they want to change. They can then make code changes, perform testing and commit the changes to the branch in their personal fork. It is suggested that they update their branch by merging the develop branch with the develop branch of the original repositories periodically to get the latest updates and bug fixes. If developers would like to get their code committed back to the original repository, it is suggested to follow the steps below: @@ -141,7 +141,7 @@ It is suggested that the developers inform all the related code managers as the Engaging in the code review process ----------------------------------- -When code managers receive a pull request to commit the code changes, it is recommended that they add at least two code reviewers to review the code and at least one of the reviewers has write permission. The reviewers will write comments about the code changes and give a recommendation as to whether the code changes can be committed. What kinds of code changes will be accepted in the repository is beyond the scope of this document; future ufs-weather-model code management may have detailed answer for that. +When code managers receive a pull request to commit the code changes, it is recommended that they add at least two code reviewers to review the code and at least one of the reviewers has write permission. The reviewers will write comments about the code changes and give a recommendation as to whether the code changes can be committed. What kinds of code changes will be accepted in the repository is beyond the scope of this document; future ufs-weather-model code management documents may have a detailed answer for that. Reviewers may suggest some code changes during the review process. Developers need to respond to these comments in order to get code changes committed. If developers make further changes to their branch, reviewers need to check the code changes again. When both reviewers give recommendation to commit the code, code managers will merge the changes into the repository. @@ -149,7 +149,8 @@ Reviewers may suggest some code changes during the review process. Developers ne Conducting regression tests ---------------------------- -Only developers that are running on a limited set of platforms (Hera, Cheyenne, WCOSS) can compile and run regression tests using the ufs-weather-model. +Only developers using Tier 1 and 2 platforms can run the ufs-weather-model regression tests. Other developers need to work with the code managers to assure completion of the regression tests. + To run regression test using rt.sh @@ -172,8 +173,21 @@ rt.sh is a bash shell file to run the RT and has the following options: % cd ufs-weather-model/tests % ./rt.sh -f +This command can only be used on a NOAA machine using the Intel compiler, where an official baseline is available. For information on testing the CCPP code, or using alternate computational platforms, see the following sections. + +This command and all others below produce log output in ./tests/log_machine.compiler. These log files contain information on the location of the run directories that can be used as templates for the user. Each rt*.conf contains one or more compile commands preceding a number of tests. + Regression test log files (ufs-weather-model/tests/Compile_$(MACHINE_ID).log and ufs-weather-model/tests/RegressionTests_$(MACHINE_ID).log ) will be updated. +Regression testing is only possible on machines for which baselines exist, that is Tier 1 and 2 platforms. + +When porting the code to a new machine, it is useful to start by establishing a personal baseline. Future runs of the RT can then be compared against the personal baseline to ascertain that the results have not been inadvertently affected by code developments. The rt.sh -c option is used to create a personal baseline. + +./rt.sh -l rt.conf -c fv3 # create own reg. test baseline +Once the personal baseline has been created, future runs of the RT should be compared against the personal baseline using the -m option. + +./rt.sh -l rt.conf -m # compare against own baseline + To create new baseline: .. code-block:: console From 196ffea540777696ed1ce004eb6e4f89799b9912 Mon Sep 17 00:00:00 2001 From: Dom Heinzeller Date: Thu, 30 Jan 2020 12:52:05 -0700 Subject: [PATCH 09/11] doc/UsersGuide/source/ContributingDevelopment.rst: fixing the biggest errors only --- .../source/ContributingDevelopment.rst | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst index a8a6553a46..122a262bef 100644 --- a/doc/UsersGuide/source/ContributingDevelopment.rst +++ b/doc/UsersGuide/source/ContributingDevelopment.rst @@ -112,7 +112,7 @@ If developers would like to get their code committed back to the original reposi * Merge developer’s branch to the latest ufs-weather-model develop branch in authoritative repository. If changes are made in model sub-components, developers need to merge their branches to branches with the corresponding authoritative repository (or original repository for some components). For this, code management practices of the subcomponents need to be followed. - * Regression tests associated with the ufs-weather-model are available in Tier 1 and Tier 2 platforms as described in https://github.com/ufs-community/ufs-weather-model/wiki/Weather-Model-Platform-and-Compiler-Support. If the developer has access to these platforms, the developer should pass the regression test on at least one supported platform. If the developer does not have access to these platforms, this should be stated in the PR so the code manager(s) can conduct the tests. + * Regression tests associated with the ufs-weather-model are available on Tier 1 and Tier 2 platforms as described in https://github.com/ufs-community/ufs-weather-model/wiki/Weather-Model-Platform-and-Compiler-Support. If the developer has access to these platforms, the developer should pass the regression test on at least one supported platform. If the developer does not have access to these platforms, this should be stated in the PR so the code manager(s) can conduct the tests. * For each component branch where developers make changes, developers need to go to their personal fork on GitHub and click on the “New pull request” button. When a new page “Compare changes” appears, developers will choose the branch in their fork with code changes to commit and the branch in upstream repository that the changes will be committed to. Also developers in the commit comment must add the github issue title and number created in 1) in the comment box. The code differences between the two branches will be displayed. Developers can review the differences and click on “submit pull request” to make the pull request. After code changes are committed to the component repository, developers will make pull requests to ufs-weather-model repository. @@ -155,7 +155,6 @@ Conducting regression tests Only developers using Tier 1 and 2 platforms can run the ufs-weather-model regression tests. Other developers need to work with the code managers to assure completion of the regression tests. - To run regression test using rt.sh rt.sh is a bash shell file to run the RT and has the following options: @@ -177,17 +176,16 @@ rt.sh is a bash shell file to run the RT and has the following options: % cd ufs-weather-model/tests % ./rt.sh -f -This command can only be used on a NOAA machine using the Intel compiler, where an official baseline is available. For information on testing the CCPP code, or using alternate computational platforms, see the following sections. +This command can only be used on platforms that have been configured for regression testing (Tier 1 and Tier 2 platforms as described in https://github.com/ufs-community/ufs-weather-model/wiki/Weather-Model-Platform-and-Compiler-Support). For information on testing the CCPP code, or using alternate computational platforms, see the following sections. This command and all others below produce log output in ./tests/log_machine.compiler. These log files contain information on the location of the run directories that can be used as templates for the user. Each rt*.conf contains one or more compile commands preceding a number of tests. Regression test log files (ufs-weather-model/tests/Compile_$(MACHINE_ID).log and ufs-weather-model/tests/RegressionTests_$(MACHINE_ID).log ) will be updated. -Regression testing is only possible on machines for which baselines exist, that is Tier 1 and 2 platforms. +If developers wish to contribute code that changes the results of the regression tests (because of updates to the physics, for example), it is useful to run rt.sh as described above to make sure that the test failures are as expected. It is then useful to establish a new personal baseline: -When porting the code to a new machine, it is useful to start by establishing a personal baseline. Future runs of the RT can then be compared against the personal baseline to ascertain that the results have not been inadvertently affected by code developments. The rt.sh -c option is used to create a personal baseline. +./rt.sh -l rt.conf -c # create own reg. test baseline -./rt.sh -l rt.conf -c fv3 # create own reg. test baseline Once the personal baseline has been created, future runs of the RT should be compared against the personal baseline using the -m option. ./rt.sh -l rt.conf -m # compare against own baseline @@ -199,12 +197,12 @@ To create new baseline: % cd ufs-weather-model/tests % ./rt.sh -f -c - * To run regression test using NEMSCompsetRun +An alternative/complementary regression test system is using NEMSCompsetRun, which focuses more on coupled model configurations than testing features of the standalone ufs-weather-model. To run regression test using NEMSCompsetRun: .. code-block:: console % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun -f + % ./NEMS/NEMSCompsetRun -f Regression test log files (ufs-weather-model/log/$MACHINE_ID/* ) will be updated. @@ -213,8 +211,7 @@ To create new baseline: .. code-block:: console % cd ufs-weather-model - % ./NEMS/NEMSCompsetRun--baseline fv3 --platform=${PLATFORM} - + % ./NEMS/NEMSCompsetRun --baseline fv3 --platform=${PLATFORM} The value of ${PLATFORM} can be found in ufs-weather-model/compsets/platforms.input. From 22765ab99718acfa41248da1a8e8e0e9f7f961d1 Mon Sep 17 00:00:00 2001 From: Dom Heinzeller Date: Thu, 30 Jan 2020 12:53:54 -0700 Subject: [PATCH 10/11] Fix more errors, update usage in rt.sh --- doc/UsersGuide/source/ContributingDevelopment.rst | 2 +- tests/rt.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst index 122a262bef..3edc235192 100644 --- a/doc/UsersGuide/source/ContributingDevelopment.rst +++ b/doc/UsersGuide/source/ContributingDevelopment.rst @@ -161,7 +161,7 @@ rt.sh is a bash shell file to run the RT and has the following options: .. code-block:: console - Usage: $0 -c | -f | -s | -l | -m | -r | -e | -h + Usage: ./rt.sh -c | -f | -s | -l | -m | -r | -e | -h -c create new baseline results for -f run full suite of regression tests -s run standard suite of regression tests diff --git a/tests/rt.sh b/tests/rt.sh index 1c99394dd7..2655f015ac 100755 --- a/tests/rt.sh +++ b/tests/rt.sh @@ -7,7 +7,7 @@ die() { echo "$@" >&2; exit 1; } usage() { set +x echo - echo "Usage: $0 -c | -f | -s | -l | -m | -k | -r | -e | -h" + echo "Usage: $0 -c | -f | -s | -l | -m | -k | -r | -e | -h" echo echo " -c create new baseline results for " echo " -f run full suite of regression tests" From 01d4ad98c0536c698ffd1cf243a9c1642c407fda Mon Sep 17 00:00:00 2001 From: Dom Heinzeller Date: Thu, 30 Jan 2020 13:06:45 -0700 Subject: [PATCH 11/11] Document -k in rt.sh, remove another comment --- doc/UsersGuide/source/ContributingDevelopment.rst | 3 ++- tests/rt.sh | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/UsersGuide/source/ContributingDevelopment.rst b/doc/UsersGuide/source/ContributingDevelopment.rst index 3edc235192..3dfb26fa56 100644 --- a/doc/UsersGuide/source/ContributingDevelopment.rst +++ b/doc/UsersGuide/source/ContributingDevelopment.rst @@ -161,12 +161,13 @@ rt.sh is a bash shell file to run the RT and has the following options: .. code-block:: console - Usage: ./rt.sh -c | -f | -s | -l | -m | -r | -e | -h + Usage: ./rt.sh -c | -f | -s | -l | -m | -k | -r | -e | -h -c create new baseline results for -f run full suite of regression tests -s run standard suite of regression tests -l run test specified in -m compare against new baseline results + -k keep run directory (automatically deleted otherwise if all tests pass) -r use Rocoto workflow manager -e use ecFlow workflow manager -h display this help diff --git a/tests/rt.sh b/tests/rt.sh index 2655f015ac..984a756b85 100755 --- a/tests/rt.sh +++ b/tests/rt.sh @@ -9,7 +9,7 @@ usage() { echo echo "Usage: $0 -c | -f | -s | -l | -m | -k | -r | -e | -h" echo - echo " -c create new baseline results for " + echo " -c create new baseline results" echo " -f run full suite of regression tests" echo " -s run standard suite of regression tests" echo " -l runs test specified in "