View source for TOMAS aerosol microphysics

== Overview ==

The TwO-Moment Aerosol Sectional (TOMAS) microphysics package was developed for implementation into GEOS-Chem at Carnegie-Mellon University. Using a moving sectional and moment-based approach, TOMAS tracks two independent moments (number and mass) of the aerosol size distribution for 30 size bins. It also contains codes to simulate nucleation, condensation, and coagulation processes. The aerosol species that are considered with 30-bin size resolution are sulfate, sea-salt, BC/OC, EC, and dust. 

'''Authors and collaborators:'''
* [mailto:petera@andrew.cmu.edu Peter Adams]  ''(Carnegie-Mellon U.)''  -- Principal Investigator
* [mailto:wtrivita@staffmail.ed.ac.uk Win Trivitayanurak] ''(Carnegie-Mellon U. -- now at U. Edinburgh)''
* [mailto:dwesterv@andrew.cmu.edu Dan Westervelt] ''(Carnegie-Mellon U.)''
* [mailto:jeffrey.pierce@dal.ca Jeffrey Pierce] ''(Dalhousie U.)''

Questions regarding TOMAS can be directed at Dan (e-mail linked above).

--[[User:Dan Westervelt|Dan W.]] 11:53, 27 January 2010 (EST)

== Tracers ==

TOMAS is a simulation type 3 and utilizes 310 tracers. Each aerosol species requires 30 tracers for the 30 bin size resolution. Here is the (abbreviated) default setup in input.geos (see run.Tomas directory):

 Tracer #   Description
 40         H2SO4
 41-70      Number
 71-100     Sulfate
 101-130    Sea-salt
 131-160    Hydrophilic EC
 161-190    Hydrophobic EC
 191-210    Hydrophilic OC
 211-240    Hydrophobic OC
 241-271    Mineral dust
 271-310    Aerosol water

--[[User:Dan Westervelt|Dan W.]] 21:08, 28 January 2010 (EST)

== 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 <tt>Code</tt> 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 <tt>GeosTomas/</tt>.  The files in <tt>GeosTomas</tt> 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 <tt>GeosCore</tt> subdirectory.  Therefore, in addition to having the GEOS-Chem modifications from [[GEOS-Chem v8-02-05|v8-02-05]], these files also have the relevant TOMAS references.

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

* The ND60 diagnostic in the standard GEOS-Chem code (in <tt>GeosCore/</tt>) 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 <tt>GeosCore/</tt> with references to TOMAS-specific routines.  

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

--[[User:Bmy|Bob Y.]] 10:36, 27 January 2010 (EST)

=== Building GEOS-Chem with TOMAS ===

The <tt>VPATH</tt> feature of [http://www.gnu.org/software/make/manual/make.html 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 <tt>GeosTomas/</tt> directory first.  If it cannot find files there, it will then search the <tt>GeosCore/</tt> directory. Thus, if we make a change to a "core" GEOS-Chem routine in the <tt>GeosCore/</tt> subdirectory (say in <tt>dao_mod.f</tt> or <tt>diag49_mod.f</tt>), then those changes will automatically be applied when you build GEOS-Chem with TOMAS.  Thus, we only need to keep in <tt>GeosTomas/</tt> separate copies of those files that have to "talk" with TOMAS.

Several new targets were added to the <tt>Makefile</tt> in the top-level <tt>Code/</tt> 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 <tt>-DTOMAS</tt> C-preprocessor switch to the <tt>FFLAGS</tt> compiler flag settings in <tt>Makefile_header.mk</tt>.  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 <tt>GeosTomas/</tt> subdirectory to build the executable.  The executable file is now named <tt>geostomas</tt> 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

--[[User:Bmy|Bob Y.]] 10:36, 27 January 2010 (EST)

== Microphysics Routines ==
The aerosol microphysics code is largely contained within the file <tt>tomas_mod.f</tt>. Tomas_mod and its subroutines are modular -- they use all their own internal variables

=== Aerophys ===
The aerophys routine is where each individual microphysical process is called within the code. Since H2SO4 is the main condensing species, H2SO4 concentrations are calculated using a pseudo-steady state approach as described in Pierce and Adams, 2009, ''AS&T''. Within this routine, nucleation, condensation, and coagulation are calculated at each time step. <tt>Cond_nuc</tt> is called for coupled nucleation-condensation. Nucleation schemes can either be binary (Vehkamaki et al 2002) or ternary (Napari et al 2002). There is a switch for this in the variable declarations. For nucleation, a parameterization (Kerminen et al 2004) is used to determine the flux of new particles to the first size bin.

--[[User:Dan Westervelt|Dan W.]] 22:36, 28 January 2010 (EST)

== Validation ==

Text to be added

== Previous issues now resolved ==

None known at this time.

== Outstanding issues ==

None known at this time.