***************************************************************************** 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@na.uni-tuebingen.de

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