From Geos-chem
Jump to: navigation, search


NOTE: GCAP in the standard GEOS-Chem is mostly obsolete. Most simulations using the GCAP meteorology are now performed with the ICECAP model. This is a separate code base in which the GISS Model E dynamics have been integrated into GEOS-Chem.

Support for the legacy GCAP meteorology will be removed from v11-02d and later versions.

This is the main wiki page for the GEOS-Chem/GCAP model.

What is GCAP

GCAP is short for "Global Change and Air Pollution". It uses simulated climate data from GCMs to drive the chemical transport model GEOS-Chem to simulate present-day and future air quality.

How to run GCAP

Code revisions

The code used for GCAP in this wiki is GEOS-Chem v08.03.01. This version has more development based on GEOS-5 meteorological fields than GCAP. However, we can still use the code of this version by adding some switches for GCAP simulations. (UPDATES regarding running GCAP with more recent version, e.g. v9-01-02, are added by A. Tai, Jul 2012.)

1) Comment the force LAI option in 'GeosCore/ input_mod.f'.

Currently, there is no GCAP version MODIS LAI. We have to use AVHRR LAI instead.

  #if   !defined( GCAP )
  ! Force to use MODIS LAI if we use MEGAN. (ccc, 2/23/10)
           LMODISLAI = .TRUE.
           LAVHRRLAI = .FALSE.
           WRITE(6,'(/,a,/)') 'Force to use MODIS LAI for MEGAN.' //
       &        ' AVHRR LAI will not be used'
  • UPDATE (A. Tai, Jul 2012): As of v9-01-02, this issue is apparently resolved, i.e. GCAP can read MODIS LAI without any problem. Therefore, the recommended change here is no longer necessary.

2) Revise 'GeosCore/ nei2005_anthro_mod.f' for NEI2005 emission.

a) Currently, there is no switch for GCAP to use NEI2005 emission. However, the emission file for GEOS4 has the similar data structure, so we can add a switch for GCAP by using GEOS4 emission.

  #if defined( GEOS_5 )
        SNAME = 'GEOS5'
  #elif defined( GCAP   )
        SNAME = 'GEOS4'
  #elif defined( GEOS_4 )
        SNAME = 'GEOS4'
  #elif defined( GEOS_3 )
        SNAME = 'GEOS3'

b) NEI2005 uses the VISTAS emission by default. However, it only offers the data from 1999 to 2007. So it will be a problem for the GCAP simulation beyond this time period, especially for the future simulations. To solve this problem, we may fix the year of the emission data.

  #if   !defined( GCAP )
        WRITE( SYEAR, '(i4)') THISYEAR
        WRITE( SYEAR, '(i4)') 2002

3) Revise 'GeosCore/ toms_mod.f'.

GEOS-5 uses files from 'TOMS_200906'. However, GCAP uses files from 'TOMS_200701'.

  ! Define filename (with replaceable tokens)
  #if   !defined( GCAP )
        FILENAME = 'TOMS_200906/TOMS_O3col_YYYY.' // GET_NAME_EXT_2D() //
       &           '.'                            // GET_RES_EXT()
        FILENAME = 'TOMS_200701/TOMS_O3col_YYYY.' // GET_NAME_EXT_2D() //
       &           '.'                            // GET_RES_EXT()

Build GCAP executable

1) Uncomment the GCAP definition line in 'Headers/define.h'. Comment other definition line (e.g. GEOS5, GEOS4, GEOS3)

  !----- Model types -----
  #define GCAP        'GCAP'
  !#define GEOS_3      'GEOS_3'
  !#define GEOS_4      'GEOS_4'
  !#define GEOS_5      'GEOS_5'

2) In the main directory, type 'make realclean' to remove all the dependent and objective files away from each directory.

3) Type 'make' to build the executable file


To run the GCAP correctly, you need to download proper emission files, meteorological files, control files, initial/restart files, and information files.

1) Emission files

The emission files for GCAP are created on 72×45 grids, different from the 72×46 grids used in GEOS-5 simulations. Most of the GCAP emission files have names with 'gcap.4x5', which will be identified by GEOS-Chem model automatically if the switch for GCAP simulation is on in 'Headers/define.h'.

2) Meteorological files

GCAP use simulated meteorological fields from climate models as input. Currently, we can run GCAP with model data from the NASA/GISS Model 3 and the NASA/GISS Model E. Here is a list of GCAP met fields.

3) Control file 'input.geos'

a) Change the data directory path.

  Root data directory     : /as/group/gcap/data/GCAP_4x5/
   => GCAP       subdir   : AGRID/YYYY/MM/
   => GEOS-3     subdir   : GEOS_3/YYYY/MM/
   => GEOS-4     subdir   : GEOS_4_v4/YYYY/MM/
   => GEOS-5     subdir   : GEOS_5/YYYY/MM/

In this example, the emission files are located in "/as/group/gcap/data/GCAP_4x5/" and meteorological files are located in subdirectory "AGRID"

b) Change the NOx menu.

  => Use lightning NOx?  : T
      => Scale glb flrate?: F
      => OTD reg redist?  : F
      => OTD loc redist?  : F
      => Use CTH param?   : T
      => Use MFLUX param? : F
      => Use PRECON param?: F
  • UPDATE (A. Tai, Jul 2012): As of v9-01-02:
  => Use lightning NOx?  : T
        => Spat-seas constr?: F

c) Use AVHRR LAI instead of MODIS LAI.

  Use AVHRR-derived LAI?  : T
  Use MODIS-derived LAI?  : F
  • UPDATE (A. Tai, Jul 2012): As of v9-01-02, this issue is apparently resolved, i.e. GCAP can read MODIS LAI without any problem. Therefore, the recommended change here is no longer necessary.

d) Do not use variable tropopause.

  Use variable tropopause?: F

e) Use climatological monthly mean BC/OC emission which is not from GFED2

  => Use GFED2 biomass?  :---
      => monthly GFED2?   : F
      => 8-day GFED2?     : F 
      => 3-hr GFED2?      : F
      => synoptic GFED2?  : F
  • UPDATE (A. Tai, Jul 2012): As of v9-01-02, GFED3 (turned on by default) appears to be running properly in GCAP.

f) For v9-01-02 or higher versions, turn off RETRO emissions (for which there are no GCAP version)

  => Use RETRO emiss?    : F

4) Initial/restart files

Create proper initial/restart file with GAMAP rewrite_agprod. Make sure to use the right 'tau0', tracer number, and grid resolution. Commands in this subsection need typing in IDL.

  • UPDATE (A. Tai, Jul 2012): As of v9-01-02, the SOA restart files are soaprod.YYYYMMDDhh.

a) Change time information (tau0)

  rewrite_agprod, YMD=YYYYMMDD

A window will prompt out for you to choose the restart file whose 'tau0' you want to change into 'YYYYMMDD'.

b) Change spatial resolution (if necessary)

For example, you have an old restart file named 'restart_gprod_aprod.1996070100'. You want to interpolate into GCAP grid.

  regridh_restart, INFILENAME='restart_gprod_aprod.1996070100', OUTFILENAME='temp1', /GCAP, diagn=0
  regridv_restart, INFILENAME='temp1', OUTFILENAME='restart.gcap.1996070100', /GCAP, diagn=0

For more information, refer to section '1.3 Renaming and Regridding APROD/GPROD restart files' in wiki page of File I/O with GAMAP

5) Information files

GCAP needs some information and parameter files, for example, 'tracerinfo.dat', 'diaginfo.dat', 'jv_atms.dat', and so on. These files need be placed in the same directory with 'input.geos', initial/restart files, and GCAP executable file.


GCAP outputs 'ctm.bpch.YYYYMMDD' and 'restart.gcap.YYYYMMDD' files at the time step determined by the schedule set in the output menu of 'input.geos' file. The 'ctm' file contains emission, concentration, and deposition amount of gas/aerosol tracers. You can use GAMAP to analyze data and plot figures. The 'restart' file can be used to restart the GEOS-Chem model in sequent simulations. It can also be used as initial conditions for GEOS-Chem after changing proper 'tau0' and spatial resolution.

Frequently Asked Questions

  1. Where can I download GCAP codes and data?

    GCAP is not a name of model. It uses simulated climate data from GCMs to drive the chemical transport model GEOS-Chem to simulate present-day and future air quality. For the GEOS-Chem, please contact Prof. Daniel J. Jacob to join the user community and access the code. For the driven data, you may download both meteorological fields of the NASA/GISS GCM3 and emission files in '/pub/gcap/GCAP_4x5' through public FTP access 'ftp.as.harvard.edu'.

  2. Can I use GEOS_4x5 emission files and download only the AGRID data?

    It is important to download both AGRID data and emission data for GCAP. The grid resolution for GCAP is 72x45, while GEOS-5 is 72x46. As a result, you may not run the GCAP successfully with emissions from GEOS-5 or GEOS-4.

  3. I can not find the codes needed for revising, such as 'nei2005_anthro_mod.f'.

    The code revision introduced in this Wiki is for GEOS-Chem version v08.03.01. We may already include these revisions in the newer versions.

  4. How can I check the emission or meteorological files?

    You may use GAMAP programs to check these files. For emission, you may use gamap command and select the emission file to check its content. For meteorological data, use test_met command instead to check both maximum and minimum values for each variable.

  5. Where are the emissions for future simulation?

    For some natural gas/aerosol (e.g. biogenic organic carbon aerosol), the GEOS-Chem model will calculate new emissions in response to climate change. However, for future anthropogenic emissions, please contact Loretta Mickley.

  6. Where can I get a restart file to use or interpolate?

  7. How can I generate initial files for future simulation?

    The restart file for future can be easily created by GAMAP with the following command (used in IDL):

    rewrite_agprod, YMD=YYYYMMDD

    Where YYYYMMDD is the date in the future. The GAMAP will prompt a window automatically for you to select a pre-existing restart file. You may use any present-day restart file as the pre-existing restart file but make sure they are in the same month. For example, if you would like to create restart file for 20460701, then you'd better use 19960701 (or 19970701, the year is not important). The model will spin-up some time and reach equilibrium within a short time.


Here is a list of GCAP user groups and their research projects. Please add your information to the table.

User Group Description Contact Person Date Added
IAP/CAS GCAP Asia Hong Liao March 24, 2011

--Bob Y. 14:35, 13 January 2011 (EST)

Previous issues that are now resolved

Removed array temporaries in call to GCAP_CONVECT

These updates were validated in the 1-month benchmark simulation v10-01c and approved on 29 May 2014.

The GEOS-Chem Unit Tester revealed the presence of array temporaries in the call to GCAP convection routine GCAP_CONVECT. To remove the array temporaries, we made these modifications in subroutine DO_GCAP_CONVECT, located in module GeosCore/convection_mod.F:

(1) Declare the F variable with the TARGET attribute, as follows:

#if   defined( APM )
      INTEGER          :: INDEXSOL(Input_Opt%N_TRACERS+N_APMTRA) 
      REAL*8,  TARGET  :: F       (IIPAR,JJPAR,LLPAR,
     &                            Input_Opt%N_TRACERS+N_APMTRA)
      INTEGER          :: INDEXSOL(Input_Opt%N_TRACERS) 
      REAL*8,  TARGET  :: F       (IIPAR,JJPAR,LLPAR,
     &                            Input_Opt%N_TRACERS)

(2) Add pointer variables p_STT and p_F:

      ! Pointers
      REAL*8,  POINTER :: STT        (:,:,:,:)   ! Ptr to Tracer concentrations
      ... etc ...
      REAL*8,  POINTER :: p_STT      (:,:,:,:)   ! Ptr to STT (flipped)
      REAL*8,  POINTER :: p_F        (:,:,:,:)   ! Ptr to F   (flipped)

(3) Point p_STT to the State_Chm%Tracers field and flip levels in the vertical. Likewise, point p_F to the F array, and also flip in the vertical:

     ! Point to met fields and flip in vertical
     p_UPDE     => State_Met%UPDE     (:,:,LLPAR:1:-1  )
     ... etc ...
     p_STT      => State_Chm%Tracers  (:,:,LLPAR:1:-1,:)
     p_F        => F                  (:,:,LLPAR:1:-1,:)  

(4) Pass p_STT and p_F to subroutine GCAP_CONVECT:

      ! Call the GCAP convection routines 
! Prior to 4/15/14:
! Eliminate array temporary (bmy, 4/15/14)
!     &                   STT      (:,:,LLPAR:1:-1,:), 
     &                   p_STT,
     &                   N_TOT_TRC,
     &                   DP, ! I think this is the correct way (bmy, 5/25/05)
     &                   NSTEP, 
! Prior to 4/15/14:
! Eliminate array temporary (bmy, 4/15/14)
!     &                   F        (:,:,LLPAR:1:-1,:),     
     &                   p_F,
     &                   TCVV,   
     &                   INDEXSOL, 
     &                   p_UPDE,
     &                   p_DNDE,
     &                   p_ENTRAIN,
     &                   p_DETRAINE,
     &                   p_UPDN,
     &                   p_DNDN,
     &                   p_DETRAINN )

(5) Nullify the pointers p_STT and p_F at the end of subroutine DO_GCAP_CONVECT:

      ! Free pointers
      NULLIFY( STT,     p_STT,    p_F                    )

--Bob Y. 17:08, 30 May 2014 (EDT)

Fixed bugs caused by GIGC edits

This update was tested in the 1-month benchmark simulation v9-02m and approved on 30 Jul 2013.

We have now corrected several issues for the GCAP model that had been introduced when we modified GEOS-Chem for grid-independence (i.e. to facilitate connecting w/ the GEOS-5 GCM). These are:

  1. GeosCore/a3_read_mod.F and GeosCore/a6_read_mod.F
    • Now make sure to save data into the proper fields of the State_Met object
  2. GeosCore/gcap_read_mod.F
    • Pass the Input_Opt object to routine GET_GCAP_FIELDS
  3. GeosCore/input_mod.F
    • In routine INITIALIZE_GEOS_GRID, do not use half-sized polar boxes for the GCAP model
  4. GeosCore/wetscav_mod.F
    • In the GCAP section, make sure to pass the State_Chm object to the routine WETDEP
  5. GeosUtil/grid_mod.F90
    • For GCAP, compute the longitude centers so that we do not use half-sized polar boxes.
  6. Headers/smv_dimension_mod.F90
    • For GCAP, set the parameter MAX_COLUMN=23. This is used to set the NB parameter for FAST-J.

--Bob Y. 14:17, 2 July 2013 (EDT)

Bug fix for leap years with GCAP

This update was tested in the 1-month benchmark simulation v9-01-02e and approved on 01 Aug 2011.

Recall that the GCAP met fields are climatological GCM output, and do not have any leap years (i.e. there are no Feb 29ths).

In GEOS-Chem v9-01-01 and prior versions, routine SET_CURRENT_TIME in time_mod.f) uses the Astronomical Julian Date algorithms (located in julday_mod.f), which assume that there are leap-years. If you ran GEOS-Chem with the GCAP met fields for more than one year, the current code caused the time & date to be computed incorrectly at the start of the second year. GEOS-Chem would die because the wrong met fields would be read in from disk.

We have added an improved algorithm fix into SET_CURRENT_TIME for GCAP met fields only. Whenever a leap-year day (Feb 29th) is encountered, we shall just skip ahead a day to March 1st and compute the corresponding time & date values. However, we must also keep track of how many leap years we have encountered since the start of the GEOS-Chem simulation. This count is needed so that we can increment the current Astronomical Julian Date so as to "skip over" from Feb 29th to Mar 1st for each new leap year that we encounter.

This fix now skips from Feb 28 to Mar 1st for all leap years. We have tested this for multiple leap years and it works fine.

--Bob Y. 10:21, 31 October 2011 (EDT)

VEGEMIS bug in Hg simulation

Please see this wiki post which describes a bug in the switch that decides whether GEIA Hg emissions should be scaled to David Streets' 2006 regional GCAP emissions. This is now fixed in GEOS-Chem v9-01-02.

--Bob Y. 16:10, 31 October 2011 (EDT)

Outstanding issues that are not yet resolved

Missing PARDF and PARDR fields in 1995 met data

Carey Friedman wrote:

I can't get any of the a3 met files to work for 1995. I've compared the a3 files from 1995 to those from other years and they are smaller in size. Through gamap-ing it looks like they are missing photosynthetically active radiation (only 14 fields found instead of 16). Has anyone else found this before?

--Bob Y. 11:07, 31 October 2011 (EDT)