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:
http://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.