1 /* ----------------------------------------------------------------- 2 * Programmer(s): Daniel Reynolds @ SMU 3 * David Gardner, Carol Woodward, 4 * Slaven Peles, Cody Balos @ LLNL 5 * ----------------------------------------------------------------- 6 * SUNDIALS Copyright Start 7 * Copyright (c) 2002-2020, Lawrence Livermore National Security 8 * and Southern Methodist University. 9 * All rights reserved. 10 * 11 * See the top-level LICENSE and NOTICE files for details. 12 * 13 * SPDX-License-Identifier: BSD-3-Clause 14 * SUNDIALS Copyright End 15 * ----------------------------------------------------------------- 16 * This is the header file for a generic linear solver package. 17 * It defines the SUNLinearSolver structure (_generic_SUNLinearSolver) 18 * which contains the following fields: 19 * - an implementation-dependent 'content' field which contains 20 * any internal data required by the solver 21 * - an 'ops' filed which contains a structure listing operations 22 * acting on/by such solvers 23 * 24 * We consider both direct linear solvers and iterative linear solvers 25 * as available implementations of this package. Furthermore, iterative 26 * linear solvers can either use a matrix or be matrix-free. As a 27 * result of these different solver characteristics, some of the 28 * routines are applicable only to some types of linear solver. 29 * ----------------------------------------------------------------- 30 * This header file contains: 31 * - enumeration constants for all SUNDIALS-defined linear solver 32 * types, as well as a generic type for user-supplied linear 33 * solver types, 34 * - type declarations for the _generic_SUNLinearSolver and 35 * _generic_SUNLinearSolver_Ops structures, as well as references 36 * to pointers to such structures (SUNLinearSolver), 37 * - prototypes for the linear solver functions which operate 38 * on/by SUNLinearSolver objects, and 39 * - return codes for SUNLinearSolver objects. 40 * ----------------------------------------------------------------- 41 * At a minimum, a particular implementation of a SUNLinearSolver must 42 * do the following: 43 * - specify the 'content' field of SUNLinearSolver, 44 * - implement the operations on/by those SUNLinearSolver objects, 45 * - provide a constructor routine for new SUNLinearSolver objects 46 * 47 * Additionally, a SUNLinearSolver implementation may provide the 48 * following: 49 * - "Set" routines to control solver-specific parameters/options 50 * - "Get" routines to access solver-specific performance metrics 51 * -----------------------------------------------------------------*/ 52 53 #ifndef _SUNLINEARSOLVER_H 54 #define _SUNLINEARSOLVER_H 55 56 #include <sundials/sundials_types.h> 57 #include <sundials/sundials_iterative.h> 58 #include <sundials/sundials_matrix.h> 59 #include <sundials/sundials_nvector.h> 60 61 #ifdef __cplusplus /* wrapper to enable C++ usage */ 62 extern "C" { 63 #endif 64 65 66 /* ----------------------------------------------------------------- 67 * Implemented SUNLinearSolver types and IDs: 68 * ----------------------------------------------------------------- */ 69 70 typedef enum { 71 SUNLINEARSOLVER_DIRECT, 72 SUNLINEARSOLVER_ITERATIVE, 73 SUNLINEARSOLVER_MATRIX_ITERATIVE 74 } SUNLinearSolver_Type; 75 76 typedef enum { 77 SUNLINEARSOLVER_BAND, 78 SUNLINEARSOLVER_DENSE, 79 SUNLINEARSOLVER_KLU, 80 SUNLINEARSOLVER_LAPACKBAND, 81 SUNLINEARSOLVER_LAPACKDENSE, 82 SUNLINEARSOLVER_PCG, 83 SUNLINEARSOLVER_SPBCGS, 84 SUNLINEARSOLVER_SPFGMR, 85 SUNLINEARSOLVER_SPGMR, 86 SUNLINEARSOLVER_SPTFQMR, 87 SUNLINEARSOLVER_SUPERLUDIST, 88 SUNLINEARSOLVER_SUPERLUMT, 89 SUNLINEARSOLVER_CUSOLVERSP_BATCHQR, 90 SUNLINEARSOLVER_CUSTOM 91 } SUNLinearSolver_ID; 92 93 94 /* ----------------------------------------------------------------- 95 * Generic definition of SUNLinearSolver 96 * ----------------------------------------------------------------- */ 97 98 /* Forward reference for pointer to SUNLinearSolver_Ops object */ 99 typedef _SUNDIALS_STRUCT_ _generic_SUNLinearSolver_Ops *SUNLinearSolver_Ops; 100 101 /* Forward reference for pointer to SUNLinearSolver object */ 102 typedef _SUNDIALS_STRUCT_ _generic_SUNLinearSolver *SUNLinearSolver; 103 104 /* Structure containing function pointers to linear solver operations */ 105 struct _generic_SUNLinearSolver_Ops { 106 SUNLinearSolver_Type (*gettype)(SUNLinearSolver); 107 SUNLinearSolver_ID (*getid)(SUNLinearSolver); 108 int (*setatimes)(SUNLinearSolver, void*, ATimesFn); 109 int (*setpreconditioner)(SUNLinearSolver, void*, 110 PSetupFn, PSolveFn); 111 int (*setscalingvectors)(SUNLinearSolver, 112 N_Vector, N_Vector); 113 int (*initialize)(SUNLinearSolver); 114 int (*setup)(SUNLinearSolver, SUNMatrix); 115 int (*solve)(SUNLinearSolver, SUNMatrix, N_Vector, 116 N_Vector, realtype); 117 int (*numiters)(SUNLinearSolver); 118 realtype (*resnorm)(SUNLinearSolver); 119 sunindextype (*lastflag)(SUNLinearSolver); 120 int (*space)(SUNLinearSolver, long int*, long int*); 121 N_Vector (*resid)(SUNLinearSolver); 122 int (*free)(SUNLinearSolver); 123 }; 124 125 /* A linear solver is a structure with an implementation-dependent 126 'content' field, and a pointer to a structure of linear solver 127 operations corresponding to that implementation. */ 128 struct _generic_SUNLinearSolver { 129 void *content; 130 SUNLinearSolver_Ops ops; 131 }; 132 133 134 /* ----------------------------------------------------------------- 135 * Functions exported by SUNLinearSolver module 136 * ----------------------------------------------------------------- */ 137 138 SUNDIALS_EXPORT SUNLinearSolver SUNLinSolNewEmpty(); 139 140 SUNDIALS_EXPORT void SUNLinSolFreeEmpty(SUNLinearSolver S); 141 142 SUNDIALS_EXPORT SUNLinearSolver_Type SUNLinSolGetType(SUNLinearSolver S); 143 144 SUNDIALS_EXPORT SUNLinearSolver_ID SUNLinSolGetID(SUNLinearSolver S); 145 146 SUNDIALS_EXPORT int SUNLinSolSetATimes(SUNLinearSolver S, void* A_data, 147 ATimesFn ATimes); 148 149 SUNDIALS_EXPORT int SUNLinSolSetPreconditioner(SUNLinearSolver S, void* P_data, 150 PSetupFn Pset, PSolveFn Psol); 151 152 SUNDIALS_EXPORT int SUNLinSolSetScalingVectors(SUNLinearSolver S, N_Vector s1, 153 N_Vector s2); 154 155 SUNDIALS_EXPORT int SUNLinSolInitialize(SUNLinearSolver S); 156 157 SUNDIALS_EXPORT int SUNLinSolSetup(SUNLinearSolver S, SUNMatrix A); 158 159 SUNDIALS_EXPORT int SUNLinSolSolve(SUNLinearSolver S, SUNMatrix A, N_Vector x, 160 N_Vector b, realtype tol); 161 162 SUNDIALS_EXPORT int SUNLinSolNumIters(SUNLinearSolver S); 163 164 SUNDIALS_EXPORT realtype SUNLinSolResNorm(SUNLinearSolver S); 165 166 SUNDIALS_EXPORT N_Vector SUNLinSolResid(SUNLinearSolver S); 167 168 SUNDIALS_EXPORT sunindextype SUNLinSolLastFlag(SUNLinearSolver S); 169 170 SUNDIALS_EXPORT int SUNLinSolSpace(SUNLinearSolver S, long int *lenrwLS, 171 long int *leniwLS); 172 173 SUNDIALS_EXPORT int SUNLinSolFree(SUNLinearSolver S); 174 175 176 /* ----------------------------------------------------------------- 177 * SUNLinearSolver return values 178 * ----------------------------------------------------------------- */ 179 180 #define SUNLS_SUCCESS 0 /* successful/converged */ 181 182 #define SUNLS_MEM_NULL -801 /* mem argument is NULL */ 183 #define SUNLS_ILL_INPUT -802 /* illegal function input */ 184 #define SUNLS_MEM_FAIL -803 /* failed memory access */ 185 #define SUNLS_ATIMES_NULL -804 /* atimes function is NULL */ 186 #define SUNLS_ATIMES_FAIL_UNREC -805 /* atimes unrecoverable failure */ 187 #define SUNLS_PSET_FAIL_UNREC -806 /* pset unrecoverable failure */ 188 #define SUNLS_PSOLVE_NULL -807 /* psolve function is NULL */ 189 #define SUNLS_PSOLVE_FAIL_UNREC -808 /* psolve unrecoverable failure */ 190 #define SUNLS_PACKAGE_FAIL_UNREC -809 /* external package unrec. fail */ 191 #define SUNLS_GS_FAIL -810 /* Gram-Schmidt failure */ 192 #define SUNLS_QRSOL_FAIL -811 /* QRsol found singular R */ 193 #define SUNLS_VECTOROP_ERR -812 /* vector operation error */ 194 195 #define SUNLS_RES_REDUCED 801 /* nonconv. solve, resid reduced */ 196 #define SUNLS_CONV_FAIL 802 /* nonconvergent solve */ 197 #define SUNLS_ATIMES_FAIL_REC 803 /* atimes failed recoverably */ 198 #define SUNLS_PSET_FAIL_REC 804 /* pset failed recoverably */ 199 #define SUNLS_PSOLVE_FAIL_REC 805 /* psolve failed recoverably */ 200 #define SUNLS_PACKAGE_FAIL_REC 806 /* external package recov. fail */ 201 #define SUNLS_QRFACT_FAIL 807 /* QRfact found singular matrix */ 202 #define SUNLS_LUFACT_FAIL 808 /* LUfact found singular matrix */ 203 204 /* ----------------------------------------------------------------------------- 205 * SUNLinearSolver messages 206 * ---------------------------------------------------------------------------*/ 207 208 #if defined(SUNDIALS_EXTENDED_PRECISION) 209 #define SUNLS_MSG_RESIDUAL "\t\tlin. iteration %ld, lin. residual: %Lg\n" 210 #elif defined(SUNDIALS_DOUBLE_PRECISION) 211 #define SUNLS_MSG_RESIDUAL "\t\tlin. iteration %ld, lin. residual: %g\n" 212 #else 213 #define SUNLS_MSG_RESIDUAL "\t\tlin. iteration %ld, lin. residual: %g\n" 214 #endif 215 216 #ifdef __cplusplus 217 } 218 #endif 219 #endif 220