Frequently Asked Questions
Contents
- Installation
- I got the tarball. What do I do next?
- What configure flags do I really need?
- Can I use a C++ compiler to build SUNDIALS?
- How do I build SUNDIALS without using the configure script?
- How do I install SUNDIALS under Windows?
- How can I generate shared libraries under cygwin?
- Should I build 32-bit or 64-bit SUNDIALS libraries?
- Everything installed fine! How do I link the SUNDIALS libraries to my own application?
- CVODE / CVODES
- How do I choose tolerances?
- How do I choose what linear solver to use for the stiff case?
- How do I handle a data-defined function within the RHS function?
- How do I control unphysical negative values?
- How do I treat discontinuities in the RHS function?
- When is it advantegeous to supply my own EwtFn function?
- How do I switch on/off forward sensitivity computations in CVODES?
- What is the role of plist in CVODES?
- What is the role of pbar in CVODES?
- What is pure quadrature integration?
- IDA
- How do I choose tolerances in IDA?
- How do I choose what linear solver to use?
- How do I handle a data-defined function within the residual function?
- How do I control unphysical negative values in IDA?
- How do I treat discontinuities in the residual function in IDA?
- When is it advantegeous to supply my own EwtFn function?
- KINSOL
- Miscellaneous
Installation
I got the tarball. What do I do next?
Let's assume you downloaded sundials-x.y.z.tar.gz.
First, you'll have to uncompress and unpack it:
Next, you need to configure and build the SUNDIALS libraries. You can get some information on how to do this here, but more details are available in the user guides (e.g. sundials/cvode/doc/cv_guide.pdf).
If your system does not support configure scripts, see How do I build SUNDIALS without using the configure script?
Otherwise, the first thing to decide now is where you'd like to install the SUNDIALS libraries and header files. We will call this directory instdir. You will specify this through the --prefix option to configure (if --prefix is not specified, instdir defaults to usr/local.). WARNING: In no circumstances, should you use the same instdir as the source directory srcdir, as this would result in errors when attempting to install the exported header files.
Next, from within srcdir, you configure, build, and install SUNDIALS:
% tar -xzf sundials-x.y.z.tarThis will create a directory sundials-x.y.z, which we will call srcdir. (Note that if you only downloaded an individual solver tarball, call it solver-x.y.z.tar.gz, uncompressing and unpacking it will result in the directory solver-x.y.z.)
Next, you need to configure and build the SUNDIALS libraries. You can get some information on how to do this here, but more details are available in the user guides (e.g. sundials/cvode/doc/cv_guide.pdf).
If your system does not support configure scripts, see How do I build SUNDIALS without using the configure script?
Otherwise, the first thing to decide now is where you'd like to install the SUNDIALS libraries and header files. We will call this directory instdir. You will specify this through the --prefix option to configure (if --prefix is not specified, instdir defaults to usr/local.). WARNING: In no circumstances, should you use the same instdir as the source directory srcdir, as this would result in errors when attempting to install the exported header files.
Next, from within srcdir, you configure, build, and install SUNDIALS:
% cd srcdir % ./configure --prefix=instdir <configure-options> % make % make installIf everything went fine, the SUNDIALS libraries were installed in instdir/lib, the exported header files were installed in various subdirectories of instdir/include, and the sundials-config executable script was installed in instdir/bin. If compilation of the SUNDIALS examples was enabled through the --enable-examples option to configure then these were installed in various subdirectores of exinstdir, where exinstsdir was specified through the --with-examples-instdir option (default instdir/examples). Similarly, if compilation of the Matlab toolbox sundialsTB was enabled at configuration time (--enable-sundialsTB), then it was installed in stbinstdir/sundialsTB, where stbinstdir was specified with --with-sundialsTB-instdir (default $MATLAB/toolbox).
What configure flags do I really need?
That depends a lot on how your system is configured. If all compilers, libraries, and system
header files are in the usual places, configuring SUNDIALS can be as simple as:
% ./configure % make % make installIn certain circumstances, more sophisticated configure lines may be needed, especially when building SUNDIALS with MPI support and/or the Fortran-C interfaces. For example, to build SUNDIALS using gcc as the serial C compiler, g77 as the serial Fortran compiler, using the MPI compiler scripts mpicc and mpif77 from a particular MPICH distribution, and using the additional compiler flag -g3, you would use:
% configure CC=gcc F77=g77 --with-cflags=-g3 --with-fflags=-g3 \ --with-mpicc=/usr/apps/mpich/1.2.4/bin/mpicc \ --with-mpif77=/usr/apps/mpich/1.2.4/bin/mpif77
Can I use a C++ compiler to build SUNDIALS?
Yes. However, if building SUNDIALS using a C++ compiler and with parallel support,
you must take care not to include MPI C++ bindings. This can be done by
specifying an implementation-dependent MPI flag using --with-mpi-flags:
♦ for MPICH, use --with-mpi-flags=-DMPICH_SKIP_MPICXX
♦ for LAM MPI, use --with-mpi-flags=-DLAM_BUILDING
On the other hand, in order to resolve all necessary symbols while linking the parallel Fortran libraries, you must either use the MPI wrapper using the C++ compiler (i.e. specify --with-mpif77=mpiCC), or else add the stdc++ library (i.e. specify --with-libs=-lstdc++).
Note that, if you want to use an MPI script, you must specify, through --with-mpicc, the wrapper using the C++ compiler (mpiCC or mpic++, depending on your MPI distribution). If a C++ compiler is specified and --with-mpicc is not specified, the SUNDIALS configure script will automaticall select the correct MPI script.
♦ for MPICH, use --with-mpi-flags=-DMPICH_SKIP_MPICXX
♦ for LAM MPI, use --with-mpi-flags=-DLAM_BUILDING
On the other hand, in order to resolve all necessary symbols while linking the parallel Fortran libraries, you must either use the MPI wrapper using the C++ compiler (i.e. specify --with-mpif77=mpiCC), or else add the stdc++ library (i.e. specify --with-libs=-lstdc++).
Note that, if you want to use an MPI script, you must specify, through --with-mpicc, the wrapper using the C++ compiler (mpiCC or mpic++, depending on your MPI distribution). If a C++ compiler is specified and --with-mpicc is not specified, the SUNDIALS configure script will automaticall select the correct MPI script.
How do I install SUNDIALS without using the configure script?
Complete details on bulding SUNDIALS without using the default build system are provided
in the "Building SUNDIALS without the configure script" section of the installation
chapter in any of the SUNDIALS user guides. This type of installation requires manually
creating the sundials_config.h header file
[ view | download ]
How do I install SUNDIALS under Windows?
The easiest way of obtaining Windows libraries for the SUNDIALS solvers is probably
to use cygwin (www.cygwin.com),
in which case the installation procedure is the same as for any other *NIX system.
Several of our users have reported successfuly building the SUNDIALS libraries using various IDEs (Borland C++, Visual C++, etc.). For more details, browse also the sundials-users mailing list.
Several of our users have reported successfuly building the SUNDIALS libraries using various IDEs (Borland C++, Visual C++, etc.). For more details, browse also the sundials-users mailing list.
How can I generate shared libraries under cygwin?
In order to create shared libraries (DLLs) under cygwin, you must regenerate the
configure script using cygwin's autotools and use the -no-undefined
option to libtool.
-
Remove, if they exist, the aclocal.m4 file and autom4te.cache
directory:
% rm -rf aclocal.m4 autom4te.cache
-
Regenerate the configure script:
% aclocal % autoconf % autoheader
-
Configure SUNDIALS, enabling creation of shared libraries and using the required
flag:
% ./configure --enable-shared --with-ldflags=-no-undefined
Should I build 32-bit or 64-bit SUNDIALS libraries?
Typically, the "bitness" of a CPU refers to the size of the linear address space a process
can address (e.g., an IA-32 processor can address up to 4GB). Consequently, if your program
does not require more than 4GB of memory, then there is probably no benefit to building a
64-bit library.
People are also often confused by the nomenclature, but the "bitness" of a CPU has nothing to do with the accuracy of floating-point computations or the size of floating-point numeric data types. Regardless of the "bitness" of the processor, real numbers are stored in the IEEE Standard 754 floating-point format. Therefore, building a 64-bit library will not increase the accuracy of your numerical results.
People are also often confused by the nomenclature, but the "bitness" of a CPU has nothing to do with the accuracy of floating-point computations or the size of floating-point numeric data types. Regardless of the "bitness" of the processor, real numbers are stored in the IEEE Standard 754 floating-point format. Therefore, building a 64-bit library will not increase the accuracy of your numerical results.
Everything installed fine! How do I link the SUNDIALS libraries to my own application?
The easiest way to determine the preprocessor and linker flags required to link the SUNDIALS libraries to
a user application is to invoke, from within the Makefile, the executable script sundials-config
available in instdir/bin. Its usage is as follows:
Usage: sundials-config -m cvode|cvodes|ida|kinsol -t s|p -l c|f [-s libs|cppflags -hv] Requires: standard GNU commands Options: -m cvode|cvodes|ida|kinsol SUNDIALS module -t s|p use serial or parallel vectors -l c|f use C or Fortran -s libs|cppflags show linking flags or C preprocessor flags. (show both if option not given.) -h usage and options (this help) -v view this script Notes: '-l f' is not valid for '-m cvodes' '-s cppflags' returns an empty string for '-l f'With this, a sample Makefile to compile a CVODE application witten in C and using the serial NVECTOR module could look as follows:
SHELL = /bin/sh CC = gcc CFLAGS = -g -O CPPFLAGS = LDFLAGS = SUN_DISTRO = /home/radu/CODES/sundials-2.3.0-mpich1_gcc MY_APPS = app1 app2 all: @sun_cppflags=`eval "${SUN_DISTRO}/bin/sundials-config -m cvode -t s -l c -s cppflags"`; \ sun_ldflags=`eval "${SUN_DISTRO}/bin/sundials-config -m cvode -t s -l c -s libs"`; \ for i in ${MY_APPS} ; do \ echo "--- Making $${i} ---" ; \ eval "make SUN_CPPFLAGS='$${sun_cppflags}' SUN_LDFLAGS='$${sun_ldflags}' $${i}"; \ done app1: app1.c ${CC} ${CPPFLAGS} ${SUN_CPPFLAGS} ${CFLAGS} -c app1.c ${CC} -o app1 app1.o ${CFLAGS} ${LDFLAGS} ${SUN_LDFLAGS} app2: app2.c ${CC} ${CPPFLAGS} ${SUN_CPPFLAGS} ${CFLAGS} -DMY_PREPROC_DIR -c app2.c ${CC} -o app2 app2.o ${CFLAGS} ${LDFLAGS} ${SUN_LDFLAGS} clean: rm -f *.o rm -f ${MY_APPS}