GAMAP v2–19 User Guide
Previous | Next | Printable View (no frames)
Before we can use the GAMAP package, we must now ensure that our system is set up to use IDL. We shall assume that you will use GAMAP on a Unix or Linux system.
If you use C-shell (csh) or T-shell (tcsh), add the following lines to your .cshrc file:
# Location of your "idl_startup.pro" file setenv IDL_STARTUP $home/IDL/idl_startup.pro
and to accept the changes, type this at the Unix prompt:
source ~/.cshrc
If you use Bourne-Again shell (bash), then add the these lines to your .bashrc file:
#Location of your "idl_startup.pro" file export IDL_STARTUP=$home/IDL/idl_startup.pro
and to accept the changes, type this at the Unix prompt:
source ~/.bashrc
Also, we assume that you have created a directory named ~/IDL in your personal disk space. This directory will be the top-level directory for your IDL source-code programs. We recommend installing the GAMAP package into your ~/IDL directory. This will be discussed in more detail in Chapter 2.2.
We will learn more about the idl_startup.pro file in Chapter 2.3.
NOTE: Some Windows users have experienced problems with directory paths due to the IDL Workbench, especially running under Windows 7. For this reason, we recommend that you use GAMAP on a Unix/Linux machine if possible. For more information, see this post and also this post on our General GAMAP Usage wiki page.
2.2 Installing the GAMAP directories
The GAMAP source code repository has now been migrated from CVS to Git, and is now available for remote download. (Git is an open-source version control system that is available for download at http://www.git-scm.com. You must have Git installed on your system to proceed.)
Like most GAMAP users, you probably have been storing the gamap2/ directory in a subdirectory of your ~/IDL/ directory. So let's rename the existing GAMAP directory:
cd ~/IDL mv gamap2 gamap2.backup
This will allow us to revert to the old code in case there is a problem w/ the Git download.
Once the existing directory has been backed up, you can then proceed to download the GAMAP source code from the Git online repository.
To download athe GAMAP source code, type:
git clone https://bitbucket.org/gcst/gamap2.git
This will create a "clone" of the gamap2/ directory, which will be populated with the GAMAP source code subdirectories. The various system files are all stored in the gamap2/.git subdirectory. The files in gamap2/ are an exact copy of what was on the Git repository server at the time you downloaded it.
If you wish to use a different directory name for your local "cloned" repository, you may type it as the second argument to git clone , e.g:
git clone https://bitbucket.org/gcst/gamap2.git new_gamap2
Here is a list of the subdirectories in the gamap2/ directory structure:
| Directory | Description of directory contents |
|---|---|
atm_sci/ |
Contains routines that perform atmospheric chemistry computations. |
benchmark/ |
Contains routines for creating standard comparison plots for GEOS-Chem 1-month benchmarks |
color/ |
Contains routines that define the color table and color bar. |
data_files/ |
Contains various data files (e.g. surface pressures, etc.) required by GAMAP. |
date_time/ |
Contains routines that compute and/or format the date and time. |
doc/ |
Contains routines for documenting IDL source code. |
examples/ |
Contains routines that educate users about the various features of GAMAP. |
file_io/ |
Contains routines that read data from / write data to disk. |
gamap_util/ |
GAMAP routines for displaying, reading, and plotting data. (These routines comprise most of the routines that used to be in the old ~/IDL/gamap directory of previous versions.) |
general/ |
Miscellaneous IDL routines that do not fall into any of the other categories. |
graphics/ |
Routines for reading from / writing to various graphic data file formats such as GIF, JPEG, BMP, PNG, TIFF, etc. |
idl_startup/ |
Contains the default idl_startup.pro for use with GAMAP (see Chapter 2.3) |
input_files/ |
Contains the gamap.defaults, diaginfo.dat, and tracerinfo.dat files for use with GAMAP. (See Chapter 7.) |
internals/ |
Internal GAMAP routines (i.e. not meant to be called by GAMAP users directly). |
manual/ |
Contains the GAMAP manual pages (a collection of the documentation from each of the GAMAP source code routine headers) in HTML and/or PDF format. The same documentation is also displayed in Chapter 5. |
math_units/ |
Contains routines for math, statistics, and unit conversion. |
plotting/ |
Contains general plotting routines. |
regridding/ |
Contains routines for regridding data from one model grid to another. |
strings/ |
Contains routines for working with strings. |
structures/ |
Contains routines for working with structures. |
| timeseries/ | Contains routines for working with 4D time series data (e.g. lon, lat, alt, time output) |
For a complete list of all GAMAP routines, as well as the relevant documentation, please see Chapter 5.
2.2.1 A little more information
Some programs were included from other authors, including David Fanning's TVIMAGE, TVREAD, and UNDEFINE routines, as well as Martin Schultz's NCDF_READ routine. Also, some of the color table definitions were taken from the ColorBrewer package.
Windows users should check their "Preferences" to make sure gamap2/ and its subdirectories are found. If you are already running an IDL session, exit and start again. You should now be able to use GAMAP.
Please visit the GEOS–Chem Programming Resources Web Page. There you will find several useful links to IDL-related sites.
Furthermore, there is a really good book on IDL available ("IDL Programming Techniques" by David Fanning. Finally, let us recommend the comp.lang.idl-pvwave newsgroup if you really want to learn about IDL.
Now that we have installed the GAMAP directory structure into our ~/IDL directory, let us take a further look at the idl_startup.pro file. This file is executed whenever an IDL session is started. It defines various quantities (such as the default colortable) which will be used in the IDL session.
A default idl_startup.pro file is contained in the gamap2/idl_startup directory. It is recommended to copy this file to your ~/IDL directory. Also make sure that your .cshrc file contains the defintion of the IDL_STARTUP environment variable as described above in Chapter 2.1).
The idl_startup.pro file looks like this:
;==============================================================================
; Startup file for IDL -- customized for GAMAP 2.18+ (bmy, 4/30/15)
;
; This file is an batch file (i.e. it is a list of IDL statements as
; you would type them from the IDL> command prompt). There are no
; "pro" and "end" statements, as there would be with regular IDL
; routines. Also, compound IF statements are not allowed.
;==============================================================================
;-----------------------------------------------------------------------------
; The !PATH variable contains various system directories in which you would
; like IDL to search for source code routines. We must insert the gamap2/
; directories up front so that IDL will search here before searching through
; the system directories.
;
; You may also add other directories in which you have IDL source code to
; the !PATH variable.
;------------------------------------------------------------------------------
; Call the IDL routine PATH_SEP to get the path separator token
; (i.e. the character that you need to separate directories in !PATH).
; This token is different depending on which OS you are using.
Sep = Path_Sep( /Search_Path )
; Add directories to the !PATH variable. Using IDL's EXPAND_PATH routine
; with the '+' sign will also cause any subdirectories to be added to the
; the !PATH variable.
;
; The /ALL_DIRS flag will cause all subdirectories to be added to !PATH
; and not just the subdirectories containing *.pro files.
; %%%%%%%%%% IDL 6.2 and later %%%%%%%%%%
; Use the PREF_SET command to append your directories into the default
; IDL search path. This approach is necessary if you want to use the
; IDLDE in IDL 7.0 and later versions. (phs, bmy, 4/15/08)
if ( !VERSION.RELEASE ge 6.2 ) then $
Pref_Set, 'IDL_PATH', $
Expand_Path( '+~/IDL/gamap2/', /All_Dirs ) + Sep + $
'', /Commit
;-----------------------------------------------------------------------------
; Various default settings
;-----------------------------------------------------------------------------
; Default character size, character thickness, and line thickness
!P.CHARSIZE = 1.2
!P.CHARTHICK = 1
!P.THICK = 1
; Default X and Y margins for the PLOT command
!X.MARGIN = [10,3]
!Y.MARGIN = [ 4,2]
; !EDIT_INPUT is the # of lines that you can up-arrow recall,
; but this is only defined in IDL versions prior to 6.2. (bmy, 3/21/06)
if ( !VERSION.RELEASE lt 6.2 ) then !EDIT_INPUT = 40
; Suppress status & warning messages for remote shell operation
if ( !D.NAME eq 'NULL' ) then !QUIET = 1
;-----------------------------------------------------------------------------
; Default device and color settings
;
; These commands will not be executed you if are running IDL on a NULL device
; (e.g. a terminal such as VT100 that can display text but not graphics).
;-----------------------------------------------------------------------------
; Get visual color depth
if ( !D.NAME ne 'NULL' ) then Device, Get_Visual_Depth=Depth
if ( N_Elements( Depth ) eq 0 ) then Depth = 0
if ( Depth lt 4 ) then RetAll
;-------
; This section comes from a newsgroup post by Liam Gumley, Wed, 13 Aug 1998.
; This will set the colors correctly on 8-bit, 24-bit, and TRUE COLOR devices.
;
; Use (normally 8) bit colors
if ( !D.NAME ne 'NULL' and $
!VERSION.OS_FAMILY eq 'unix' ) then Device, Pseudo=Depth
; Tell IDL to do the backing store instead of the window manager
; Also use pseudo colors instead of true color
if ( !D.NAME ne 'NULL' ) then Device, Retain=2, Decomposed=0
; Open a pixmap window to get color table and allocate space for all
; available colors but 15, so 15 colors are left for other apps
if ( !D.NAME ne 'NULL' ) then Window, /Free, /Pixmap, Colors=-15
;-------
; Manually set the default character size and spacing
; This is necessary for SGI, since the SGI default fonts are huge!
if ( !D.NAME ne 'NULL' ) then Device, Set_Character_Size=[ 6, 9 ]
; Load the WHITE-GREEN-YELLOW-RED custom colortable with MYCT
if ( !D.NAME ne 'NULL' ) then MyCt, /Verbose, /WhGrYlRd
; Test if !MYCT was created before we reference it below
DefSysV, '!MYCT', Exists=MYCT_Exists
; If we have loaded a MYCT color table, then the default background
; color will be white. Also set the default foreground color to black.
if ( !D.NAME ne 'NULL' and MYCT_Exists ) then !P.COLOR = !MYCT.BLACK
; Delete pixmap window so that plotting will create visible one
if ( !D.NAME ne 'NULL' ) then WDelete
;%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
;%%% Kludge by Bob Yantosca (bmy, 1/4/11)
;%%%
;%%% For Windows 7 displays, open a window of size 1000x700 pixels, at
;%%% top left corner of the screen. Otherwise the IDL window will be
;%%% placed so that you can't put a mouse pointer on it.
;%%%
;%%% Comment this out if it doesn't work for your display. This
;%%% is customized to Bob Y's window display, which is 1980x1200.
;%%%
;if ( !D.NAME ne 'NULL' ) then Window, XSize=1000, YSize=700, XPos=0, YPos=500
;%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
lines that you see in the file.
The idl_startup.pro file is essentially doing 4 things:
For the purposes of our discussion, the most important items in the above list are #1 and #4. We will discuss how to define paths in the next section. We will discuss color tables in Chapter 3.
2.4 Defining the default IDL paths
Let us take a closer look at the !PATH variable from the idl_startup.pro file. !PATH is a system variable (i.e. an IDL variable that is visible to all routines at all times) and it contains all of the directories in which you would like IDL to search for source code routines.
When we start IDL, the IDL executable directories and other system directories are automatically added to the !PATH variable. If !PATH is not modified, then IDL would only search through the system directories for source code routines.
In order to ensure that IDL searches for GAMAP routines before it looks for system routines, we must modify the !PATH variable such that we place the GAMAP source code directories first.
; Call the IDL routine PATH_SEP to get the path separator token ; (i.e. the character that you need to separate directories in !PATH). ; This token is different depending on which OS you are using. Sep = Path_Sep( /Search_Path )
This first statement defines the path separator token. This is the character that separates directories from each other in the !PATH variable string. For Unix, the path separator character is the colon; however, this may be a different character for other operating systems. IDL's PATH_SEP function will return the correct path separator token in a operating-system-independent way.
The next statements add directories to the IDL !PATH variable. Note that you have to do this in 2 ways, depending on your IDL version. The first method is for IDL versions 6.1 and earlier:
; Add directories to the !PATH variable. Using IDL's EXPAND_PATH routine
; with the '+' sign will also cause any subdirectories to be added to the
; the !PATH variable.
;
; The /ALL_DIRS flag will cause all subdirectories to be added to !PATH
; and not just the subdirectories containing *.pro files.
; %%%%%%%%%% IDL 6.1 and earlier %%%%%%%%%%
; Get the IDL system path and all subdirctories
if ( !VERSION.RELEASE lt 6.2 ) then $
IdlPath = Expand_Path( '+' + !PATH, /All_Dirs )
; Append your directories into the IDL !PATH variable
if ( !VERSION.RELEASE lt 6.2 ) then $
!PATH = Expand_Path( '+~/IDL/gamap2/', /All_Dirs ) + Sep + IdlPath
In addition to adding the top-level gamap2/ directory to the !PATH, we also need to include all subdirectories of gamap2/to !PATH as well. This is most easily done with IDL's EXPAND_PATH routine. By adding a + sign in front of the directory name in the call to EXPAND_PATH, we tell IDL to also include all subdirectories of gamap2/ into the !PATH variable. We also need to use the /ALL_DIRS keyword to EXPAND_PATH in order to ensure that all subdirectories (and not just those with *.pro) files will be added to the !PATH variable.
You may also add more directories of your own as well to !PATH as well. These should come after the gamap2/ directory
For IDL versions 6.2 and later we use a different method:
; %%%%%%%%%% IDL 6.2 and later %%%%%%%%%%
; Use the PREF_SET command to append your directories into the default
; IDL search path. This approach is necessary if you want to use the
; IDLDE in IDL 7.0 and later versions. (phs, bmy, 4/15/08)
if ( !VERSION.RELEASE ge 6.2 ) then $
Pref_Set, 'IDL_PATH', $
Expand_Path( '+~/IDL/gamap2/', /All_Dirs ) + Sep + $
'<IDL_DEFAULT>', /Commit
This is essentially doing the same thing as above, but instead of directly setting the !PATH statement, we are using the PREF_SET command to specify it.
This method is also required if you want to use the new the new IDL Workbench in IDL 7 and IDL 8. For more information, please see the entry in the GEOS–Chem wiki page for GAMAP and IDL 7.