3.12 Upgrading to the latest version of MOM

MOM 2 version 1.0 included a script ``run_upgrade_sgi'' for incorporating local changes into newer versions of MOM 2. This approach has since been discarded in favor of a much better one: reliance on the directory structure in MOM and a new utility ... the graphical difference analyzer ``gdiff'' which exists on Silicon Graphics workstations and makes easy, painless work out of what was once a difficult, time consuming, and complicated task. Even better is ``xdiff'' which is an X windows based graphical difference analyzer. If similar tools are not available, an alternative method outlined below will still work reasonable well, only not as easily as using ``gdiff'' of ``xdiff''. These utilities have become indispensable for development work at GFDL.

Standard operating practice

First and foremost, as a matter of operating practice, NEVER change a routine within the parent MOM_3 directory. Copy the routine first into an UPDATES sub-directory and make changes there. A different UPDATES sub-directory should be maintained for each experiment. Variants of routines within each UPDATES sub-directory can be kept in further sub-directories; with each sub-directory inheriting routines to be changed from its parent directory and adding local modifications; for example,

• PACIFIC/MOM_UPDATES/HLFX
• PACIFIC/MOM_UPDATES/HLFX/TEST1

In this way, a hierarchy of changes can be built. If this hierarchy is carefully designed, selecting sub-directories to copy in decending order down the branches of the hierarchy will allow any combination of updates to be applied. This can convieniently be done within the run script. Look at script run_mom to see how all routines are first copied from the parent directory MOM_3 into a temporary working directory followed by all routines from MOM_3/EXP/TEST_CASE/MOM_UPDATES. If there were a sub-directory hanging off of MOM_UPDATES, all routines from this last sub-directory would be copied next and so forth. After routines from all sub-directories have been copied, the desired model will have been built in the working directory.

Before starting to upgrade to a newer version of MOM, move the whole existing MOM_3 directory structure to MOM_3_OLD using

 mv  MOM_3  MOM_3_OLD

Then install the newer MOM_3 directory by uncompressing and extracting the tar file after retrieving it from the GFDL anonymous ftp. Now, for illustrative purposes, assume all local updates are kept in

 MOM_3_OLD/EXP/BOX/MOM_UPDATES

This sub-directory will be referred to as OLD_UPDATES. It is important to realize that although many of the routines in the newer version of MOM may have changed, only routines in OLD_UPDATES will have to be examined. Make a similar sub-directory within the new MOM_3 directory using

 mkdir  MOM_3/EXP/BOX/MOM_UPDATES

Let this new sub-directory be referred to as NEW_UPDATES. Note the list of files in OLD_UPDATES. Copy the corresponding files from the new MOM_3 directory into NEW_UPDATES. If additional personal files have been added to OLD_UPDATES, then copy them as well into NEW_UPDATES.