Difference between revisions of "KPP solvers FAQ"

From Geos-chem
Jump to: navigation, search
(→‎How do I choose the absolute and relative tolerance?)
(→‎Example: Tightening tolerances for SOA simulations)
(31 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
Welcome to the "KPP and GEOS-Chem - Frequently Asked Questions" page.
+
== Current KPP documentation ==
  
 +
We have migrated our KPP-for-GEOS-Chem documentation to '''https://kpp.readthedocs.io'''.
  
−
== What is KPP? ==
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:45, 2 March 2021 (UTC)
  
−
The Kinetic PreProcessor is a software that automatically generates F90 code that solves the chemistry (defined by input files) in a box model.
+
== How do I choose the absolute and relative tolerance? ==
  
−
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.
+
The tolerance are set in the <tt>DO_FLEXCHEM</tt> routine (in <tt>flexchem_mod.F90</tt>). GEOS-Chem 13.0.0 uses these default values:
  
−
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.
+
    !%%%%% CONVERGENCE CRITERIA %%%%%
−
 
+
−
== What are the pros of using KPP? ==
+
−
 
+
−
In short, '''faster and better'''. In many points:
+
−
 
+
−
# It gives you a choice of different solvers that can have relative advantages depending on the level of desired accuracy [Sandu and Sander, 2006].
+
−
# One of the solver (radau5) is also recommended for "accurate reference solutions" [Sandu and Sander, 2006].
+
−
# By default, GEOS-Chem is compiled with the Rosenbrock Rodas3 solver:
+
−
## 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.
+
−
## "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]
+
−
## 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 [http://acmg.seas.harvard.edu/geos/word_pdf_docs/rodas3_smvgear_comp.pdf (pdf here)]. It shows that Rodas3 can be almost 10% faster for a more accurate solution. SMVGEAR is
+
    ! Absolute tolerance
−
particularly bad at reproducing isoprene and the inorganic sulfur nitrates.
+
     ATOL     = 1e-2_dp
−
 
+
−
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|"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 [[GEOS-Chem_v8-02-03#KPP_is_not_compatible_with_IFORT_9.1|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)
+
    ! Relative tolerance
−
  Radau-1A  quadrature (order 5) [4]
+
    IF ( Input_Opt%LUCX  ) THEN
−
  Lobatto-3C quadrature (order 4) [2]
+
      ! UCX-based mechanisms
−
  Gauss     quadrature (order 6) [3]
+
      !RTOL      = 2e-2_dp
−
+
      !RTOL     = 1e-2_dp
−
LSODES (BDF, Livermore ODE solver, sparse array version)
+
      RTOL      = 0.5e-2_dp
−
+
    ELSE
−
Rosenbrock methods (*):
+
      ! Non-UCX mechanisms
−
+
      RTOL      = 1e-2_dp
−
  Ros-2    [1]
+
    ENDIF
−
  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 the Rodas-3 Rosenbrock solver, runtime and accuracy of the solution for various set of tolerances are [http://acmg.seas.harvard.edu/geos/word_pdf_docs/rodas3_smvgear_comp.pdf described in this pdf].  
  
−
For details on those methods and their implementation, see Sandu and Sander [2006] and its electronic supplement, and references therein.
+
If you switch to Livermore solver (LSODE), you do need to set ATOL between 1d4 and 1d6, to have a performance similar to SMVGEAR.
  
−
== How do I switch solver? ==
+
For an accurate solution with Radau5, you need small tolerances: RTOL=1d-8 for example.
  
−
Solvers are chosen at three steps: ''before compilation'', at ''compilation'', and at ''runtime''.
+
=== Solver convergence issues posted on Github  ===
  
−
'''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.
+
See these issues:
  
−
The KKP solver is chosen '''at compilation'''. When calling make, you can overwrite the default rosenbrock solver, with the KPPSOLVER flag:
+
#[https://github.com/geoschem/geos-chem/issues/66 geoschem/geos-chem #66]
−
 
+
−
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 <tt>GCKPP_DRIVER</tt> routine (in <tt>chemistry_mod.f</tt>). 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 [http://acmg.seas.harvard.edu/geos/word_pdf_docs/rodas3_smvgear_comp.pdf described in this pdf]. Some results are reproduced in the section [[KPP_solvers_FAQ#How_does_the_default_Rodas-3_Rosenbrock_integrator_compare_with_the_SMVGEAR_.3F|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 ===
 
=== Example: Tightening tolerances for SOA simulations ===
Line 131: Line 41:
 
Here is an instance in which the relative error tolerance <tt>RTOL</tt> had to be tightened when performing a GEOS-Chem simulation with the secondary organic aerosol tracers:
 
Here is an instance in which the relative error tolerance <tt>RTOL</tt> had to be tightened when performing a GEOS-Chem simulation with the secondary organic aerosol tracers:
  
−
'''''Amos P.K. Tai (tai@seas.harvard.edu) wrote:'''''
+
'''''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 (<tt>RTOL</tt>) in the <tt>GCKPP_DRIVER</tt> subroutine in the <tt>chemistry_mod.f</tt> module.  Then I counted the number of times I got the following error:
+
<blockquote>I've performed a few 3-month 4x5 GEOS-5 runs with the v8-02-03 KPP solver with two different relative tolerance levels (<tt>RTOL</tt>) in the <tt>GCKPP_DRIVER</tt> subroutine in the <tt>chemistry_mod.f</tt> module.  Then I counted the number of times I got the following error:</blockquote>
  
 
     Forced exit from Rosenbrock due to the following error:
 
     Forced exit from Rosenbrock due to the following error:
Line 139: Line 49:
 
     T=  2690.36541862269      and H=  6.025073049527794E-013
 
     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.
+
<blockquote>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 = 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.
+
*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.
+
So, reducing the tolerance level, as you have suggested before, appears to solve the problem of KPP solver leading to a crash.</blockquote>
  
 
--[[User:Bmy|Bob Y.]] 10:22, 10 November 2009 (EST)
 
--[[User:Bmy|Bob Y.]] 10:22, 10 November 2009 (EST)
  
−
== How does the default Rodas-3 Rosenbrock integrator compare with the SMVGEAR? ==
+
=== More about tolerances ===
  
−
Faster by up to 10% for a slightly more accurate solution:
+
'''''[mailto:Tao.Zeng@dnr.state.ga.us Tao Zeng] wrote:'''''
−
*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 [http://acmg.seas.harvard.edu/geos/word_pdf_docs/rodas3_smvgear_comp.pdf 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
+
<blockquote>
−
ATOL=1d-2, here is a comparison between SMVGEAR and Rodas-3 with several relative tolerances
+
By reducing RTOL from 0.2 to 0.05, you were able to run the model for longer time without errors.
−
RTOL. The RMS of relative error in % of species with an error
+
−
larger than 10%, and the runtime with respect to SMVGEAR are:
+
  
−
                         
+
I tried your method and found it works. But I am quite confused with the setting. To my understanding, we enlarge the tolerance to make it not so strict, it's like to open the door a little wider. But why does it work in the opposite way in the KPP case?
−
        Rodas3          SMVGEAR          Rodas3          Rodas3
+
</blockquote>
−
        RTol=0.3                          RTol=0.2        RTol=0.1
+
 
−
        =======================================================================
+
'''''Claire Carouge wrote:'''''
−
  ISOP         222.22 
+
<blockquote>I am not sure of what is happening but I think I have an idea.  
−
  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 ? ==
+
The errors occur because the system arrives to a state too far from the truth to be able to converge. By tightening the tolerances, you make sure the system stays closer to the truth at every time step. Then, the problematic time steps start the chemistry with a system closer to the true state, enabling the chemistry to converge even with a tighter tolerance.
−
Yes. Installing, and running KPP, as well as interfacing the generated code with GEOS-Chem is described in [[Interfacing GEOS-Chem with KPP|"Interfacing GEOS-Chem with KPP"]].
+
  
−
== References ==
+
Typically, if the first time step of chemistry couldn't converge, tightening the tolerances wouldn't work but loosening the tolerance would. Since here it is not the first time step, tightening the tolerances can work by keeping the system errors smaller before.</blockquote>
−
#Eller et al., Geosci. Model Dev., 2, 89-96, 2009
+
−
#Henze et al., ACP, 7 ,2413-2433, 2007
+
−
#Sandu and Sander, ACP, 6, 187-195, 2006
+
  
−
--[[User:Plesager|phs]] 16:54, 17 September 2009 (EDT)
+
--[[User:Bmy|Bob Y.]] 10:35, 11 March 2010 (EST)

Revision as of 16:54, 2 March 2021

Current KPP documentation

We have migrated our KPP-for-GEOS-Chem documentation to https://kpp.readthedocs.io.

--Bob Yantosca (talk) 16:45, 2 March 2021 (UTC)

How do I choose the absolute and relative tolerance?

The tolerance are set in the DO_FLEXCHEM routine (in flexchem_mod.F90). GEOS-Chem 13.0.0 uses these default values: 

   !%%%%% CONVERGENCE CRITERIA %%%%%

   ! Absolute tolerance
   ATOL      = 1e-2_dp

   ! Relative tolerance
   IF ( Input_Opt%LUCX  ) THEN
      ! UCX-based mechanisms
      !RTOL      = 2e-2_dp
      !RTOL      = 1e-2_dp
      RTOL      = 0.5e-2_dp
   ELSE
      ! Non-UCX mechanisms
      RTOL      = 1e-2_dp
   ENDIF

For the Rodas-3 Rosenbrock solver, runtime and accuracy of the solution for various set of tolerances are described in this pdf.

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.

Solver convergence issues posted on Github

See these issues:

  1. geoschem/geos-chem #66

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 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)

More about tolerances

Tao Zeng wrote:

By reducing RTOL from 0.2 to 0.05, you were able to run the model for longer time without errors.

I tried your method and found it works. But I am quite confused with the setting. To my understanding, we enlarge the tolerance to make it not so strict, it's like to open the door a little wider. But why does it work in the opposite way in the KPP case?

Claire Carouge wrote:

I am not sure of what is happening but I think I have an idea.

The errors occur because the system arrives to a state too far from the truth to be able to converge. By tightening the tolerances, you make sure the system stays closer to the truth at every time step. Then, the problematic time steps start the chemistry with a system closer to the true state, enabling the chemistry to converge even with a tighter tolerance.

Typically, if the first time step of chemistry couldn't converge, tightening the tolerances wouldn't work but loosening the tolerance would. Since here it is not the first time step, tightening the tolerances can work by keeping the system errors smaller before.

--Bob Y. 10:35, 11 March 2010 (EST)

Retrieved from "https://wiki.seas.harvard.edu/geos-chem/index.php?title=KPP_solvers_FAQ&oldid=49277"