Difference between revisions of "GAMAP tips and tricks"

From Geos-chem
Jump to: navigation, search
(GEOS-Chem TAU values)
 
(115 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Date and time ==
+
----
 +
<span style="color:red"><big><strong>[https://geoschem.github.io/gamap-manual/GAMAP GAMAP] is now obsolete.  We recommend using [https://gcpy.readthedocs.io GCPy] for analyzing output from recent GEOS-Chem versions.  But we will preserve the GAMAP wiki documentation for reference.</strong></big></span>
 +
----
  
=== Julian Day vs. Astronomical Julian Day ===
 
  
The '''Julian Day''' (JD) is used to denote the number of days that have elapsed since the start of a year.  For example, the Julian Day number of 2008/01/10 is 10 (since it is the 10th day of 2008).   
+
On this page we list information about GAMAP, the Global Atmospheric Model Analysis Package.   
  
However, another term that is sometimes confused with the Julian Day is the '''Astronomical Julian Day''' (AJD).  This is the number of days that have elapsed since 12:00 GMT on January 1, 4713 BC.  The Astronomical Julian Day at 00:00 GMT on 2008/01/10 is 2454475.5.
+
== Overview ==
  
The Astronomical Julian Day is mostly used in astrophysics and space sciences to compute long intervals of time that may span many years (e.g. the period of a variable star or of a comet's orbit, etc.).  You can find algorithms for computing AJD in several textbooks, including ''Practical Astronomy with Your Calculator'' by Peter Duffett-Smith, Cambridge Univ. Press, 1992.
+
GAMAP
  
The chief advantage of using the Astronomical Julian Day is that its computation accounts for the end-of-month, end-of-year, end-of-century, and end-of-millenium transitions.  This makes it very useful for computing future or past dates in scripts and computer programs.
+
* is a self-contained, consistent, and user-friendly software package for reading and visualizing output from chemical tracer models (CTM's)
 +
* consists of a suite of routines written in IDL (Interactive Data Language)
 +
* makes extensive use of IDL's powerful plotting features
 +
* can produce line plots, 2D plots, 2D animations, or 3D isocontour surface plots
 +
* can read 2D, 3D or 4D data blocks
 +
* can read output from the GEOS–Chem, GISS and FSU model families
 +
* can be easily customized to keep pace with ongoing model development
 +
* can be installed on any platform that supports IDL, thus ensuring a high degree of portability
 +
* can be coupled with the ION (IDL on the Net) interface to create interactive plots which can be served to a web page
 +
* can read data from ASCII, binary, netCDF (including COARDS conventions!), and HDF–EOS file formats
 +
* contains helper routines to read from / write to various file formats
  
For example, if you want to compute what the date will be 1000 days from 2008/01/01, then all you have to do is:
+
The main GAMAP program contains a user-friendly, menu-driven interface; however, users may also call GAMAP subroutines independently of the main program. This makes it possible to embed GAMAP routines within existing IDL code.
  
# compute the Astronomical Juliay Day for 2008/01/01
+
== Table of Contents ==
# add 1000
+
# convert back to a calendar date
+
  
We'll return to this example in the next section.
+
=== GAMAP web pages ===
  
'''''TIP: In order to avoid confusing Julian Day with Astronomical Julian Day, we recommend that you use the terminology "Day of Year" rather than "Julian Day". This will remove all ambiguity.'''''
+
* [https://geoschem.github.io/gamap-manual/ GAMAP main page]
 +
* [https://geoschem.github.io/gamap-manual/doc/index.html GAMAP Online User's Guide]
  
=== Astronomical Julian Day routines in IDL and GAMAP ===
+
=== GAMAP tips and tricks ===
  
IDL has two Astronomical Julian Day functions
+
* [[General GAMAP usage]]
 +
* [[File I/O with GAMAP]]
 +
* [[Color and graphics with GAMAP]]
 +
* [[Regridding with GAMAP]]
 +
* [[Date and time computations with GAMAP]]
 +
* [[Text manipulation with GAMAP]]
 +
* [[Removing extraneous lines from map plots]]
 +
* [[TVMAP cheat sheet]]
 +
* [[Reading binary files in IDL]]
  
* JULDAY -- converts a year, month, day (, hour, min, sec) to Astronomical Julian Date
+
--[[User:Bmy|Bob Y.]] 09:48, 11 March 2011 (EST)
* CALDAT -- converts an Astronomical Julian Day back to year, month, day (, hour, min, sec)
+
 
+
NOTE: The year, month, day are mandatory but you may omit the hour, min, sec.  If you omit hour, min, sec, then JULDAY will return an long integer value.  If you include hour, min, sec, JULDAY wil return a double precision value.
+
 
+
JULDAY and CALDAT are used as follows:
+
 
+
; Compute the Astronomical Julian Day for 2008/01/10
+
; Note: the day is required, the hours, mins, seconds are optional
+
IDL> print, julday( 1, 10, 2008, 0, 0, 0 )
+
        2454475.5
+
+
; Convert the Astronomical Julian Day back to a calendar date
+
IDL> caldat, 2454475.5, y, m, d, h, mi, s
+
IDL> print, y, m, d, h, mi, s
+
            1          10        2008          0          0      0.0000000
+
 
+
To compute the date 1000 days after 2008/01/01 (from the example in the preceding section), you would do the following:
+
 
+
IDL> jd = julday( 1, 1, 2008 )
+
IDL> jd = jd + 1000
+
IDL> caldat, jd, y, m, d
+
IDL> print, y, m, d
+
          9          27        2010
+
 
+
We find that gives us the date 2010/09/27.  NOTE: This has also accounted for the leap-year-day on Feb 29, 2008.
+
 
+
For your convenience, GAMAP has a function called ADD_DATE which will do this for you in one fell swoop:
+
 
+
IDL> print, add_date( 20080101, 1000 )
+
    20100927
+
 
+
You can also use ADD_DATE to compute days prior to a given date.  Let's compute what the calendar date was 1000 days prior to Jan 1, 2008:
+
 
+
IDL> print, add_date( 20080101, -1000 )
+
    20050406
+
 
+
=== Computing the day of year from a calendar date (and vice-versa) ===
+
 
+
A quick way to compute the day of the year is w/ IDL's JULDAY function:
+
 
+
Day_of_Year = JULDAY( Month, Day, Year ) - JULDAY( 1, 0, Year )
+
 
+
For example:
+
 
+
IDL> print, julday( 1, 10, 2008 ) - julday( 1, 0, 2008 )
+
      10
+
 
+
JULDAY( 1, 0, 2008 ) is another way of saying 12/31/2007.  This is used so that you don't have to add one to the above equation.  (This is equivalent to JULDAY( 1, 10, 2008 ) - JULDAY( 1, 1, 2008 ) + 1.)
+
 
+
The GAMAP function DAY_OF_YEAR does the above computation for you.  You can replace the statement above with:
+
 
+
IDL> print, day_of_year( 1, 10, 2008 )
+
      10
+
 
+
To compute the calendar date from the day of the year (the inverse operation), you can use IDL's CALDAT function.  However, you must also add the Astronomical Julian day for the first of the year, for example:
+
 
+
IDL> caldat, julday( 1, 0, 2008 )+10, y, m, d
+
IDL> print, y, m, d
+
        1          10        2008
+
 
+
But this is made much easier with the GAMAP functions DAY_OF_YEAR and ADD_DATE:
+
 
+
; Convert month/day/year to day of year
+
IDL> doy = day_of_year( 1, 10, 2008 )
+
IDL> print, doy
+
      10
+
+
; convert day of year back to month/day/year
+
IDL> print, add_date( 20080101, doy-1 )
+
    20080110
+
 
+
The only thing to remember is you have to subtract 1 from the day of year due to the way that ADD_DATE is written.
+
 
+
NOTE: Starting in GAMAP v2-12 (not released yet), you will be able to specify a single YYYYMMDD argument instead of the month, day, year arguments:
+
 
+
; Convert month/day/year to day of year
+
IDL> doy = day_of_year( 20080110 )
+
 
+
=== Separating YYYYMMDD into year, month day ===
+
 
+
 
+
 
+
=== GEOS-Chem TAU values ===
+
 
+
Conceptually similar to the Astronomical Julian Day, the TAU value is a monotonically-increasing time index that is used to timestamp output from the GEOS-Chem and GISS models:
+
 
+
* GEOS-Chem: TAU is the count of hours since 0 GMT on Jan 1, 1985
+
* GISS: TAU is the count of hours since 0 GMT on Jan 1, 1980
+
 
+
However, unlike the Astronomical Julian Day, TAU is given in hours and not days.  Also, the reason for the difference in starting date for TAU is that at the time GEOS-Chem was being created, there existed no meteorological data for it prior to Jan 1, 1985.  So 1/1/85 was taken as the start date.
+
 
+
GAMAP ships with 2 functions for working with TAU values: NYMD2TAU and TAU2YYMMDD.  They are used as follows:
+
 
+
; Convert a date and time to TAU
+
; GEOS-Chem style (from 1985) is the default
+
IDL> tau_gc = nymd2tau( 20080101, 030000 )
+
IDL> print, tau_gc
+
      201603.00
+
+
; Convert TAU back to date and time (GEOS-Chem style)
+
IDL> date = tau2yymmdd( tau_gc, /nformat )
+
IDL> print, date
+
    20080101      30000
+
 
+
Note that TAU2YYMMDD returns a 2-element vector with the date and time when you use the /NFORMAT keyword.  If you omit this keyword then TAU2YYMMDD will return a structure with year, month, day, hour, minute, second tags:
+
 
+
; Convert TAU back to date and time (GEOS-Chem style)
+
; but this time return as a structure
+
IDL> date = tau2yymmdd( tau_gc )
+
IDL> help, date, /structure
+
** Structure <2061898>, 6 tags, length=24, data length=24, refs=1:
+
    YEAR            LONG      Array[1]
+
    MONTH          LONG      Array[1]
+
    DAY            LONG      Array[1]
+
    HOUR            LONG      Array[1]
+
    MINUTE          LONG      Array[1]
+
    SECOND          LONG      Array[1]
+
 
+
NYMD2TAU and TAU2YYMMDD assume GEOS-Chem style (from 1 Jan 1985) as the default.  To compute TAU for GISS style (from 1 Jan 1980), you can call these functions with the /GISS keyword as follows:
+
 
+
; Convert date to TAU value (GISS style)
+
IDL> tau_giss = nymd2tau( 20080101, 030000, /giss )
+
IDL> print, tau_giss
+
      245451.00
+
+
; Convert TAU value back to date (GISS style)
+
IDL> date = tau2yymmdd( tau_giss, /nformat, /giss )
+
IDL> print, date
+
    20080101      30000
+
 
+
--[[User:Bmy|Bmy]] 09:56, 4 April 2008 (EDT)
+
 
+
== Combining output from timeseries files ==
+
 
+
'''''Ray Nassar (ray@io.as.harvard.edu) wrote:'''''
+
 
+
:I just have a quick question, is there any GAMAP routine that can average all hourly data blocks in a timeseries file to make a single daily average bpch file? 
+
 
+
:It appears like I could use the average option of ctm_sum.pro but I do not quite understand where the averaged data goes and afterwards would still have to write to bpch.
+
 
+
'''''Philippe Le Sager (plesager@seas.harvard.edu) replied:'''''
+
 
+
:Check the
+
 
+
    /gamap2/timeseries/gc_combine_nd49.pro
+
    /gamap2/timeseries/gc_combine_nd48.pro
+
 
+
:routines, which combines daily bpch files (nd48 & nd49 output, but also met field input files) into 4D data blocks. It has many options. You can extract a subset of data according to time and/or location, or process the data (moving average, daily max, shift to local time). You can either save the data into a new bpch file or just get an array of data in output.
+
 
+
:I wrote a tutorial that gives some pointers [http://www-as.harvard.edu/chemistry/trop/gamap/doc/timeseries_brief_tutorial.pdf here.]
+
 
+
:-Philippe
+
 
+
--[[User:Bmy|Bob Yantosca]] 09:43, 1 April 2008 (EDT)
+
 
+
== Memory management and CTM_MAKE_DATAINFO ==
+
 
+
When using CTM_MAKE_DATAINFO, you create few pointers and allocate memory to pointed data. Three scenarios to free that memory are possible.
+
 
+
(1) By default, GAMAP keeps track of the pointers in a global structure, and you can clean up the memory by calling CTM_CLEANUP (with or without the keyword /NO_GC):
+
 
+
    ctm_make_datainfo(data, ...)
+
    CTM_WriteBpch, DataInfo, FileInfo, FileName=file
+
    ctm_cleanup
+
 
+
(2) If you use the keyword /NO_GLOBAL when calling CTM_MAKE_DATAINFO, the story is a little bit more subtle. Now, GAMAP has no idea of the created pointers. If you use CTM_CLEANUP without the keyword /NO_GC, everything is clean up because there is a call to heap_gc. But you are also loosing **all other** pointers and objects.
+
 
+
    ctm_make_datainfo(data, ..., /No_global)
+
    CTM_WriteBpch, DataInfo, FileInfo, FileName=file
+
    ctm_cleanup
+
 
+
Note if you do not call ctm_cleanup or call it with /No_GC, then the memory allocated by CTM_MAKE_DATAINFO is still allocated and the pointers that refers to it are alive... until you exit the routine (unless they are passed back). Once you are out of the routine, this memory remains allocated but is useless since unaccessible, in other words you have memory leak.
+
 
+
(3) So, if you want to keep some objects and/or pointers alive in your code (i.e., you do not want to call heap_gc or ctm_cleanup,/no_gc), you need to free only the created pointers as follows:
+
 
+
    ctm_make_datainfo(data, datainfo, fileinfo, ..., /No_global)
+
    CTM_WriteBpch, DataInfo, FileInfo, FileName=file
+
    ptr_free, DataInfo.data
+
    ptr_free, fileinfo.gridinfo
+
 
+
To free only the heap memory created by multiple calls to CTM_MAKE_DATAINFO, the procedure is:
+
 
+
  for D=0L, NTracers-1L do begin
+
     
+
      Success = CTM_Make_DataInfo( Data[*,*,D], DataInfo, FileInfo, ..., /No_Global )
+
     
+
      ArrDataInfo = D eq 0l ? [ DataInfo ] : [ ArrDataInfo, DataInfo ]
+
     
+
      if D ne Ntracers-1l then ptr_free, Fileinfo.gridinfo
+
     
+
  endfor
+
     
+
  CTM_WriteBpch, ArrDataInfo, FileInfo, FileName=OutFileName
+
     
+
  for d=0, n_elements(ArrDataInfo)-1l do ptr_free, ArrDataInfo[d].data
+
  ptr_free, fileinfo.gridinfo
+
 
+
--[[User:Phs|Philippe Le Sager]] 10:28, 13 February 2008
+

Latest revision as of 19:02, 16 September 2022


GAMAP is now obsolete. We recommend using GCPy for analyzing output from recent GEOS-Chem versions. But we will preserve the GAMAP wiki documentation for reference.



On this page we list information about GAMAP, the Global Atmospheric Model Analysis Package.

Overview

GAMAP

  • is a self-contained, consistent, and user-friendly software package for reading and visualizing output from chemical tracer models (CTM's)
  • consists of a suite of routines written in IDL (Interactive Data Language)
  • makes extensive use of IDL's powerful plotting features
  • can produce line plots, 2D plots, 2D animations, or 3D isocontour surface plots
  • can read 2D, 3D or 4D data blocks
  • can read output from the GEOS–Chem, GISS and FSU model families
  • can be easily customized to keep pace with ongoing model development
  • can be installed on any platform that supports IDL, thus ensuring a high degree of portability
  • can be coupled with the ION (IDL on the Net) interface to create interactive plots which can be served to a web page
  • can read data from ASCII, binary, netCDF (including COARDS conventions!), and HDF–EOS file formats
  • contains helper routines to read from / write to various file formats

The main GAMAP program contains a user-friendly, menu-driven interface; however, users may also call GAMAP subroutines independently of the main program. This makes it possible to embed GAMAP routines within existing IDL code.

Table of Contents

GAMAP web pages

GAMAP tips and tricks

--Bob Y. 09:48, 11 March 2011 (EST)