EXP4 README FILE

 

*****************************************************************************

     	   EXP4 README FILE, VERSION 1.1

*****************************************************************************

  ----- Visit ChangeLog file for information on the current release -------

IMPORTANT
      Before going any further, please read and accept the terms in
      the file COPYING.


WHAT IT IS ALL ABOUT:

      EXP4 solves ordinary differential equations of the form

		      y' = f(y), y(t_0) = y_0

      numerically.

      This system is in autonomous form. We refer to t_0 as initial
      time and y_0 as initial value. This code appears to be
      particularly attractive to solve problems, where the dimension
      of the system is large and (mildly) stiff or oscillatory.

      The user has to specify the function f and provide a routine
      that computes matrix-vector products with the Jacobian A=df/dy.
      If A is available explicitly (as a matrix in any format) then
      the code includes a strategy that uses the same matrix A for
      different time steps.

      Theory, implementation issues and numerical examples can be
      found in:

        Marlis Hochbruck, Christian Lubich, Hubert Selhofer: 
        "Exponential Integrators for Large Systems of Differential 
        Equations", to appear in SIAM Journal of Scientific Computing. 
 
      To get the paper and the latest version of the code:
 
             https://na.uni-tuebingen.de/na/software.shtml
 

INSTALLATION:

    - gunzip exp4_c.tar.gz (or gzip -d exp4_c.tar.gz)
    - tar xvf exp4_c.tar
      This yields a directory exp4 containing all the files.
    - Make sure that you have LAPACK and BLAS libraries installed (we
      need the FORTRAN versions).
    - Change to the directory exp4/examples.
    - Try
        make AllExamples
      If this fails, check the instructions in Makefile (we NEED a
      standard ANSI C compiler, e.g. "gcc -ansi").


GETTING STARTED:

    - For the first-time use of EXP4 we recommend to try the following
      examples provided in the directory 'examples':
        laser_simple
      Your output should look like


#################################################################
Exp4 Example: The Laser   example, 257 - dimensional Problem
#################################################################

Simple integrator call!

Press return please ...
--------------------------------------------------------
        Exponential method of order 4(3,2) (W)
--------------------------------------------------------
t = 0.000000e+00, h=7.00e-03, errw=7.08e-03, err3=2.35e-05 Krylov:  2, 1, 1 (K)
t = 6.998497e-03, h=1.67e-02, errw=9.57e-02, err3=7.60e-04 Krylov:  2, 1, 1 (K)
t = 2.366263e-02, h=6.67e-02, errw=6.20e+00, err3=3.33e-01 Krylov:  3, 1, 1 (E)
t = 9.031916e-02, h=8.65e-02, errw=1.82e+01, err3=3.57e+00 Krylov: 20,11, 8 (E)
== STEP REJECTED == STEP REJECTED == STEP REJECTED ==
t = 9.031916e-02, h=5.09e-02, errw=3.15e+00, err3=3.03e-01 Krylov: 20, 8, 6 (K)
t = 1.412617e-01, h=5.09e-02, errw=4.80e+00, err3=5.96e-01 Krylov: 15, 6, 6 (E)
t = 1.922043e-01, h=4.35e-02, errw=5.09e+00, err3=5.36e-01 Krylov: 20,11, 6 (E)
t = 2.357080e-01, h=4.26e-02, errw=7.56e+00, err3=8.08e-01 Krylov: 20,11, 6 (E)
t = 2.783364e-01, h=3.52e-02, errw=6.16e+00, err3=5.60e-01 Krylov: 20,11, 6 (K)
t = 3.135456e-01, h=3.52e-02, errw=8.19e+00, err3=8.23e-01 Krylov: 20,11, 6 (E)
t = 3.487547e-01, h=2.97e-02, errw=6.36e+00, err3=5.68e-01 Krylov: 20,11, 6 (K)
t = 3.784991e-01, h=2.97e-02, errw=7.69e+00, err3=7.64e-01 Krylov: 20,11, 6 (E)
t = 4.082435e-01, h=2.65e-02, errw=6.54e+00, err3=6.21e-01 Krylov: 20,11, 6 (K)
 
 .......

t = 9.682954e-01, h=8.79e-03, errw=1.39e+01, err3=7.07e-01 Krylov: 15, 8, 6 (E)
t = 9.770891e-01, h=8.79e-03, errw=1.51e+01, err3=7.49e-01 Krylov: 15, 8, 6 (E)
t = 9.858769e-01, h=8.54e-03, errw=1.52e+01, err3=7.09e-01 Krylov: 15, 8, 6 (E)
t = 9.944128e-01, h=5.59e-03, errw=5.19e+00, err3=1.38e-01 Krylov: 11, 6, 2 (K)
t = 1.0000000000e+00

number of successful steps:                    53
number of rejected steps:                       1
number of fnc evaluations:                    162
number of jacobi evaluations:                   0
number of Krylov steps 1st stage:             863
number of Krylov steps reuse k stage:           0
number of Krylov steps 2nd stage:             494
number of Krylov steps 3rd stage:             307
number of all Krylov steps:                  1664
number of jacobian vector mult.:             1752
number of transp. jac. vector mult.:            0

CPU time:                               2.79 seconds
1e-06 <= Atol <= 1e-06, 0.001 <= Rtol <= 0.001

Total amount of allocated memory: 490.93 KBytes.


      Next you can try
        bruss2d_simple
      and should get an output like

 

#################################################################
Exp4 Example: The Brusselator example, 800 - dimensional Problem
#################################################################

Simple integrator call!

Press return please ...

--------------------------------------------------------
        Exponential method of order 4(3,2) (W)
--------------------------------------------------------
t = 0.000000e+00, h=1.49e-04, errw=4.23e-04, err3=1.01e-06 Krylov:  2, 1, 1 (K)
t = 1.488436e-04, h=3.54e-04, errw=2.26e-03, err3=2.29e-03 Krylov:  2, 1, 1 (K)
t = 5.032553e-04, h=1.42e-03, errw=5.27e-02, err3=3.50e-02 Krylov:  2, 1, 1 (E)
t = 1.920902e-03, h=3.90e-03, errw=2.53e-01, err3=1.01e-02 Krylov:  3, 1, 1 (E)
t = 5.821487e-03, h=1.63e-02, errw=3.12e+00, err3=2.88e-01 Krylov:  6, 2, 2 (E)
t = 2.208773e-02, h=2.22e-02, errw=2.57e+00, err3=1.86e-01 Krylov:  6, 3, 2 (E)
t = 4.426260e-02, h=3.49e-02, errw=3.74e+00, err3=2.44e-01 Krylov:  6, 3, 2 (E)
t = 7.919512e-02, h=5.03e-02, errw=3.91e+00, err3=2.15e-01 Krylov:  6, 3, 3 (E)
t = 1.295357e-01, h=7.56e-02, errw=6.57e+00, err3=2.78e-01 Krylov:  6, 3, 3 (E)
 
 .......
 
t = 9.734768e+00, h=7.79e-02, errw=1.93e+00, err3=1.64e-01 Krylov:  3, 1, 2 (E)
t = 9.812643e+00, h=1.28e-01, errw=5.46e+00, err3=3.58e-01 Krylov:  3, 2, 2 (E)
t = 9.940577e+00, h=5.94e-02, errw=5.21e-01, err3=1.12e-02 Krylov:  3, 1, 2 (E)
t = 1.0000000000e+01

number of successful steps:                    49
number of rejected steps:                       3
number of fnc evaluations:                    154
number of jacobi evaluations:                  47
number of Krylov steps 1st stage:             283
number of Krylov steps reuse k stage:           0
number of Krylov steps 2nd stage:             121
number of Krylov steps 3rd stage:             112
number of all Krylov steps:                   516
number of jacobian vector mult.:              609
number of transp. jac. vector mult.:            0

CPU time:                               0.43 seconds
1e-06 <= Atol <= 1e-06, 0.001 <= Rtol <= 0.001

Total amount of allocated memory: 594.734 KBytes.


 
      laser_simple is an example where only a routine for
      Jacobian-vector multiplication is provided.
      (The fft routines used are those from FFTPACK available from
      netlib which we included in this package for convenience; see
      the README file in the fftpack directory)
      bruss2d_simple is an example where a routine for the Jacobian
      itself (in sparse format) and a routine for matrix-vector
      multiplication with a matrix in this sparse format are provided. 

      Now take a look at the files laser_simple.c and bruss2d_simple.c
      to see how a simple version is implemented. 

      More advanced options are illustrated in the other examples.  


DOCUMENTATION:

      See exp4/exp4.h.


SOME FURTHER REMARKS ON THE EXP4 CODE:

      The Exp4(Ex) code is written modularly. This means that the main
      integrator is called with a minimal set of options.
     
      For example if you want to change the value of Atol, you should
      call the routine Exp4SetAtol before calling the Exp4(Ex) main
      integrator. Calls like this will change this option for ALL
      later calls of Exp4(Ex) (these options are static variables).

      A helpful file for using Exp4(Ex) is exp4.h. It contains the
      external declarations of all routines important for the user.
      It also contains the description of these routines.

      Read the exp4/Makefile for further options and information.


WHAT OUR MAKEFILES DO:

    - First the Makefile will enter the directory ftypes and make the
      file "ftypes.h". This file contains some typedef commands which
      are needed for calling f77 compiled routines from C (we have
      encountered some compatibility problems when using f2c.h due to
      inexact type definitions or sloppy installations). For further
      details see the ftypes/README file.
    - Next the static library exp4.a is compiled.
    - The exp4/Makefile contains __NO__ CFLAGS. You have to specify
      them in the command line of make. Therefore: To use EXP4 on your
      problem include the following line in your Makefile:
      "cd /path/to/exp4; $(MAKE) CC="$(CC)" CFLAGS="$(CFLAGS)" exp4.a",
      where "/path/to/exp4" is to be replaced by the actual path of
      EXP4.


PROBLEMS:

    - There might be unresolved symbols. They are caused by the use of
      F77 compiled LAPACK and BLAS routines. Try linking with f77 or
      add the F77 and I77 libraries to FLIBS in examples/Makefile (see
      the comment there).
 
    - We know about a malfunction in bundle with the LAPACK and BLAS
      library complib.sgimath on an SGI Indigo II with operating
      system version 6.2. Please compile and use your own LAPACK and
      BLAS library. (At the moment we suppose that the dgemm routine
      does not work correctly.)


For comments and questions feel free to send an e-mail to:

		       exp4 does-not-exist.na uni-tuebingen de


 

Comments and suggestions to www∂am.uni-duesseldorf.de.