[Science]   [BAS home]   [Met home]   [Beowulf home]	Antarctic Meteorology

Writing modsets

Corrections or comments are particularly welcome.

The UM code is supposed to be modified by using modsets, which are applied during the compilation process. However, if you don't like doing it this way, or you're just testing out something quickly, you can instead:

Edit the code directly

1. Compile the job as usual. The compiled source (and objects) will be saved in a tar file.
2. Go to "the appropriate directory" (probably DATAW, on our ssytem that would be ~user/PUM_Output/vn4.5/dataw.jobid)
3. Go to the compile directory (Compile, or jobid.compile, or whatever)
4. This directory will be empty, if things have gone well
5. Untar the compiled sources:

   	gunzip -c ../*.gz|tar xf -
   

6. Now you have all the sources (.f), and all the compiled objects (.o), and the makefiles.
7. Edit the code you want.
8. Re-make the exec:

   	make -f makefile.compile
   	make -f makefile.link
   

9. And now you're ready to run.
10. Caution: if the .f file you've edited is from the pre-compiled sections, then
    1. It will be write-only, because its a link
    2. You can write your changes, but they won't write over the "original" (if your system is sane), which is what you want
    3. Because they are pre-compiled, they *won't be in the makefile*, and so will get built with the system default compiler, which is probably *not* what you want
    4. So in that case, you need to explicitly compile them, using whatever options are in the makefile.compile

Using modsets

See http://www.cgam.nerc.ac.uk/um/useful/nupdate_doc.txt for Lois's guide to nupdate.

Here is an example of a simple mod.

And here it is written out:

*IDENT SETFILwmc
*DECLARE SETFIL1A
*D GPB3F403.115,GPB3F403.121
C WMC. Include prints of area filtered: very useful info!
C      If all is well, results should be 25-33% ish.
      WRITE(6,*) 'SETFIL : Updating filtering area to ',    
     &           '2 - > ',NORTHERN_FILTERED_P_ROW,' and ',    
     &           SOUTHERN_FILTERED_P_ROW,' -> ',glsize(2)-1        
      WRITE(6,*) 'SETFIL: Filtering ',                              
     &  REAL((glsize(2)-2)-                                           
     &  (SOUTHERN_FILTERED_P_ROW-NORTHERN_FILTERED_P_ROW-1))/          
     &  REAL(glsize(2)-2),' frac of grid (not counting polar rows)'       

So...

1. *SOMETHING is a directive
2. The *IDENT line identifies it. This may or may not be necessary, but its useful.
3. *DECLARE tells you the code deck (in this case SETFIL1A.dk) that we are changing
4. *D GPB3F403.115,GPB3F403.121 deletes lines in the range specified, and replaces then with whatever follows, until the next directive (you can abbreviate directives. *D is short for *DELETE).
5. If you just want to insert code, use *I (*INSERT) line-number. This inserts *after* the line number specified (unlike *B, which... well you guess).
6. Not used here, but useful, is */, which is a comment. Of course, thats an *nupdate* comment: Fortran comments, ie lines beginning "C", go into the code as ever

So, how do you work out where to put your mod? Well, assuming you know what deck, and what code, you look in ~gcm/um/vn4.5/source/umpl/SETFIL1A.dk (or whatever your path to the source is) and you find:

!      WRITE(6,*) 'SETFIL : Updating filtering area to ',                  GPB3F403.115
!     &           '2 - > ',NORTHERN_FILTERED_P_ROW,' and ',                GPB3F403.116
!     &           SOUTHERN_FILTERED_P_ROW,' -> ',glsize(2)-1               GPB3F403.117
!      WRITE(6,*) 'SETFIL: Filtering ',                                    GPB3F403.118
!     &  REAL((glsize(2)-2)-                                               GPB3F403.119
!     &  (SOUTHERN_FILTERED_P_ROW-NORTHERN_FILTERED_P_ROW-1))/             GPB3F403.120
!     &  REAL(glsize(2)-2),' % of grid (not counting polar rows)'          GPB3F403.121

So... suppose you want to do something, but you don't know which deck you need to modify? Then thats tricky. I tend to use grep to search for an appropriate bit of code, or a diagnostic number.

Caution: decks come in different versions (SETFIL1A and SETFIL1B, for example). You need to look at your compiled source to see which version your code is using, before starting to mod it.

And once you've written your modset, you need to get it into your code: within the umui, go to: sub-model indep -> compilation and mods -> mods for the model.

Naturally enough, you'd probably like to test your mod somehow before doing the full compilation process.

This may be done by a command such as:

nupdate -p ~gcm/um/vn4.5/source/umpl -q $1 -c $1.f -o sq -s $1.f -i $2 -d $3

Note that all (almost all?) of the UM code is surrounded by IFDEF's. If you attempt to use nupdate without these, you will end up with an empty .f file. In most cases, the IFDEFs you need to include are obvious from the top of the code. In some cases, there willbe IFDEFs inside the code (MPP, for example) and you will need to set these too.

If thats confusing you, read on:

The code is, effecitively, pre-processed by nupdate in a manner similar to the C pre-processor, cpp. Which is to say... the source deck has "IFDEF"'s around blocks of code that are, say, processor or science-specific. By setting the appropriate defs, only those portions of code are extracted to be put into the compile file. This allows, for example, the same deck to work for MPP and single-processor code. So... for the pruposes of testing your mod, you can do 2 things:

1. Work out what defs are used in the "real" model compile (available from the compile output file). But this will be a long list.
2. Just add in enough defs to extract enough of your code so you can test the mod is doing about the right thing. How do you know? Just grep for IFDEF in the deck.