1 | /* |
---|
2 | * ----------------------------------------------------------------- |
---|
3 | * Programmer(s): Daniel R. Reynolds @ SMU |
---|
4 | * Radu Serban @ LLNL |
---|
5 | * ----------------------------------------------------------------- |
---|
6 | * LLNS/SMU Copyright Start |
---|
7 | * Copyright (c) 2017, Southern Methodist University and |
---|
8 | * Lawrence Livermore National Security |
---|
9 | * |
---|
10 | * This work was performed under the auspices of the U.S. Department |
---|
11 | * of Energy by Southern Methodist University and Lawrence Livermore |
---|
12 | * National Laboratory under Contract DE-AC52-07NA27344. |
---|
13 | * Produced at Southern Methodist University and the Lawrence |
---|
14 | * Livermore National Laboratory. |
---|
15 | * |
---|
16 | * All rights reserved. |
---|
17 | * For details, see the LICENSE file. |
---|
18 | * LLNS/SMU Copyright End |
---|
19 | * ----------------------------------------------------------------- |
---|
20 | * This is the header file for the CVSBANDPRE module, which |
---|
21 | * provides a banded difference quotient Jacobian-based |
---|
22 | * preconditioner and solver routines for use with the CVSSPILS |
---|
23 | * iterative linear solver interface. |
---|
24 | * |
---|
25 | * Part I contains type definitions and function prototypes for using |
---|
26 | * CVSBANDPRE on forward problems (IVP integration and/or FSA) |
---|
27 | * |
---|
28 | * Part II contains type definitions and function prototypes for using |
---|
29 | * CVSBANDPRE on adjopint (backward) problems |
---|
30 | * ----------------------------------------------------------------- |
---|
31 | */ |
---|
32 | |
---|
33 | #ifndef _CVSBANDPRE_H |
---|
34 | #define _CVSBANDPRE_H |
---|
35 | |
---|
36 | #include <sundials/sundials_nvector.h> |
---|
37 | |
---|
38 | #ifdef __cplusplus /* wrapper to enable C++ usage */ |
---|
39 | extern "C" { |
---|
40 | #endif |
---|
41 | |
---|
42 | /*================================================================= |
---|
43 | PART I - forward problems |
---|
44 | =================================================================*/ |
---|
45 | |
---|
46 | /*----------------------------------------------------------------- |
---|
47 | SUMMARY |
---|
48 | |
---|
49 | These routines provide a band matrix preconditioner based on |
---|
50 | difference quotients of the ODE right-hand side function f. |
---|
51 | The user supplies parameters |
---|
52 | mu = upper half-bandwidth (number of super-diagonals) |
---|
53 | ml = lower half-bandwidth (number of sub-diagonals) |
---|
54 | The routines generate a band matrix of bandwidth ml + mu + 1 |
---|
55 | and use this to form a preconditioner for use with the Krylov |
---|
56 | linear solver through the CVSPILS interface. Although this |
---|
57 | matrix is intended to approximate the Jacobian df/dy, it may |
---|
58 | be a very crude approximation. The true Jacobian need not be |
---|
59 | banded, or its true bandwith may be larger than ml + mu + 1, |
---|
60 | as long as the banded approximation generated here is |
---|
61 | sufficiently accurate to speed convergence as a preconditioner. |
---|
62 | |
---|
63 | Usage: |
---|
64 | The following is a summary of the usage of this module. |
---|
65 | Details of the calls to CVodeCreate, CVodeInit, CVSp*, |
---|
66 | and CVode are available in the User Guide. |
---|
67 | To use these routines, the sequence of calls in the user |
---|
68 | main program should be as follows: |
---|
69 | |
---|
70 | #include <cvodes/cvodes_bandpre.h> |
---|
71 | #include <nvector_serial.h> (or openmp or pthreads) |
---|
72 | ... |
---|
73 | void *cvode_mem; |
---|
74 | ... |
---|
75 | Set y0 |
---|
76 | ... |
---|
77 | SUNLinearSolver LS = SUNSPBCGS(y0, pretype, maxl); |
---|
78 | -or- |
---|
79 | SUNLinearSolver LS = SUNSPFGMR(y0, pretype, maxl); |
---|
80 | -or- |
---|
81 | SUNLinearSolver LS = SUNSPGMR(y0, pretype, maxl); |
---|
82 | -or- |
---|
83 | SUNLinearSolver LS = SUNSPTFQMR(y0, pretype, maxl); |
---|
84 | -or- |
---|
85 | SUNLinearSolver LS = SUNPCG(y0, pretype, maxl); |
---|
86 | ... |
---|
87 | cvode_mem = CVodeCreate(...); |
---|
88 | flag = CVodeInit(...); |
---|
89 | ... |
---|
90 | flag = CVSpilsSetLinearSolver(cvode_mem, LS); |
---|
91 | ... |
---|
92 | flag = CVBandPrecInit(cvode_mem, N, mu, ml); |
---|
93 | ... |
---|
94 | flag = CVode(...); |
---|
95 | ... |
---|
96 | Free y0 |
---|
97 | ... |
---|
98 | CVodeFree(&cvode_mem); |
---|
99 | ... |
---|
100 | SUNLinSolFree(LS); |
---|
101 | ... |
---|
102 | |
---|
103 | Notes: |
---|
104 | (1) Include this file for the CVBandPrecData type definition. |
---|
105 | (2) In the CVBandPrecInit call, the arguments N is the |
---|
106 | problem dimension. |
---|
107 | (3) In the linear solver creation call, the user is free to |
---|
108 | specify the input pretype and the optional input maxl. |
---|
109 | -----------------------------------------------------------------*/ |
---|
110 | |
---|
111 | |
---|
112 | /*----------------------------------------------------------------- |
---|
113 | Function : CVBandPrecInit |
---|
114 | ----------------------------------------------------------------- |
---|
115 | CVBandPrecInit allocates and initializes the BANDPRE preconditioner |
---|
116 | module. This function must be called AFTER the CVSPILS linear |
---|
117 | solver interface has been created. |
---|
118 | |
---|
119 | The parameters of CVBandPrecInit are as follows: |
---|
120 | |
---|
121 | cvode_mem is the pointer to CVODE memory returned by CVodeCreate. |
---|
122 | |
---|
123 | N is the problem size. |
---|
124 | |
---|
125 | mu is the upper half bandwidth. |
---|
126 | |
---|
127 | ml is the lower half bandwidth. |
---|
128 | |
---|
129 | The return value of CVBandPrecInit is one of: |
---|
130 | CVSPILS_SUCCESS if no errors occurred |
---|
131 | CVSPILS_MEM_NULL if the integrator memory is NULL |
---|
132 | CVSPILS_LMEM_NULL if the linear solver memory is NULL |
---|
133 | CVSPILS_ILL_INPUT if an input has an illegal value |
---|
134 | CVSPILS_MEM_FAIL if a memory allocation request failed |
---|
135 | |
---|
136 | NOTE: The band preconditioner assumes a serial/OpenMP/Pthreads |
---|
137 | implementation of the NVECTOR package. Therefore, |
---|
138 | CVBandPrecInit will first test for a compatible N_Vector |
---|
139 | internal representation by checking for required functions. |
---|
140 | -----------------------------------------------------------------*/ |
---|
141 | SUNDIALS_EXPORT int CVBandPrecInit(void *cvode_mem, sunindextype N, |
---|
142 | sunindextype mu, sunindextype ml); |
---|
143 | |
---|
144 | /*----------------------------------------------------------------- |
---|
145 | Optional output functions : CVBandPrecGet* |
---|
146 | ----------------------------------------------------------------- |
---|
147 | CVBandPrecGetWorkSpace returns the real and integer work space used |
---|
148 | by CVBANDPRE. |
---|
149 | CVBandPrecGetNumRhsEvals returns the number of calls made from |
---|
150 | CVBANDPRE to the user's right-hand side |
---|
151 | routine f. |
---|
152 | |
---|
153 | The return value of CVBandPrecGet* is one of: |
---|
154 | CVSPILS_SUCCESS if no errors occurred |
---|
155 | CVSPILS_MEM_NULL if the integrator memory is NULL |
---|
156 | CVSPILS_LMEM_NULL if the linear solver memory is NULL |
---|
157 | CVSPILS_PMEM_NULL if the preconditioner memory is NULL |
---|
158 | -----------------------------------------------------------------*/ |
---|
159 | SUNDIALS_EXPORT int CVBandPrecGetWorkSpace(void *cvode_mem, |
---|
160 | long int *lenrwLS, |
---|
161 | long int *leniwLS); |
---|
162 | SUNDIALS_EXPORT int CVBandPrecGetNumRhsEvals(void *cvode_mem, |
---|
163 | long int *nfevalsBP); |
---|
164 | |
---|
165 | |
---|
166 | /*================================================================= |
---|
167 | PART II - backward problems |
---|
168 | =================================================================*/ |
---|
169 | |
---|
170 | /*----------------------------------------------------------------- |
---|
171 | Functions: CVBandPrecInitB |
---|
172 | ----------------------------------------------------------------- |
---|
173 | Interface functions for the CVBANDPRE preconditioner to be used |
---|
174 | on the backward phase. |
---|
175 | |
---|
176 | CVBandPrecInitB interfaces to the CVBANDPRE preconditioner |
---|
177 | for the backward integration. |
---|
178 | The 'which' argument is the int returned by CVodeCreateB. |
---|
179 | -----------------------------------------------------------------*/ |
---|
180 | SUNDIALS_EXPORT int CVBandPrecInitB(void *cvode_mem, int which, |
---|
181 | sunindextype nB, sunindextype muB, |
---|
182 | sunindextype mlB); |
---|
183 | |
---|
184 | #ifdef __cplusplus |
---|
185 | } |
---|
186 | #endif |
---|
187 | |
---|
188 | #endif |
---|