/usr/include/kinsol/kinsol_direct.h is in libsundials-dev 2.7.0+dfsg-2build1.
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 | /*
* -----------------------------------------------------------------
* $Revision: 4378 $
* $Date: 2015-02-19 10:55:14 -0800 (Thu, 19 Feb 2015) $
* -----------------------------------------------------------------
* Programmer: Radu Serban @ LLNL
* -----------------------------------------------------------------
* LLNS Copyright Start
* Copyright (c) 2014, Lawrence Livermore National Security
* This work was performed under the auspices of the U.S. Department
* of Energy by Lawrence Livermore National Laboratory in part under
* Contract W-7405-Eng-48 and in part under Contract DE-AC52-07NA27344.
* Produced at the Lawrence Livermore National Laboratory.
* All rights reserved.
* For details, see the LICENSE file.
* LLNS Copyright End
* -----------------------------------------------------------------
* Common header file for the direct linear solvers in KINSOL.
* -----------------------------------------------------------------
*/
#ifndef _KINDLS_H
#define _KINDLS_H
#include <sundials/sundials_direct.h>
#include <sundials/sundials_nvector.h>
#ifdef __cplusplus /* wrapper to enable C++ usage */
extern "C" {
#endif
/*
* =================================================================
* K I N D I R E C T C O N S T A N T S
* =================================================================
*/
/*
* -----------------------------------------------------------------
* KINDLS return values
* -----------------------------------------------------------------
*/
#define KINDLS_SUCCESS 0
#define KINDLS_MEM_NULL -1
#define KINDLS_LMEM_NULL -2
#define KINDLS_ILL_INPUT -3
#define KINDLS_MEM_FAIL -4
/* Additional last_flag values */
#define KINDLS_JACFUNC_UNRECVR -5
#define KINDLS_JACFUNC_RECVR -6
/*
* =================================================================
* F U N C T I O N T Y P E S
* =================================================================
*/
/*
* -----------------------------------------------------------------
* Type: KINDlsDenseJacFn
* -----------------------------------------------------------------
*
* A dense Jacobian approximation function Jac must be of type
* KINDlsDenseJacFn. Its parameters are:
*
* N - problem size.
*
* u - current iterate (unscaled) [input]
*
* fu - vector (type N_Vector) containing result of nonlinear
* system function evaluated at current iterate:
* fu = F(u) [input]
*
* J - dense matrix (of type DlsMat) that will be loaded
* by a KINDlsDenseJacFn with an approximation to the
* Jacobian matrix J = (dF_i/dy_j).
*
* user_data - pointer to user data - the same as the user_data
* parameter passed to KINSetFdata.
*
* tmp1, tmp2 - available scratch vectors (volatile storage)
*
* A KINDlsDenseJacFn should return 0 if successful, a positive
* value if a recoverable error occurred, and a negative value if
* an unrecoverable error occurred.
*
* -----------------------------------------------------------------
*
* NOTE: The following are two efficient ways to load a dense Jac:
* (1) (with macros - no explicit data structure references)
* for (j=0; j < Neq; j++) {
* col_j = DENSE_COL(Jac,j);
* for (i=0; i < Neq; i++) {
* generate J_ij = the (i,j)th Jacobian element
* col_j[i] = J_ij;
* }
* }
* (2) (without macros - explicit data structure references)
* for (j=0; j < Neq; j++) {
* col_j = (Jac->data)[j];
* for (i=0; i < Neq; i++) {
* generate J_ij = the (i,j)th Jacobian element
* col_j[i] = J_ij;
* }
* }
* A third way, using the DENSE_ELEM(A,i,j) macro, is much less
* efficient in general. It is only appropriate for use in small
* problems in which efficiency of access is NOT a major concern.
*
* -----------------------------------------------------------------
*/
typedef int (*KINDlsDenseJacFn)(long int N,
N_Vector u, N_Vector fu,
DlsMat J, void *user_data,
N_Vector tmp1, N_Vector tmp2);
/*
* -----------------------------------------------------------------
* Type: KINDlsBandJacFn
* -----------------------------------------------------------------
*
* A band Jacobian approximation function Jac must have the
* prototype given below. Its parameters are:
*
* N is the problem size
*
* mupper is the upper half-bandwidth of the approximate banded
* Jacobian. This parameter is the same as the mupper parameter
* passed by the user to the linear solver initialization function.
*
* mlower is the lower half-bandwidth of the approximate banded
* Jacobian. This parameter is the same as the mlower parameter
* passed by the user to the linear solver initialization function.
*
* u - current iterate (unscaled) [input]
*
* fu - vector (type N_Vector) containing result of nonlinear
* system function evaluated at current iterate:
* fu = F(uu) [input]
*
* J - band matrix (of type DlsMat) that will be loaded by a
* KINDlsBandJacFn with an approximation to the Jacobian
* matrix Jac = (dF_i/dy_j).
*
* user_data - pointer to user data - the same as the user_data
* parameter passed to KINSetFdata.
*
* tmp1, tmp2 - available scratch vectors (volatile storage)
*
* A KINDlsBandJacFn should return 0 if successful, a positive value
* if a recoverable error occurred, and a negative value if an
* unrecoverable error occurred.
*
* -----------------------------------------------------------------
*
* NOTE. Three efficient ways to load J are:
*
* (1) (with macros - no explicit data structure references)
* for (j=0; j < n; j++) {
* col_j = BAND_COL(Jac,j);
* for (i=j-mupper; i <= j+mlower; i++) {
* generate J_ij = the (i,j)th Jacobian element
* BAND_COL_ELEM(col_j,i,j) = J_ij;
* }
* }
*
* (2) (with BAND_COL macro, but without BAND_COL_ELEM macro)
* for (j=0; j < n; j++) {
* col_j = BAND_COL(Jac,j);
* for (k=-mupper; k <= mlower; k++) {
* generate J_ij = the (i,j)th Jacobian element, i=j+k
* col_j[k] = J_ij;
* }
* }
*
* (3) (without macros - explicit data structure references)
* offset = Jac->smu;
* for (j=0; j < n; j++) {
* col_j = ((Jac->data)[j])+offset;
* for (k=-mupper; k <= mlower; k++) {
* generate J_ij = the (i,j)th Jacobian element, i=j+k
* col_j[k] = J_ij;
* }
* }
* Caution: Jac->smu is generally NOT the same as mupper.
*
* The BAND_ELEM(A,i,j) macro is appropriate for use in small
* problems in which efficiency of access is NOT a major concern.
*
* -----------------------------------------------------------------
*/
typedef int (*KINDlsBandJacFn)(long int N, long int mupper, long int mlower,
N_Vector u, N_Vector fu,
DlsMat J, void *user_data,
N_Vector tmp1, N_Vector tmp2);
/*
* =================================================================
* E X P O R T E D F U N C T I O N S
* =================================================================
*/
/*
* -----------------------------------------------------------------
* Optional inputs to the KINDLS linear solver
* -----------------------------------------------------------------
*
* KINDlsSetDenseJacFn specifies the dense Jacobian approximation
* routine to be used for a direct dense linear solver.
*
* KINDlsSetBandJacFn specifies the band Jacobian approximation
* routine to be used for a direct band linear solver.
*
* By default, a difference quotient approximation, supplied with
* the solver is used.
*
* The return value is one of:
* KINDLS_SUCCESS if successful
* KINDLS_MEM_NULL if the KINSOL memory was NULL
* KINDLS_LMEM_NULL if the linear solver memory was NULL
* -----------------------------------------------------------------
*/
SUNDIALS_EXPORT int KINDlsSetDenseJacFn(void *kinmem, KINDlsDenseJacFn jac);
SUNDIALS_EXPORT int KINDlsSetBandJacFn(void *kinmem, KINDlsBandJacFn jac);
/*
* -----------------------------------------------------------------
* Optional outputs from a KINDLS linear solver
* -----------------------------------------------------------------
*
* KINDlsGetWorkSpace returns the real and integer workspace used
* by the KINDLS linear solver.
* KINDlsGetNumJacEvals returns the number of calls made to the
* Jacobian evaluation routine.
* KINDlsGetNumFuncEvals returns the number of calls to the user's F
* routine due to finite difference Jacobian
* evaluation.
* KINDlsGetLastFlag returns the last error flag set by any of
* the KINDLS interface functions.
* KINDlsGetReturnFlagName returns the name of the constant
* associated with a KINDLS return flag
*
* The return value of KINDlsGet* is one of:
* KINDLS_SUCCESS if successful
* KINDLS_MEM_NULL if the KINSOL memory was NULL
* KINDLS_LMEM_NULL if the linear solver memory was NULL
* -----------------------------------------------------------------
*/
SUNDIALS_EXPORT int KINDlsGetWorkSpace(void *kinmem, long int *lenrwB, long int *leniwB);
SUNDIALS_EXPORT int KINDlsGetNumJacEvals(void *kinmem, long int *njevalsB);
SUNDIALS_EXPORT int KINDlsGetNumFuncEvals(void *kinmem, long int *nfevalsB);
SUNDIALS_EXPORT int KINDlsGetLastFlag(void *kinmem, long int *flag);
SUNDIALS_EXPORT char *KINDlsGetReturnFlagName(long int flag);
#ifdef __cplusplus
}
#endif
#endif
|