KPP solvers FAQ

From Geos-chem
Revision as of 15:34, 10 November 2009 by Bmy (Talk | contribs) (How do I choose the absolute and relative tolerance?)

Jump to: navigation, search

Welcome to the "KPP and GEOS-Chem - Frequently Asked Questions" page.

What is KPP?

The Kinetic PreProcessor is a software that automatically generates F90 code that solves the chemistry (defined by input files) in a box model.

The KPP input files have been generated from the globchem.dat GEOS-Chem file with a Perl script, and KPP was run. The Kpp-generated code has been interfaced with GEOS-Chem.

KPP has been run twice for the standard NOx-Ox-VOC GEOS-Chem simulation: once for the 43 transported tracers model, and once for the 54 tracers version (ie with in-line secondary aerosols), since the two models have a slightly different globchem.dat.

What are the pros of using KPP?

In short, faster and better. In many points:

  1. It gives you a choice of different solvers that can have relative advantages depending on the level of desired accuracy [Sandu and Sander, 2006].
  2. One of the solver (radau5) is also recommended for "accurate reference solutions" [Sandu and Sander, 2006].
  3. By default, GEOS-Chem is compiled with the Rosenbrock Rodas3 solver:
    1. Tests reported in Henze et al. [2007] and Eller et al. [2009] show that the Rosenbrock solver is twice faster than SMVGEAR for the same accuracy. However this accuracy is with respect to a reference output obtained with the same solver.
    2. "At the very least, [using the Rosenbrock solver] results in an improvement in the numerical solution [...] for slightly less computational cost." [Henze et al., 2007]
    3. At low NOx regimes, like paleo simulations, the Rosenbrock solver is found more stable than SMVGEAR (L. Murray, personal communication, GEOS-Chem v8-01-04, 2009).

To get a measure of (3.2), a detailed comparison between SMVGEAR, Rosenbrock (Rodas3), and a reference solution was performed (pdf here). It shows that Rodas3 can be almost 10% faster for a more accurate solution. SMVGEAR is particularly bad at reproducing isoprene and the inorganic sulfur nitrates.

Here is the full list of transported species that show an RMS error larger than 10% for SMVGEAR and/or Rodas3. The numbers are RMS of relative error in %, from a comparison with a reference run, obtained with a Runge-Kutta order 5 integrator and very tight tolerances. All runs are for 13 days without transport on 4x5, the comparison is done with concentrations averaged over the 13th day.

         SMVGEAR    Rodas3     
 ISOP	 222.22   		
  NIT	  87.36      11.82	
  MVK	  33.26   		
 MACR	  30.40   
  PMN	  23.91   
  NH3	  19.10   
  DMS	  11.43   
 ALK4	  10.72   

See also "How does the default Rodas-3 Rosenbrock integrator compare with the SMVGEAR ?"

What are the cons of using KPP?

If you are changing the chemistry (species and/or reactions): you have to run KPP each time you modify globchem.dat to generate the gckpp*.f90 files. Then these files have to be adapted for GC, and replace the previous ones in GC code source. The whole process is described in "Interfacing GEOS-Chem with KPP".

Generally, if you are developing GC, be aware that the interface with KPP variables is done through both CSPEC and RRATE arrays (see physproc.f, calcrate.f, chemdr.f, and chemistry_mod.f).

Also, those of you who are using the Intel Fortran Compiler ("IFORT") version 9.1 should note that the KPP solver package has problems with this compiler version. You should upgrade to IFORT 10 or higher.

Can I still use the KPP-generated solver if I modify GEOS-Chem?

Yes. See "What are the cons of using KPP?"

Which GC simulation can use the KPP solvers?

For now, only the standard NOx-Ox-VOC simulations, with in- or off-line secondary aerosols. As of v8-02-03, the difference is in the number of transported tracers: 43 and 54.

By default, the code is compiled for 43 tracers. For the 54 tracers simulation, you can use the NTRAC flag when calling make:

make NTRAC=54

When switching between 43 and 54, you need to call:

make clean

Can I still use SMVGEAR?

Yes. There is a switch in the chemistry menu of the input.geos to choose between SMVGEAR and the KPP-derived solver at runtime.

Which KPP solvers can I use?

As of GEOS-Chem v8-02-03, you can choose between several stiff numerical solvers that depend on either the backward differentiation formula (BDF), Runge Kutta, or Rosenbrock methods.

Runge-Kutta (Fully Implicit 3-stage Runge-Kutta methods), based on several quadratures (*):

  Radau-2A   quadrature (order 5) [1] (default, stiffly accurate, robust, expensive)
  Radau-1A   quadrature (order 5) [4]
  Lobatto-3C quadrature (order 4) [2]
  Gauss      quadrature (order 6) [3]

LSODES (BDF, Livermore ODE solver, sparse array version)

Rosenbrock methods (*):

  Ros-2    [1]
  Ros-3    [2]
  Ros-4    [3]
  Rodas-3  [4] (default)
  Rodas-4  [5]

(*) For the Rosenbrock and Runge-Kutta methods, the default method can be overwritten by setting (before compilation, in chemistry_mod.f) the variable ictrl(3) to the number in square brackets.

For details on those methods and their implementation, see Sandu and Sander [2006] and its electronic supplement, and references therein.

How do I switch solver?

Solvers are chosen at three steps: before compilation, at compilation, and at runtime.

At runtime, you can switch between SMVGEAR and the KPP-derived solver with a single flag in the input.geos file. See the GEOS-Chem manual.

The KKP solver is chosen at compilation. When calling make, you can overwrite the default rosenbrock solver, with the KPPSOLVER flag:

make KPPSOLVER=<solver>

where <solver> must be one of: radau5, lsodes, runge_kutta, rosenbrock

(radau5 is a standalone Runge-Kutta solver of order 5 with Radau-2A quadrature)

You can further fine tune your choice of integrator by setting ictrl(3) in chemistry_mod.f before compilation. See "Which KPP solvers can I use?" above.

How do I choose the absolute and relative tolerance?

The tolerances used by solvers to check convergence are set differently for SMVGEAR and the KPP solvers.

For SMVGEAR, the range of absolute tolerance (ATOL) is defined in the mglob.dat file by YLOWU and YHIU. The relative tolerance (RTOL) is also set in mglob.dat with ERRMAXU, but it is overwritten in the code if you set it above 1d-3 (this is its max value, in other words).

For KPP-derived solvers, the tolerance are set in the GCKPP_DRIVER routine (in chemistry_mod.f). The code is distributed with the suggested value of:

  • RTOL = 2d-1 and
  • ATOL = 1d-2,

which give a solution slightly more accurate but ~8% faster than SMVGEAR.

For the Rodas-3 Rosenbrock solver, runtime and accuracy of the solution for various set of tolerances are described in this pdf. Some results are reproduced in the section How does the default Rodas-3 Rosenbrock integrator compare with the SMVGEAR? below.

If you switch to Livermore solver (LSODE), you do need to set ATOL between 1d4 and 1d6, to have a performance similar to SMVGEAR.

For an accurate solution with Radau5, you need small tolerances: RTOL=1d-8 for example.

Example: Tightening tolerances for SOA simulations

Here is an instance in which the relative error tolerance RTOL had to be tightened when performing a GEOS-Chem simulation with the secondary organic aerosol tracers:

Amos P.K. Tai ( wrote:

I've performed a few 3-month 4x5 GEOS-5 runs with the new v8-02-03 KPP solver with two different relative tolerance levels (RTOL) in the GCKPP_DRIVER subroutine in the chemistry_mod.f module. Then I counted the number of times I got the following error:
   Forced exit from Rosenbrock due to the following error:
   --> Step size too small: T + 10*H = T or H < Roundoff
   T=   2690.36541862269      and H=  6.025073049527794E-013
When this error occurs once in a row, the run would continue; but if it occurs twice in a row, the run crashes. I counted the number of this error in each of my 3-month runs that went without crashing.
  • For RTOL = 2d-1 (recommended), I've done four 3-month runs; the number of error ranges from 92 to 114.
  • For RTOL = 5d-2 (reduced), I've done two 3-month runs (otherwise all the same as before); no errors were detected in both runs.
So, reducing the tolerance level, as you have suggested before, appears to solve the problem of KPP solver leading to a crash.

--Bob Y. 10:22, 10 November 2009 (EST)

How does the default Rodas-3 Rosenbrock integrator compare with the SMVGEAR?

Faster by up to 10% for a slightly more accurate solution:

  • at one end, there is a RTOL between 0.2-0.3 that gives a solution as accurate but ~10% faster
  • at the other end, there is a RTOL between 0.03-0.04 that gives a solution as fast but an order of magnitude more accurate (~one significant digit better)

See this pdf for details. Here we summarize some of the findings:

Absolute tolerance ATOL has little to no effect in the [1e-2,1e+2] examined range. Using ATOL=1d-2, here is a comparison between SMVGEAR and Rodas-3 with several relative tolerances RTOL. The RMS of relative error in % of species with an error larger than 10%, and the runtime with respect to SMVGEAR are:

        Rodas3           SMVGEAR           Rodas3          Rodas3
        RTol=0.3                           RTol=0.2        RTol=0.1
 ISOP		         222.22  
  NIT	 14.75            87.36             16.33           11.82
  MVK			  33.26  
 MACR			  30.40 
  PMN			  23.91  
  NH3			  19.10 
  DMS			  11.43  
 ALK4			  10.72
 H2O2   2.23e9  
 HNO4 	 26.12
  PAN 	 23.43
  PPN 	 11.47

runtime  87%               100%             92%            93%
 notes                                      recommended    used in the adjoint-code

Can I run KPP and generate a box model myself ?

Yes. Installing, and running KPP, as well as interfacing the generated code with GEOS-Chem is described in "Interfacing GEOS-Chem with KPP".


  1. Eller et al., Geosci. Model Dev., 2, 89-96, 2009
  2. Henze et al., ACP, 7 ,2413-2433, 2007
  3. Sandu and Sander, ACP, 6, 187-195, 2006

--phs 16:54, 17 September 2009 (EDT)