5 Directory Structure

5.1 Model Source Code Directory Structure

The following figure describes the basic directory structure containing source code and utility scripts for a tgcm model:

                                $TGCMROOT/
                                    |
            ------------------------------------------------------
               |       |     |      |         |         |       | 
            scripts/  bin/  doc/  $model/  $model1/  $model2/  ...  
                                    |
                                    |
                            -----------------
                            |               |    
                           src/          scripts/
                            |               |   
                            |               |  
                           *.h          tgcm_config
                           *.F          Makefile
                                        MkDepends
                                        $model-$os.job
                                        (other utils)

Where $TGCMROOT is one of three possibilities:

• At HAO: /home/tgcm (frozen code for released models in $model/src)
• At CISL: /fis/hao/tgcm (frozen code for released models in $model/src)
• Custom: User directory in which tar file was extracted.

The tgcm root directory may be set in one of three ways:

• Use the -tgcmroot option when calling a perl script utility.
• Set the $tgcmroot shell variable in a shell script (e.g., the job script)
• Set the $TGCMROOT environment variable in your .cshrc file.

Using the -tgcmroot option to a utility will override any setting of the $TGCMROOT environment variable (see, for example, sections 3.3 and 4.2). The job script simply passes the $tgcmroot shell variable to tgcm_config via the -tgcmroot option.

There are several models under each of the default $TGCMROOT directories at HAO and CISL. Models with the same names at HAO and CISL have identical source code. A valid $model is any subdirectory in TGCMROOT which contains source code in $model/src and utility scripts in $model/scripts. Most model subdirectories under the default TGCMROOTs are in the following model "classes" (the x.x extension is an optional version number):

• tiegcm, tiegcm[x.x]
• timegcm, timegcm[x.x]
• mtgcm, mtgcm[x.x]

Model names without an x.x extension are synonomous (have the same source) with the latest versioned model of that class. For example, if the latest version of tiegcm is "tiegcm1.6", then the models "tiegcm" and "tiegcm1.6" have identical source code. When the next version is released, say "tiegcm1.7", then tiegcm is updated to the 1.7 source. Versioned models (with the extension) are never changed once they are released. An announcement will go out to the tgcmgroup email list (tgcmgroup@ucar.edu) whenever a new version is released.

$os in the job script name will be "ibm", "sgi", or "linux". For $TGCMROOT/$model to be valid, it must contain both src/ and scripts/ subdirectories. Use the ListModels utility (6.2 to list valid models for a given $TGCMROOT.

The contents of $model/$scripts are linked to $TGCMROOT/scripts for your convenience. Commands and utilities from the scripts directory are linked to $TGCMROOT/bin.

5.2 Data directory TGCMDATA

The TGCMDATA directory (specified as an environment variable or a script option) contains read-only input data files to be read by the models. The configuration script tgcm_config links the necessary files, appropriate for the model and resolution being run, to the users $execdir (see next section).

The default TGCMDATA directories at NCAR are:

• At HAO: /toshi/ftp/pub/tgcm/data
• At CISL: /hao/tgcm/data

                                $TGCMDATA/
                                    |
                                    |
                                 TGCM*.nc          (default source history files)
                                 gpi*.nc           (geophysical indices database)
                                 gswm*.nc          (GSWM tidal boundaries)
                                 magfield*.nc      (magnetic field data)
                                 ncep*.nc          (NCEP TN lbc)
                                 solgar_bndry*.nc  (Solomon-Garcia lbc)
                                 solgar_import*.nc (Solomon-Garcia species import)
                                 zatmos_bndry*.nc  (Z lbc)

5.3 Working Directory Structure

After a user makes a run using the default configuration, their working directory will have the following structure (see also 4)

                                 $wrkdir/
                                    |
                                    |
                    ---------------------------------
                    |               |               |
                    |               |               |
                 $execdir         *.job          modsrc/ 
               ($model-$os/)      *.inp            *.h
                    |             *.out            *.F 
                    |                               
                  *.o
                  *.mod
                  *.nc
                  $model (executable)

Here $wrkdir is the directory from which the user executes the job script. The subdirectory $model-$os is the run directory (also called the execution dir, or $execdir), where the model is built and executed. Here, $os is "aix", "irix64", or "linux"). The run directory contains object and module files from the build (*.o, *.mod), netCDF data files (*.nc), and the executable file, which takes the name of the model being built ($model). The run directory may also contain various utility scripts (e.g., Makefile, Mk*), and user modified or new source code. The run directory can be customized by setting the $execdir shell variable in the job scripts.

The *.job files are job script(s), the user executed to build and run the model. The *.inp file(s) are namelist input files used in the run, and *.out are output files from the job script and the model itself.

The modsrc directory is optional, and contains the user's new or modified source code (see 4.3).