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
|
/*
* -----------------------------------------------------------------
* Programmer(s): Daniel R. Reynolds @ SMU
* Alan C. Hindmarsh and Radu Serban @ LLNL
* -----------------------------------------------------------------
* LLNS/SMU Copyright Start
* Copyright (c) 2017, Southern Methodist University and
* Lawrence Livermore National Security
*
* This work was performed under the auspices of the U.S. Department
* of Energy by Southern Methodist University and Lawrence Livermore
* National Laboratory under Contract DE-AC52-07NA27344.
* Produced at Southern Methodist University and the Lawrence
* Livermore National Laboratory.
*
* All rights reserved.
* For details, see the LICENSE file.
* LLNS/SMU Copyright End
* -----------------------------------------------------------------
* This is the header file for the CVBANDPRE module, which
* provides a banded difference quotient Jacobian-based
* preconditioner and solver routines for use with the CVSPILS
* interface.
* -----------------------------------------------------------------
*/
/*-----------------------------------------------------------------
SUMMARY
These routines provide a band matrix preconditioner based on
difference quotients of the ODE right-hand side function f.
The user supplies parameters
mu = upper half-bandwidth (number of super-diagonals)
ml = lower half-bandwidth (number of sub-diagonals)
The routines generate a band matrix of bandwidth ml + mu + 1
and use this to form a preconditioner for use with the Krylov
linear solver through the CVSPILS interface. Although this
matrix is intended to approximate the Jacobian df/dy, it may
be a very crude approximation. The true Jacobian need not be
banded, or its true bandwith may be larger than ml + mu + 1,
as long as the banded approximation generated here is
sufficiently accurate to speed convergence as a preconditioner.
Usage:
The following is a summary of the usage of this module.
Details of the calls to CVodeCreate, CVodeInit, CVSp*,
and CVode are available in the User Guide.
To use these routines, the sequence of calls in the user
main program should be as follows:
#include <cvode/cvode_bandpre.h>
#include <nvector_serial.h> (or openmp or pthreads)
...
void *cvode_mem;
...
Set y0
...
SUNLinearSolver LS = SUNSPBCGS(y0, pretype, maxl);
-or-
SUNLinearSolver LS = SUNSPFGMR(y0, pretype, maxl);
-or-
SUNLinearSolver LS = SUNSPGMR(y0, pretype, maxl);
-or-
SUNLinearSolver LS = SUNSPTFQMR(y0, pretype, maxl);
-or-
SUNLinearSolver LS = SUNPCG(y0, pretype, maxl);
...
cvode_mem = CVodeCreate(...);
flag = CVodeInit(...);
...
flag = CVSpilsSetLinearSolver(cvode_mem, LS);
...
flag = CVBandPrecInit(cvode_mem, N, mu, ml);
...
flag = CVode(...);
...
Free y0
...
CVodeFree(&cvode_mem);
...
SUNLinSolFree(LS);
...
Notes:
(1) Include this file for the CVBandPrecData type definition.
(2) In the CVBandPrecInit call, the argument N is the
problem dimension.
(3) In the linear solver creation call, the user is free to
specify the input pretype and the optional input maxl.
-----------------------------------------------------------------*/
#ifndef _CVBANDPRE_H
#define _CVBANDPRE_H
#include <sundials/sundials_nvector.h>
#ifdef __cplusplus /* wrapper to enable C++ usage */
extern "C" {
#endif
/*-----------------------------------------------------------------
Function : CVBandPrecInit
-----------------------------------------------------------------
CVBandPrecInit allocates and initializes the BANDPRE preconditioner
module. This function must be called AFTER the CVSPILS linear
solver interface has been created.
The parameters of CVBandPrecInit are as follows:
cvode_mem is the pointer to CVODE memory returned by CVodeCreate.
N is the problem size.
mu is the upper half bandwidth.
ml is the lower half bandwidth.
The return value of CVBandPrecInit is one of:
CVSPILS_SUCCESS if no errors occurred
CVSPILS_MEM_NULL if the integrator memory is NULL
CVSPILS_LMEM_NULL if the linear solver memory is NULL
CVSPILS_ILL_INPUT if an input has an illegal value
CVSPILS_MEM_FAIL if a memory allocation request failed
NOTE: The band preconditioner assumes a serial/OpenMP/Pthreads
implementation of the NVECTOR package. Therefore,
CVBandPrecInit will first test for a compatible N_Vector
internal representation by checking for required functions.
-----------------------------------------------------------------*/
SUNDIALS_EXPORT int CVBandPrecInit(void *cvode_mem, sunindextype N,
sunindextype mu, sunindextype ml);
/*-----------------------------------------------------------------
Optional output functions : CVBandPrecGet*
-----------------------------------------------------------------
CVBandPrecGetWorkSpace returns the real and integer work space used
by CVBANDPRE.
CVBandPrecGetNumRhsEvals returns the number of calls made from
CVBANDPRE to the user's right-hand side
routine f.
The return value of CVBandPrecGet* is one of:
CVSPILS_SUCCESS if no errors occurred
CVSPILS_MEM_NULL if the integrator memory is NULL
CVSPILS_LMEM_NULL if the linear solver memory is NULL
CVSPILS_PMEM_NULL if the preconditioner memory is NULL
-----------------------------------------------------------------*/
SUNDIALS_EXPORT int CVBandPrecGetWorkSpace(void *cvode_mem,
long int *lenrwLS,
long int *leniwLS);
SUNDIALS_EXPORT int CVBandPrecGetNumRhsEvals(void *cvode_mem,
long int *nfevalsBP);
#ifdef __cplusplus
}
#endif
#endif
|
