TOMAS aerosol microphysics

Overview

The TOMAS aerosol microphysics package was developed at Carnegie-Mellon University.

Authors and collaborators:

• Peter Adams (Carnegie-Mellon U.) -- Principal Investigator
• Win Trivitayanurak (Carnegie-Mellon U.)
• Dan Westervelt (Carnegie-Mellon U.)
• Jeffrey Pierce (Dalhousie U.)

Implementation notes

As of Jan 27, 2010, TOMAS is currently being implemented into GEOS-Chem v8-02-05 (version in testing).

Code structure

The main-level Code directory has now been divided into several subdirectories:

GeosCore/    GEOS-Chem "core" routines
GeosTomas/   Parallel copies of GEOS-Chem routines that reference TOMAS
GeosUtil/    "Utility" modules (e.g. error_mod.f, file_mod.f, time_mod.f, etc.
Headers/     Header files (define.h, CMN_SIZE, CMN_DIAG, etc.)
KPP/         KPP solver directory structure
bin/         Directory where executables are placed
doc/         Directory where documentation is created
help/        Directory for GEOS-Chem Help Screen
lib/         Directory where library files are placed
mod/         Directory where module files are placed
obsolete/    Directory where obsolete versions of code are archived

Because there were a lot of TOMAS-related modifications in several GEOS-Chem "core" routines, the routines that need to "talk" to TOMAS were placed into a separate subdirectory named GeosTomas/. The files in GeosTomas are:

Files:
------
Makefile            -- GEOS-Chem routines that have been
aero_drydep.f          modified to reference the TOMAS aerosol
carbon_mod.f           microphysics package.  These are kept
chemdr.f               in a separate GeosTomas directory so that
chemistry_mod.f        they do not interfere with the routines
cleanup.f              in the GeosCore directory.
diag3.f
diag_mod.f             The GeosTomas directory only needs to
diag_pl_mod.f          contain the files that have been modified
drydep_mod.f           for TOMAS.  The Makefile will look for
dust_mod.f             all other files from the GeosCore directory
emissions_mod.f        using the VPATH option in GNU Make.
gamap_mod.f
initialize.f           NOTE to GEOS-Chem developers: When you
input_mod.f            make changes to any of these routines
isoropia_mod.f         in the GeosCore directory, you must also
logical_mod.f          make the same modifications to the
ndxx_setup.f           corresponding routines in the GeosTomas
planeflight_mod.f      directory.
seasalt_mod.f
sulfate_mod.f          Maybe in the near future we can work
tomas_mod.f            towards integrating TOMAS into the GeosCore
tomas_tpcore_mod.f90   directory more cleanly.  However, due to
tpcore_mod.f           the large number of modifications that were
tpcore_window_mod.f    necessary for TOMAS, it was quicker to
tracerid_mod.f         implement the TOMAS code in a separate
wetscav_mod.f          subdirectory.    
xtra_read_mod.f            -- Bob Y. (1/25/10)

Each of these files were merged with the corresponding files in the GeosCore subdirectory. Therefore, in addition to having the GEOS-Chem modifications from v8-02-05, these files also have the relevant TOMAS references.

A few technical considerations dictated the placing of these files into a separate GeosTomas/ directory:

• The ND60 diagnostic in the standard GEOS-Chem code (in GeosCore/) is now used for the CH4 offline simulation, but in TOMAS it's used for something else.
• Some parameters needed to be declared differently with for simulations with TOMAS.
• Because not all GEOS-Chem users will choose to use TOMAS, we did not want to unnecessarily bog down the code in GeosCore/ with references to TOMAS-specific routines.

All of these concerns could be best solved by keeping parallel copies of the affected routines in the GeosTomas directory.

--Bob Y. 10:36, 27 January 2010 (EST)

Building GEOS-Chem with TOMAS

The VPATH feature of GNU Make is used to simplify the compilation. When GEOS-Chem is compiled with the TOMAS option, the GNU Make utility will search for files in the GeosTomas/ directory first. If it cannot find files there, it will then search the GeosCore/ directory. Thus, if we make a change to a "core" GEOS-Chem routine in the GeosCore/ subdirectory (say in dao_mod.f or diag49_mod.f), then those changes will automatically be applied when you build GEOS-Chem with TOMAS. Thus, we only need to keep in GeosTomas/ separate copies of those files that have to "talk" with TOMAS.

Several new targets were added to the Makefile in the top-level Code/ directory:

#=============================================================================
# Targets for TOMAS aerosol microphysics code (win, bmy, 1/25/10)
#=============================================================================

.PHONY: tomas libtomas exetomas cleantomas

tomas:
        @$(MAKE) -C $(GEOSTOM) TOMAS=yes all

libtomas:
        @$(MAKE) -C $(GEOSTOM) TOMAS=yes lib

exetomas:
        @$(MAKE) -C $(GEOSTOM) TOMAS=yes exe

cleantomas:
        @$(MAKE) -C $(GEOSTOM) TOMAS=yes clean

You can build GEOS-Chem with the TOMAS option by typing:

make TOMAS=yes ...

This will automatically do the proper things to build the TOMAS code into GEOS-Chem, such as:

• Adding a -DTOMAS C-preprocessor switch to the FFLAGS compiler flag settings in Makefile_header.mk. This will cause TOMAS-specific areas of code to be turned on.
• Turning off OpenMP parallelization. For now the GEOS-Chem + TOMAS code needs to be run on a single processor. We continue to work on parallelizing the code.
• Calling the Makefile in the GeosTomas/ subdirectory to build the executable. The executable file is now named geostomas in order to denote that the TOMAS code is built in.

The GEOS-Chem + TOMAS has been built on the following compilers

• Intel Fortran compiler v10
• SunStudio 12

--Bob Y. 10:36, 27 January 2010 (EST)

Validation

Text to be added

Previous issues now resolved

Text to be added

Outstanding issues

Text to be added