File: INSTALL_NOTES

package info (click to toggle)
sundials 2.2.0-3
  • links: PTS
  • area: main
  • in suites: etch, etch-m68k, lenny
  • size: 29,116 kB
  • ctags: 9,381
  • sloc: ansic: 56,502; sh: 6,558; fortran: 2,794; makefile: 1,685
file content (385 lines) | stat: -rw-r--r-- 13,915 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
           SUNDIALS Installation Instructions
              Release 2.2.0, March 2006  

These are generic installation instructions. For complete installation 
instructions, consult the user guide for any of the SUNDIALS solvers.

Contents:
1. Basic Installation
2. Installation Names
3. Compilers and Options
  3.1. General options
  3.2. Options for Fortran support
  3.3. Options for MPI support
  3.4. Options for library support
  3.5. Environment variables
4. Configuration examples

1. Basic Installation
=====================

The simplest way to build SUNDIALS is to use the `configure' shell script
which attempts to guess correct values for various system-dependent
variables and features and find the directories where various system
headers and libraries are kept.  It then creates a `Makefile' in each
subdirectory. Running the `make' utility then builds the package for
your system.

Here's the procedure to build SUNDIALS using `configure' on systems which
are supported by it.  If this simplified procedure fails, or if you
are using a platform such as MS-Windows, where `configure' script
doesn't work, you might need to use various non-default options, and
maybe perform some of the steps manually.

  1. `cd' to the sundials directory (the directory where this file resides)
     and type `./configure' to configure the package for your system.  
     If you're using `csh' on an old version of System V, you might need to 
     type `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes a while.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile all existing modules.

  3. Type `make install' to install the libraries and header files.
 
  4. To compile the example programs for all the existing modules, type
     'make examples'.

  5. You can remove the libraries and object files from the source code 
     directories by typing `make clean'.

2. Installation Names
=====================

By default, 'make install' will install the SUNDIALS libraries in 
the subdirectory 'lib' and the header files in the sudirectory 'include'
of the directory from where 'configure' was invoked.
You can specify a different installation prefix by giving 'configure' 
the option '--prefix=PREFIX'.

You can specify separate installation prefixes for architecture-specific
files and architecture-independent files. If you give 'configure' the
option '--exec-prefix=EPREFIX', the package will use EPATH as the prefix
for installing libraries. The header files will still use the regular 
prefix.

You can also specify the directory where libraries should be installed
by giving 'configure' the option '--libdir=DIR'. Similarly, invoking
'configure --includedir=DIR' will install header files in DIR.

Run `configure --help' for a list of the directories you can set and 
what kinds of files go in them.

The SUNDIALS libraries and header files are summarized below:

SHARED module
  header files: sundials/sundials types.h     sundials/sundials math.h
                sundials/sundials config.h    sundias/sundials nvector.h
                sundials/sunials smalldense.h sundials/sundials dense.h
                sundials/sundials iterative.h sundials/sundials band.h
                sundials/sundials spbcgs.h    sundials/sundials sptfqmr.h
                sundials/sundials spgmr.h


NVECTOR_SERIAL module
  libraries:    libsundials_nvecserial.{a,so} libsundials_fnvecserial.a
  header files: nvector_serial.h


NVECTOR_PARALLEL module
  libraries:    libsundials_nvecparallel.{a,so} libsundials_fnvecparallel.a
  header files: nvector_parallel.h


CVODE module
  libraries:    libsundials_cvode.{a,so} libsundials_fcvode.a
  header files: cvode.h
                cvode/cvode_dense.h    cvode/cvode_band.h
                cvode/cvode_diag.h     cvode/cvode_spils.h
                cvode/cvode_bandpre.h  cvode/cvode_bbdpre.h
                cvode/cvode_spgmr.h    cvode/cvode_spbcgs.h
                cvode/cvode_sptfqmr.h  cvode/cvode_impl.h


CVODES module
  library:      libsundials_cvodes.{a,so}
  header files: cvodes.h cvodea.h
                cvodes/cvodes_dense.h     cvodes/cvodes_band.h
                cvodes/cvodes_diag.h      cvodes/cvodes_spils.h
                cvodes/cvodes_bandpre.h   cvodes/cvodes_bbdpre.h
                cvodes/cvodes_spgmr.h     cvodes/cvodes_spbcgs.h
                cvodes/cvodes_sptfqmr.h   cvodes/cvodes_impl.h
                cvodes/cvodea_impl.h

IDA module
  library:      libsundials_ida.{a,so}
  header files: ida.h
                ida/ida_dense.h    ida/ida_band.h
                ida/ida_spils.h    ida/ida_spgmr.h
                ida/ida_spbcgs.h   ida/ida_sptfqmr.h
                ida/ida_bbdpre.h   ida/ida_impl.h


KINSOL module
  libraries:    libsundials_kinsol.{a,so} libsundials_fkinsol.a
  header files: kinsol.h
                kinsol/kinsol_dense.h   kinsol/kinsol_band.h
                kinsol/kinsol_spils.h   kinsol/kinsol_spgmr.h
                kinsol/kinsol_spbcgs.h  kinsol/kinsol_sptfqmr.h
                kinsol/kinsol_bbdpre.h  kinsol/kinsol_impl.h



3. Compilers and Options
========================

Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  Run `./configure --help'
for details on some of the pertinent environment variables.

You can give `configure' initial values for these variables by setting 
them in the environment.  You can do that on the command line like this:

     ./configure CC=gcc CFLAGS=-O2 F77=g77 FFLAGS=-O

Here is a detailed description of the configure options that are
pertinent to SUNDIALS. In what follows, 'build_tree' is the directory
from where 'configure' was invoked.

3.1. General options
--------------------

--help
-h

  print a summary of the options to `configure', and exit.

--quiet
--silent
-q

  do not print messages saying which checks are being made.  To
  suppress all normal output, redirect it to `/dev/null' (any error
  messages will still be shown).


--prefix=PREFIX

  Location for architecture-independent files.
  Default: PREFIX=build_tree
  
--includedir=DIR

  Alternate location for header files.
  Default: DIR=PREFIX/include
  
--libdir=DIR

  Alternate location for libraries.
  Default: DIR=PREFIX/lib

--disable-examples

  All available example programs are automatically built unless this option is
  used. The example executables are stored under the following subdirectories
  of the associated solver: 
  
  
   build_tree/ solver/examples_ser :      serial C examples
   build_tree/solver/examples_par :       parallel C examples
   build_tree/solver/fcmix/examples_ser : serial F77 examples
   build_tree/solver/fcmix/examples_par : parallel F77 examples
  
  
  Note: Some of these subdirectories may not exist depending upon the
  solver and/or the configuration options used.
  
--disable-solver

  Although each existing solver module is built by default, support for a
  given solver can be explicitly disabled using this option. 
  The valid values for solver are: cvode, cvodes, 
  ida, and kinsol.
  
--with-cppflags=ARG

  Specify additional C preprocessor flags 
  (e.g., ARG=-I<include_dir> if necessary header files are located in nonstandard locations).

--with-cflags=ARG

  Specify additional C compilation flags.

--with-ldflags=ARG

  Specify additional linker flags 
  (e.g., ARG=-L<lib_dir> if required libraries are located in nonstandard locations).

--with-libs=ARG

  Specify additional libraries to be used 
  (e.g., ARG=-l<foo> to link with the library named libfoo.a or libfoo.so).

--with-precision=ARG

  By default, sundials will define a real number (internally referred to as
  realtype) to be a double-precision floating-point numeric data type (double
  C-type); however, this option may be used to build sundials with realtype
  alternatively defined as a single-precision floating-point numeric data type
  (float C-type) if ARG=single, or as a long double C-type if ARG=extended.

  Default: ARG=double

3.2. Options for Fortran support
--------------------------------

--disable-f77

  Using this option will disable all F77 support. The fcvode, fkinsol and
  fnvector modules will not be built regardless of availability.

--with-fflags=ARG

  Specify additional F77 compilation flags.


The configuration script will attempt to automatically determine the
function name mangling scheme required by the specified F77 compiler, but the
following two options may be used to override the default behavior.

--with-f77underscore=ARG

  This option pertains to the fkinsol, fcvode and fnvector F/C interface 
  modules and is used to specify the number of underscores to append to 
  function names so F77 routines can properly link with the associated
  sundials libraries. Valid values for ARG are: none, one, and two.

  Default: ARG=one

--with-f77case=ARG

  Use this option to specify whether the external names of the fkinsol,
  fcvode and fnvector F/C interface functions should be lowercase
  or uppercase so F77 routines can properly link with the associated sundials
  libraries. Valid values for ARG are: lower and upper.

  Default: ARG=lower

3.3. Options for MPI support
----------------------------

The following configuration options are only applicable to the parallel sundials packages:

  
--disable-mpi

  Using this option will completely disable MPI support.

--with-mpicc=ARG
--with-mpif77=ARG

  By default, the configuration utility script will use the MPI compiler
  scripts named mpicc and mpif77 to compile the parallelized
  sundials subroutines; however, for reasons of compatibility, different
  executable names may be specified via the above options. Also, ARG=no
  can be used to disable the use of MPI compiler scripts, thus causing
  the serial C and F compilers to be used to compile the parallelized
  sundials functions and examples.

--with-mpi-root=MPIDIR

  This option may be used to specify which MPI implementation should be used.
  The sundials configuration script will automatically check under the
  subdirectories MPIDIR/include and MPIDIR/lib for the necessary
  header files and libraries. The subdirectory MPIDIR/bin will also be
  searched for the C and F MPI compiler scripts, unless the user uses
  --with-mpicc=no or --with-mpif77=no.

--with-mpi-incdir=INCDIR
--with-mpi-libdir=LIBDIR
--with-mpi-libs=LIBS

  These options may be used if the user would prefer not to use a preexisting
  MPI compiler script, but instead would rather use a serial complier and
  provide the flags necessary to compile the MPI-aware subroutines in
  sundials.

  Often an MPI implementation will have unique library names and so it may
  be necessary to specify the appropriate libraries to use (e.g., LIBS=-lmpich).

  Default: INCDIR=MPIDIR/include, LIBDIR=MPIDIR/lib and LIBS=-lmpi

--with-mpi-flags=ARG

  Specify additional MPI-specific flags.

3.4. Options for library support
--------------------------------

By default, only static libraries are built, but the following option
may be used to build shared libraries on supported platforms.

--enable-shared

  Using this particular option will result in both static and shared versions
  of the available sundials libraries being built if the systsupports
  shared libraries. To build only shared libraries also specify --disable-static.

  Note: The fcvode and fkinsol libraries can only be built as static
  libraries because they contain references to externally defined symbols, namely
  user-supplied F77 subroutines.  Although the F77 interfaces to the serial and
  parallel implementations of the supplied nvector module do not contain any
  unresolvable external symbols, the libraries are still built as static libraries
  for the purpose of consistency.

3.5. Environment variables
--------------------------

The following environment variables can be locally (re)defined for use during the 
configuration of sundials. See the next section for illustrations of these.

CC

F77

  Since the configuration script uses the first C and F77 compilers found in
  the current executable search path, then each relevant shell variable (CC
  and F77) must be locally (re)defined in order to use a different compiler. 
  For example, to use xcc (executable name of chosen compiler) as the C
  language compiler, use CC=xcc in the configure step.

CFLAGS

FFLAGS

  Use these environment variables to override the default C and F77 compilation flags.

4. Configuration examples
=========================

The following examples are meant to help demonstrate proper usage of the configure options:


% 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


The above example builds sundials using gcc as the serial C compiler, g77 as the serial F77
compiler, mpicc as the parallel C compiler, mpif77 as the parallel F77 compiler, 
and appends the -g3 compilaton flag to the list of default flags.

% configure CC=gcc --disable-examples --with-mpicc=no \
            --with-mpi-root=/usr/apps/mpich/1.2.4 \
            --with-mpi-libs=-lmpich

This example again builds sundials using gcc as the serial C compiler, but the 
--with-mpicc=no option explicitly disables the use of the corresponding MPI compiler script. 
In addition, since the --with-mpi-root option is given, the compilation flags
-I/usr/apps/mpich/1.2.4/include and -L/usr/apps/mpich/1.2.4/lib are passed to gcc when 
compiling the MPI-enabled functions. The --disable-examples option disables the examples
(which means a Fortran compiler is not required). The --with-mpi-libs option is still needed
so that the configure script can check if gcc can link with the appropriate MPI library as
-lmpi is the internal default.