NEMS DOCUMENTATION
How To Use NEMSLegacy

The Big Merge of April 2016
In April, 2016 there was a "big merge" that took about a year of development on the NUOPC/development branch to the NEMS trunk. This was a step toward unification of the NEMS applications at EMC. It had an impact on the way that codes at EMC are obtained and run.

The following was done during the merge:

In order to work on GSM or NMMB with the NEMS system after the merge in the way that you did before, you will not check out NEMS directly. Instead check out the NEMSLegacy application. The head of the NEMSLegacy trunk will bring in the head of the NEMS trunk, and fixed revisions of GSM and NMMB.

In short, you now do this to check out:

svn co https://svnemc.ncep.noaa.gov/projects/nems/apps/NEMSLegacy/trunk
NEMSLegacy

This will create a NEMSLegacy directory where you will find NEMS as a subdirectory.

There are more details below on how to accomplish specific tasks:

Making changes in NEMS/GSM:

  1. Create a nems ticket and a gsm ticket; document all the changes along with your work

  2. Create a NEMSlegacy branch

    %svn copy https://svnemc.ncep.noaa.gov/projects/nems/apps/NEMSLegacy/trunk

    https://svnemc.ncep.noaa.gov/projects/nems/apps/NEMSLegacy/branches/your_nemslegacy_branch -m"your message"

  3. Create a nems branch

    %svn copy https://svnemc.ncep.noaa.gov/projects/nems/trunk

    https://svnemc.ncep.noaa.gov/projects/nems/branches/your_nems_branch -m"your message"

  4. Create a gsm branch

    %svn copy https://svnemc.ncep.noaa.gov/projects/gsm/trunk https://svnemc.ncep.noaa.gov/projects/gsm/branches/your_gsm_branch -m"your_message"

  5. Make changes to a working copy of your NEMSLegacy/nems/gsm branches

    a) get a NEMSlegacy working copy from your branch:

    %svn co https://svnemc.ncep.noaa.gov/projects/nems/apps/NEMSLegacy/branches/your_nemslegacy_branch

    You will see a directory named your_nemslegacy_branch under your local directory

    b) change svn external links to your branches

    %cd your_nemslegacy_branch

    %svn propedit svn:externals .(dot)

    Change the trunks (along with the revision number) to your nems/gsm branches:

    NEMS         https://svnemc.ncep.noaa.gov/projects/nems/trunk

    NEMS/src/atmos/gsm-rRevision_number https://svnemc.ncep.noaa.gov/projects/gsm/trunk

    NEMS/src/atmos/nmm-rRevision_number https://svnemc.ncep.noaa.gov/projects/nmmb/trunk

    Change to:

    NEMS         https://svnemc.ncep.noaa.gov/projects/nems/branches/your_nems_branch

    NEMS/src/atmos/gsm https://svnemc.ncep.noaa.gov/projects/gsm/branches/your_gsm_branch

    NEMS/src/atmos/nmm https://svnemc.ncep.noaa.gov/projects/nmmb/trunk

    Save the file, then do

    %svn update

    Now the working copy has your nems/gsm branches. You can start to make changes.

  6. Compile and run jobs using regression test script:

    The easiest way to compile and run a test is through nems/gsm regression test. Currently there are 9 tests for gsm including Eulerian dycore, WAM, GSM semi-Lagrangian (SLG), and ngac. You can find general setting for all gsm regression tests at:

    Your_nemslegacy_branch/your_nems_branch/tests/gsm_config

    Detailed setting information for each test is at the files under your_nems_branch/tests/tests. For example, your_nems_branch/tests/tests/gfs_slg contains the setting for gsm SLG T62 regression test.

    Here is how to run a single regression test, you may use this example to test your code:

    %cd your_nemslegacy_branch/your_nems_branch/tests

    %cp rt.conf rt.conf1

    Edit the rt.conf1 file, keep the tests you want to run and remove the rest. Below is an example file rt.conf1 to run gsm SLG at T62 on wcoss:

    COMPILE     | gsm         | standard   | wcoss   | gsm_intel         |

    RUN             | gfs_slg     | standard   |              | gfs                   |

    To compile and run the test, do:

    % ./rt.sh -l rt.conf1

    If there are compiling errors, please check file: Compile_wcoss.log on wcoss and Compile_theia.log on theia under your_nems_branch/tests. If the code is successfully compiled, but the job failed, please go to the run directory (on phase1: /ptmpp1/$USER/rt_$jobid, on phase2: /ptmpp2//$USER/rt_$jobid, on theia: /scratch4/NCEPDEV/stmp3/$USER/rt_$jobid). On wcoss look for fcst.$CDATE.out.$job_id for the run output prints; on theia: files out and err in the run directory have all the run output prints.

    Currently the GSM SLG regression test history files (sigf and fllxf) are in nemsio grib format. You can use grib2ctl.pl to create the GrADS control file, to create index file, please use:

    Gribmap -s12800000 -i your_grads_ctl.ctl

    The -s option is to skip nemsio header. The sfc history files ares in nemsio binary format, to generate grads ctl file:

    /global/save/emc.glopara/bin/mkgfsnemsioctl your_sfcfile

    You will see a Grads control file: your_sfcfile.ctl.

    To see the impact of your changes on the forecast, you can compare the forecasts made from your branch and those from baseline (results created from trunk). On wcoss, the baseline results are at:

    /meso/noscrub/Ratko.Vasic/REGRESSION_TEST

    On Theia:

    /scratch4/NCEPDEV/meso/noscrub/Ratko.Vasic/REGRESSION_TEST

  7. Run regression tests on wcoss and theia

    If the tests run well and you would like to commit your code changes into trunk, please finish following steps:

    a) commit all the changes to your gsm branch and nems branch.

    b) update your branch with the latest nems/gsm trunk change through svn merge. For example, to merge changes from gsm trunk:

    i) dry run merge to show all the possible conflicts:

    %cd your_nemslegacy_branch/your_nems_branch/src/atmos/gsm

    %svn merge -dry-run https://svnemc.ncep.noaa.gov/projects/gsm/trunk

    ii) merge changes from gsm trunk

    %svn merge https://svnemc.ncep.noaa.gov/projects/gsm/trunk

    Please resolve all the conflicts shown up.

    c) run regression test on both wcoss and theia (we usually do a full regression test before the commit)

    %cd your_nemslegacy_branch/your_nems_branch/tests

    %./rt.sh -f

    You can run as a background job:

    on wcoss: nohup ./rt.sh -f >xx 2>&1 &

    on theia: nohup ./rt.sh -f > & xx &

    When regression test is done, please review RegressionTests_wcoss.log on wcoss and RegressionTests_theia.log on theia, and fix all the failed tests if any. All regression tests should be passed before you commit the changes to trunk.

  8. Commit changes to trunk

    Please follow the steps below to commit your changes:

    a) Committing to gsm trunk

    finish documenting all the changes in your gsm ticket, and reassign your ticket to someone to review, make changes if the reviewer suggests any. If the reviewer recommends the changes to be committed, reassign the ticket to gsm code manager (jun.w.nosp@m.ang@.nosp@m.noaa..nosp@m.gov) for gsm trunk commit. A new revision number will be available once the code is committed.

    b) Committing to nems trunk

    finish documenting all NEMS changes in NEMS ticket, now you yourself will commit to nems trunk.

    i)         Send out an "intent to commit" email to NEMS announcement group at: ncep..nosp@m.list.nosp@m..nems.nosp@m..ann.nosp@m.ounce.nosp@m.@lst.nosp@m.srv.n.nosp@m.cep..nosp@m.noaa..nosp@m.gov. If you are not in the email list, please send email to nicol.nosp@m.e.mc.nosp@m.kee@n.nosp@m.oaa..nosp@m.gov or mark..nosp@m.ired.nosp@m.ell@n.nosp@m.oaa..nosp@m.gov. Current policy is to wait for 24 hours after you send the announcement to give people time reviewing your changes. If you receive any feedbacks from nems developers, please resolve all the issues before you commit to nems trunk. For details, please read the "code development Guidelines" section at https://svnemc.ncep.noaa.gov/trac/nems

    ii)         To commit your branch to nems trunk:

    1)check out a working copy of nems trunk

    %svn co https://svnemc.ncep.noaa.gov/projects/nems/trunk

    %cd trunk

    You can run a dry run merge first to view the list of files that are going to be changed, then do actual merge. Resolve all the conflicts

    %svn merge –dry-run –reintegrate https://svnemc.ncep.noaa.gov/projects/nems/branches/your_nems_branch

    %svn merge –reintegrate https://svnemc.ncep.noaa.gov/projects/nems/branches/your_nems_branch

    2) Then commit to nems trunk

    %svn ci -m"your message for commit" or

    %svn ci -F log_file (log file has your message for commit)

    c) Committing to NEMSLegacy trunk

    Update NEMSLegacy to point to the head of nems/gsm trunks

    i)         Check out an NEMSLegacy trunk working copy:

    %svn co https://svnemc.ncep.noaa.gov/projects/nems/apps/NEMSLegacy/trunk

    %cd trunk

    %svn propedit svn:externas .(dot)

    ii)         Change following links to gsm/nems head of trunk with revision number:

    NEMS         https://svnemc.ncep.noaa.gov/projects/nems/trunk

    NEMS/src/atmos/gsm -rGSM_trunk_revision_number_from_7a)         https://svnemc.ncep.noaa.gov/projects/gsm/trunk

    NEMS/src/atmos/nmm     -rRevision_number https://svnemc.ncep.noaa.gov/projects/nmmb/trunk

    iii)         Commit the changes from your NEMSLegacy trunk working copy:

    %cd trunk

    %svn ci -m"your message for commit" or

    %svn ci -F log_file (log file has your message for commit)

    If you have questions on this section of the documentation, please contact: Jun.W.nosp@m.ang@.nosp@m.noaa..nosp@m.gov

NOTE on where to set externals

Please do not set svn:externals under the NEMS trunk. The GSM and NMM externals are now handled via the NEMSLegacy app, and not in the NEMS trunk. The proper way to checkout NEMS is via the NEMSLegacy app.

Examples:

To check out the current NEMS version:
svn co https://svnemc.ncep.noaa.gov/projects/nems/apps/NEMSLegacy/trunk     NEMSLegacy

To update the the GSM or NMM versions after a commit or for testing of different revisions:

svn co –ignore-externals https://svnemc.ncep.noaa.gov/projects/nems/apps/NEMSLegacy/trunk     NEMSLegacy

cd NEMSLegacy

svn propedit svn:externals .

NEMS         https://svnemc.ncep.noaa.gov/projects/nems/trunk
NEMS/src/atmos/gsm     -r 77262 https://svnemc.ncep.noaa.gov/projects/gsm/trunk
NEMS/src/atmos/nmm     -r 74333 https://svnemc.ncep.noaa.gov/projects/nmmb/trunk

(save and exit)

svn commit -m "NEMSLegacy app: Updating NMM and GSM externals"

Then if you want to download the revisions pointed to after updating the externals ;
svn update

NOTE on committing local changes

Don't commit your local changes to the NEMSLegacyexternals if you are testing an earlier revision or your own branch.

To update the the GSM or NMM versions after committing a NEMS, GSM, or NMM revision that has been thoroughly tested:
Change the svn:externals property and then:
svn commit -m "NEMSLegacy app: Updating NMM and GSM externals"

If you are only fetching a previous revision or a branch revision in your changes to svn:externals:
Change the svn:externals property and then:
svn update