GEOS-5 Checkout and Build Instructions (Fortuna): Difference between revisions

These instructions presume checking out the PIESA group tag: '''AeroChem-Fortuna-2_5-b23'''.

The GEOS-5 (AGCM) source code checks out at about 55 MB of space.  Once compiled, the complete package is about 1.3 GB.  Your home space on '''discover''' may not be sufficient for checking out and building the code.  You should consider either 1) requesting a larger quota in your home space (call the tag x6-9120 and ask, telling them you are doing GEOS-5 development work) or 2) building in your (larger) nobackup space (recommended).  But consider, ''nobackup'' is not backed up.  So be careful...

=== Check Out the Code ===

Let's get ourselves ready to check out the code.  We'll be using the ''cvs'' command to check out the code.  The basic syntax is:

  % cvs -d :ext:pcolarco@cvsacldirect:/cvsroot/esma co -d GEOSagcm -r AeroChem-Fortuna-2_5-b23 Fortuna

So our module is ''Fortuna'' and the tag is ''AeroChem-Fortuna-2_5-b23''.  The code will check-out to a newly created directory call ''GEOSagcm''.  Note that I substituted the shortcut ''co'' for ''checkout'' in the above command.

The above command is generally valid. You ought to be able to execute it and checkout some code. If you don't have your ''ssh keys'' setup on '''cvsacl''' then you should be prompted for your '''cvsacl''' password. The assumption here is that your username on '''cvsacl''' is the same as on the machine you are checking the code out on.

Here's a short cut.  So that you don't have to type in the ''-d :ext:pcolarco@cvsacldirect:/cvsroot/esma'' business all the time, you can add the following lines to your, e.g., ''.cshrc'' file:

  setenv CVSROOT ':ext:pcolarco@cvsacldirect:/cvsroot/esma'

Modify as appropriate to put in your username in or if you use a different shell (i.e., put the analog of these lines into your .bashrc file or whatever).  Or if you are on a different machine than discover, the path to the '''cvsacl''' repository may be somewhat different.

  % cvs co -d GEOSagcm -r AeroChem-Fortuna-2_5-b23 Fortuna  

and the code will check out.

=== Build the Code ===

Now you've checked out the code.  Your should have a directory called GEOSagcm in front of you.  You're almost ready to build the code at this point.

The first thing to do is to set up your shell environment.  First, we need to define the environment variable ESMADIR, e.g.,

  % setenv ESMADIR $NOBACKUP/GEOSagcm

assuming you put the source code in your $NOBACKUP directory.

Then:

  % alias g5 'setenv ESMADIR $NOBACKUP/GEOSagcm;cd $ESMADIR/src;source g5_modules'

The executables are in the ''bin'' directory.  The resource files are in the ''etc'' directory.

== How to Setup and Run an Experiment ==

Now that you've built the code, let's try to run it.  In the exercise that follows, we will create a fresh experiment.

Let's make sure that your binaries from your compiled GEOS-5 code are in your path.  Include the following line somewhere in your .cshrc file:

  setenv PATH .:$NOBACKUP/GEOSagcm/Linux/bin:$PATH

where obviously you replace the particular path to the binaries with your path. Note what this implies: it won't be a good idea to move or clean this directory while the model is running!

=== Create the Experiment Directories ===

From your model build '''src''' directory, go into Applications/GEOSgcm_App.  Then run ''gcm_setup''.

Your will be prompted to answer some questions.  Here they are with some typical responses:

  Enter the Experiment ID:

  Enter a 1-line Experiment Description:

Enter the Model Vertical Resolution: LM (Default: 72)

  Do you wish to run GOCART? (Default: NO or FALSE)

  Enter the GOCART Emission Files to use: "CMIP" (Default), "PIESA", or "OPS":

Enter the AERO_PROVIDER: GOCART (Default) or PCHEM:

  Enter Desired Location for HOME Directory (to contain scripts and RC files)

  Enter Desired Location for EXP Directory (to contain model output and restart files)

Enter Location for Build directory containing:  src/ Linux/ etc...

  Current GROUPS: [List of groups you belong to]

  [Choose group]

Upon completion, you will have two directories, the HOME directory which is in your home space (something like ~/geos5/EXPID, where EXPID is the Experiment ID you named) and the EXP directory which is in your nobackup space.

 

 

 

 

 

 

 

To run with climatological aerosol forcing, modify the appropriate lines above to look like:

AEROCLIMDEL: ExtData/AeroCom/L72/aero_clm/gfedv2.del_aero.eta.%y4%m2clm.nc

AERO_PROVIDER: PCHEM  # options: PCHEM, GOCART            (Radiatively active aerosols)

'''HISTORY.rc'''

This file controls the output streams from the model.  Mine has the following collections:

  COLLECTIONS: 'geosgcm_prog'

'''CAP.rc'''

This file controls the timing of the model run.  For example, you specify the END_DATE, the number of days to run per segment (JOB_SGMT) and the number of segments (NUM_SGMT).  If you modify nothing else, the model would run until it reached END_DATE or had run for NUM_SGMT segments.  Note that you might think that BEG_DATE specifies a beginning date for the model to run.  It is set by default to BEG_DATE: 18910301 000000, which is probably before the period you want to simulate.  The actual model start time is specified later when we set up your EXP directory.

'''gcm_run.j'''

This is the model run script.  You might not need to edit anything, but check in here to see if we are pointing to the right emission files.  This is system dependent.  For our tag, on discover, there is a line:

setenv CHMDIR  /discover/nobackup/projects/gmao/share/dao_ops/fvInput_nc3

which points to the emission files presumed in this run.  You might have to modify this line on a different system or to use different emission inventories.

'''An Optional Modification'''

For some applications it is desirable to have the model stop running to generate restarts on fixed dates and then start up again.  (Each instance of the model running for some number of days and then stopping and generating restarts is called a ''segment''.)  For example, suppose we want restarts at the beginning and middle of the month. I've added this functionality, but you need to make a few edits.  What works is to ensure your model runs to the middle of the first month (in practice, the 17th of the month), stopping it, and then from that point to the 1st of the next month. Here's how: edit '''CAP.rc''' so that

  NUM_SGMT:    12

substituting the appropriate YYYYMM in END_DATE for the overall time you want your experiment to end.

By default the '''gcm_run.j''' on this tag has the following environment variables set like this:

  set STOP_MID_MONTH = 1

  set DFLT_JOB_SGMT = 16

Here's what is happening: overall model control is handled by '''CAP.rc'''.  We specify the model finish time with END_DATE in '''CAP.rc'''.  As set up, JOB_SGMT is the number of days to run the model in a single segment, and NUM_SGMT is the number of segments to run in a single queue submission.  With STOP_MID_MONTH set to '''1''' what happens is that the JOB_SGMT environment variable is tweaked for each half-month of the model run.  That is, the first segment runs the initial number of days (in this case, 17) and the next segment runs for however many days are needed to reach the 1st of the next month.  (In this example, I'm presuming we're starting from an initial date of 19991231, which requires us to run for 17 days to cause the model to stop on 20000117, which is the desired monthly mid-point.) What's really happening is that CAP.rc is being edited after each segment to specify the (hopefully) correct number of days to run the next segment.  Here, NUM_SGMT is set to '''12''', which will run the model for 6 months in a single queue submission (1/2 month per segment).  This seems to fit conservatively for our resolution in a single 8-hour wallclock time request.

If you don't care about any of this, you can set STOP_MID_MONTH = 0, which bypasses this logic and all segments are exactly as long as JOB_SGMT specifies.

This tag has successfully checked out, built, run, and archived results on NAS machine Pleiades.  No modifications to scripts are needed, as the appropriate choices for that machine are handled in gcm_setup.

=== Setup the EXP directory ===

Now go to your EXP directory.

You want to specify the model start time at this point.  Create a file called ''cap_restart".  The contents of the file should read:

  YYYYMMDD HHMMSS

where you replace the strings above with the year-month-day and hour-minute-second of your desired model start time.  For example:

  20071231 210000

You might want to edit the resource files in the RC sub-directory (e.g., '''GEOS_ChemGridComp.rc''' to turn on '''GOCART''' and '''Chem_Registry.rc''' to turn components on/off).

At this point we're ready to take a crack at running the model.  Go into your experiment HOME directory.  You can start the model job by issuing: