/usr/include/kinsol/kinsol_spils.h is in libsundials-serial-dev 2.5.0-3ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | /*
* -----------------------------------------------------------------
* $Revision: 1.7 $
* $Date: 2010/12/01 22:16:17 $
* -----------------------------------------------------------------
* Programmer(s): Scott Cohen, Alan Hindmarsh, Radu Serban, and
* Aaron Collier @ LLNL
* -----------------------------------------------------------------
* Copyright (c) 2002, The Regents of the University of California.
* Produced at the Lawrence Livermore National Laboratory.
* All rights reserved.
* For details, see the LICENSE file.
* -----------------------------------------------------------------
* This is the common header file for the Scaled Preconditioned
* Iterative Linear Solvers in KINSOL.
* -----------------------------------------------------------------
*/
#ifndef _KINSPILS_H
#define _KINSPILS_H
#ifdef __cplusplus /* wrapper to enable C++ usage */
extern "C" {
#endif
#include <sundials/sundials_iterative.h>
#include <sundials/sundials_nvector.h>
/*
* -----------------------------------------------------------------
* KINSPILS return values
* -----------------------------------------------------------------
*/
#define KINSPILS_SUCCESS 0
#define KINSPILS_MEM_NULL -1
#define KINSPILS_LMEM_NULL -2
#define KINSPILS_ILL_INPUT -3
#define KINSPILS_MEM_FAIL -4
#define KINSPILS_PMEM_NULL -5
/*
* -----------------------------------------------------------------
* KINSPILS solver constant
* -----------------------------------------------------------------
* KINSPILS_MAXL : default maximum dimension of Krylov subspace
* -----------------------------------------------------------------
*/
#define KINSPILS_MAXL 10
/*
* -----------------------------------------------------------------
* Type : KINSpilsPrecSetupFn
* -----------------------------------------------------------------
* The user-supplied preconditioner setup subroutine should
* compute the right-preconditioner matrix P (stored in memory
* block referenced by P_data pointer) used to form the
* scaled preconditioned linear system:
*
* (Df*J(uu)*(P^-1)*(Du^-1)) * (Du*P*x) = Df*(-F(uu))
*
* where Du and Df denote the diagonal scaling matrices whose
* diagonal elements are stored in the vectors uscale and
* fscale, repsectively.
*
* The preconditioner setup routine (referenced by iterative linear
* solver modules via pset (type KINSpilsPrecSetupFn)) will not be
* called prior to every call made to the psolve function, but will
* instead be called only as often as necessary to achieve convergence
* of the Newton iteration.
*
* Note: If the psolve routine requires no preparation, then a
* preconditioner setup function need not be given.
*
* uu current iterate (unscaled) [input]
*
* uscale vector (type N_Vector) containing diagonal elements
* of scaling matrix for vector uu [input]
*
* fval vector (type N_Vector) containing result of nonliear
* system function evaluated at current iterate:
* fval = F(uu) [input]
*
* fscale vector (type N_Vector) containing diagonal elements
* of scaling matrix for fval [input]
*
* user_data pointer to user-allocated data memory block
*
* vtemp1/vtemp2 available scratch vectors (temporary storage)
*
* If successful, the function should return 0 (zero). If an error
* occurs, then the routine should return a non-zero integer value.
* -----------------------------------------------------------------
*/
typedef int (*KINSpilsPrecSetupFn)(N_Vector uu, N_Vector uscale,
N_Vector fval, N_Vector fscale,
void *user_data, N_Vector vtemp1,
N_Vector vtemp2);
/*
* -----------------------------------------------------------------
* Type : KINSpilsPrecSolveFn
* -----------------------------------------------------------------
* The user-supplied preconditioner solve subroutine (referenced
* by iterative linear solver modules via psolve (type
* KINSpilsPrecSolveFn)) should solve a (scaled) preconditioned
* linear system of the generic form P*z = r, where P denotes the
* right-preconditioner matrix computed by the pset routine.
*
* uu current iterate (unscaled) [input]
*
* uscale vector (type N_Vector) containing diagonal elements
* of scaling matrix for vector uu [input]
*
* fval vector (type N_Vector) containing result of nonliear
* system function evaluated at current iterate:
* fval = F(uu) [input]
*
* fscale vector (type N_Vector) containing diagonal elements
* of scaling matrix for fval [input]
*
* vv vector initially set to the right-hand side vector r, but
* which upon return contains a solution of the linear system
* P*z = r [input/output]
*
* user_data pointer to user-allocated data memory block
*
* vtemp available scratch vector (volatile storage)
*
* If successful, the function should return 0 (zero). If a
* recoverable error occurs, then the subroutine should return
* a positive integer value (in this case, KINSOL attempts to
* correct by calling the preconditioner setup function if the
* preconditioner information is out of date). If an unrecoverable
* error occurs, then the preconditioner solve function should return
* a negative integer value.
* -----------------------------------------------------------------
*/
typedef int (*KINSpilsPrecSolveFn)(N_Vector uu, N_Vector uscale,
N_Vector fval, N_Vector fscale,
N_Vector vv, void *user_data,
N_Vector vtemp);
/*
* -----------------------------------------------------------------
* Type : KINSpilsJacTimesVecFn
* -----------------------------------------------------------------
* The (optional) user-supplied matrix-vector product subroutine
* (referenced internally via jtimes (type KINSpilsJacTimesVecFn))
* is used to compute Jv = J(uu)*v (system Jacobian applied to a
* given vector). If a user-defined routine is not given, then the
* private routine is used.
*
* v unscaled variant of vector to be multiplied by J(uu) [input]
*
* Jv vector containing result of matrix-vector product J(uu)*v
* [output]
*
* uu current iterate (unscaled) [input]
*
* new_uu flag (reset by user) indicating if the iterate uu
* has been updated in the interim - Jacobian needs
* to be updated/reevaluated, if appropriate, unless
* new_uu = FALSE [input/output]
*
* user_data pointer to user data, the same as the user_data
* parameter passed to the KINSetUserData function.
*
* If successful, the function should return 0 (zero). If an error
* occurs, then the routine should return a non-zero integer value.
* -----------------------------------------------------------------
*/
typedef int (*KINSpilsJacTimesVecFn)(N_Vector v, N_Vector Jv,
N_Vector uu, booleantype *new_uu,
void *J_data);
/*
* -----------------------------------------------------------------
* Optional Input Specification Functions
* -----------------------------------------------------------------
* The following functions can be called to set optional inputs:
*
* Function Name | Optional Input [Default Value]
* |
* -----------------------------------------------------------------
* |
* KINSpilsSetMaxRestarts | maximum number of times the SPGMR
* | (scaled preconditioned GMRES) linear
* | solver can be restarted
* | [0]
* |
* KINSpilsSetPreconditioner | used to set the following:
* | (a) name of user-supplied routine
* | used to compute a preconditioner
* | matrix for the given linear
* | system (pset)
* | [NULL]
* | (b) name of user-supplied routine
* | used to apply preconditioner to
* | linear system (psolve)
* | [NULL]
* |
* KINSpilsSetJacTimesVecFn | used to set the following the name
* | of user-supplied subroutine used to
* | compute the matrix-vector product J(u)*v,
* | where J denotes the system Jacobian.
* | [KINSpilsDQJtimes]
* -----------------------------------------------------------------
*/
SUNDIALS_EXPORT int KINSpilsSetMaxRestarts(void *kinmem, int maxrs);
SUNDIALS_EXPORT int KINSpilsSetPreconditioner(void *kinmem,
KINSpilsPrecSetupFn pset,
KINSpilsPrecSolveFn psolve);
SUNDIALS_EXPORT int KINSpilsSetJacTimesVecFn(void *kinmem,
KINSpilsJacTimesVecFn jtv);
/*
* -----------------------------------------------------------------
* KINSpilsSet* Return Values
* -----------------------------------------------------------------
* The possible return values for the KINSpilsSet* subroutines
* are the following:
*
* KINSPILS_SUCCESS : means the associated parameter was successfully
* set [0]
*
* KINSPILS_ILL_INPUT : means the supplied parameter was invalid
* (check error message) [-3]
*
* KINSPILS_MEM_NULL : means a NULL KINSOL memory block pointer
* was given [-1]
*
* KINSPILS_LMEM_NULL : means system memory has not yet been
* allocated for the linear solver
* (lmem == NULL) [-2]
* -----------------------------------------------------------------
*/
/*
* -----------------------------------------------------------------
* Optional Output Extraction Functions
* -----------------------------------------------------------------
* The following functions can be called to get optional outputs
* and statistical information related to the KINSPILS linear
* solvers:
*
* Function Name | Returned Value
* |
* -----------------------------------------------------------------
* |
* KINSpilsGetWorkSpace | returns both integer workspace size
* | (total number of long int-sized blocks
* | of memory allocated for
* | vector storage), and real workspace
* | size (total number of realtype-sized
* | blocks of memory allocated
* | for vector storage)
* |
* KINSpilsGetNumPrecEvals | total number of preconditioner
* | evaluations (number of calls made
* | to the user-defined pset routine)
* |
* KINSpilsGetNumPrecSolves | total number of times preconditioner
* | was applied to linear system (number
* | of calls made to the user-supplied
* | psolve function)
* |
* KINSpilsGetNumLinIters | total number of linear iterations
* | performed
* |
* KINSpilsGetNumConvFails | total number of linear convergence
* | failures
* |
* KINSpilsGetNumJtimesEvals | total number of times the matrix-
* | vector product J(u)*v was computed
* | (number of calls made to the jtimes
* | subroutine)
* |
* KINSpilsGetNumFuncEvals | total number of evaluations of the
* | system function F(u) (number of
* | calls made to the user-supplied
* | func routine by the linear solver
* | module member subroutines)
* |
* KINSpilsGetLastFlag | returns the last flag returned by
* | the linear solver
* |
* KINSpilsGetReturnFlagName | returns the name of the constant
* | associated with a KINSPILS return flag
* -----------------------------------------------------------------
*/
SUNDIALS_EXPORT int KINSpilsGetWorkSpace(void *kinmem, long int *lenrwSG, long int *leniwSG);
SUNDIALS_EXPORT int KINSpilsGetNumPrecEvals(void *kinmem, long int *npevals);
SUNDIALS_EXPORT int KINSpilsGetNumPrecSolves(void *kinmem, long int *npsolves);
SUNDIALS_EXPORT int KINSpilsGetNumLinIters(void *kinmem, long int *nliters);
SUNDIALS_EXPORT int KINSpilsGetNumConvFails(void *kinmem, long int *nlcfails);
SUNDIALS_EXPORT int KINSpilsGetNumJtimesEvals(void *kinmem, long int *njvevals);
SUNDIALS_EXPORT int KINSpilsGetNumFuncEvals(void *kinmem, long int *nfevalsS);
SUNDIALS_EXPORT int KINSpilsGetLastFlag(void *kinmem, long int *flag);
SUNDIALS_EXPORT char *KINSpilsGetReturnFlagName(long int flag);
#ifdef __cplusplus
}
#endif
#endif
|