/* ----------------------------------------------------------------- * Programmer(s): Daniel Reynolds @ SMU * David Gardner, Carol Woodward, * Slaven Peles, Cody Balos @ LLNL * ----------------------------------------------------------------- * SUNDIALS Copyright Start * Copyright (c) 2002-2024, Lawrence Livermore National Security * and Southern Methodist University. * All rights reserved. * * See the top-level LICENSE and NOTICE files for details. * * SPDX-License-Identifier: BSD-3-Clause * SUNDIALS Copyright End * ----------------------------------------------------------------- * This is the header file for a generic linear solver package. * It defines the SUNLinearSolver structure (_generic_SUNLinearSolver) * which contains the following fields: * - an implementation-dependent 'content' field which contains * any internal data required by the solver * - an 'ops' filed which contains a structure listing operations * acting on/by such solvers * * We consider both direct linear solvers and iterative linear solvers * as available implementations of this package. Furthermore, iterative * linear solvers can either use a matrix or be matrix-free. As a * result of these different solver characteristics, some of the * routines are applicable only to some types of linear solver. * ----------------------------------------------------------------- * This header file contains: * - enumeration constants for all SUNDIALS-defined linear solver * types, as well as a generic type for user-supplied linear * solver types, * - type declarations for the _generic_SUNLinearSolver and * _generic_SUNLinearSolver_Ops structures, as well as references * to pointers to such structures (SUNLinearSolver), * - prototypes for the linear solver functions which operate * on/by SUNLinearSolver objects, and * - return codes for SUNLinearSolver objects. * ----------------------------------------------------------------- * At a minimum, a particular implementation of a SUNLinearSolver must * do the following: * - specify the 'content' field of SUNLinearSolver, * - implement the operations on/by those SUNLinearSolver objects, * - provide a constructor routine for new SUNLinearSolver objects * * Additionally, a SUNLinearSolver implementation may provide the * following: * - "Set" routines to control solver-specific parameters/options * - "Get" routines to access solver-specific performance metrics * -----------------------------------------------------------------*/ #ifndef _SUNLINEARSOLVER_H #define _SUNLINEARSOLVER_H #include #include #include #include #include #include #include #ifdef __cplusplus /* wrapper to enable C++ usage */ extern "C" { #endif /* ----------------------------------------------------------------- * Implemented SUNLinearSolver types and IDs: * ----------------------------------------------------------------- */ typedef enum { SUNLINEARSOLVER_DIRECT, SUNLINEARSOLVER_ITERATIVE, SUNLINEARSOLVER_MATRIX_ITERATIVE, SUNLINEARSOLVER_MATRIX_EMBEDDED } SUNLinearSolver_Type; typedef enum { SUNLINEARSOLVER_BAND, SUNLINEARSOLVER_DENSE, SUNLINEARSOLVER_KLU, SUNLINEARSOLVER_LAPACKBAND, SUNLINEARSOLVER_LAPACKDENSE, SUNLINEARSOLVER_PCG, SUNLINEARSOLVER_SPBCGS, SUNLINEARSOLVER_SPFGMR, SUNLINEARSOLVER_SPGMR, SUNLINEARSOLVER_SPTFQMR, SUNLINEARSOLVER_SUPERLUDIST, SUNLINEARSOLVER_SUPERLUMT, SUNLINEARSOLVER_CUSOLVERSP_BATCHQR, SUNLINEARSOLVER_MAGMADENSE, SUNLINEARSOLVER_ONEMKLDENSE, SUNLINEARSOLVER_GINKGO, SUNLINEARSOLVER_KOKKOSDENSE, SUNLINEARSOLVER_CUSTOM } SUNLinearSolver_ID; /* ----------------------------------------------------------------- * Generic definition of SUNLinearSolver * ----------------------------------------------------------------- */ /* Forward reference for pointer to SUNLinearSolver_Ops object */ typedef _SUNDIALS_STRUCT_ _generic_SUNLinearSolver_Ops* SUNLinearSolver_Ops; /* Forward reference for pointer to SUNLinearSolver object */ typedef _SUNDIALS_STRUCT_ _generic_SUNLinearSolver* SUNLinearSolver; /* Structure containing function pointers to linear solver operations */ struct _generic_SUNLinearSolver_Ops { SUNLinearSolver_Type (*gettype)(SUNLinearSolver); SUNLinearSolver_ID (*getid)(SUNLinearSolver); SUNErrCode (*setatimes)(SUNLinearSolver, void*, SUNATimesFn); SUNErrCode (*setpreconditioner)(SUNLinearSolver, void*, SUNPSetupFn, SUNPSolveFn); SUNErrCode (*setscalingvectors)(SUNLinearSolver, N_Vector, N_Vector); SUNErrCode (*setzeroguess)(SUNLinearSolver, sunbooleantype); SUNErrCode (*initialize)(SUNLinearSolver); int (*setup)(SUNLinearSolver, SUNMatrix); int (*solve)(SUNLinearSolver, SUNMatrix, N_Vector, N_Vector, sunrealtype); int (*numiters)(SUNLinearSolver); sunrealtype (*resnorm)(SUNLinearSolver); sunindextype (*lastflag)(SUNLinearSolver); SUNErrCode (*space)(SUNLinearSolver, long int*, long int*); N_Vector (*resid)(SUNLinearSolver); SUNErrCode (*free)(SUNLinearSolver); }; /* A linear solver is a structure with an implementation-dependent 'content' field, and a pointer to a structure of linear solver operations corresponding to that implementation. */ struct _generic_SUNLinearSolver { void* content; SUNLinearSolver_Ops ops; SUNContext sunctx; }; /* ----------------------------------------------------------------- * Functions exported by SUNLinearSolver module * ----------------------------------------------------------------- */ SUNDIALS_EXPORT SUNLinearSolver SUNLinSolNewEmpty(SUNContext sunctx); SUNDIALS_EXPORT void SUNLinSolFreeEmpty(SUNLinearSolver S); SUNDIALS_EXPORT SUNLinearSolver_Type SUNLinSolGetType(SUNLinearSolver S); SUNDIALS_EXPORT SUNLinearSolver_ID SUNLinSolGetID(SUNLinearSolver S); SUNDIALS_EXPORT SUNErrCode SUNLinSolSetATimes(SUNLinearSolver S, void* A_data, SUNATimesFn ATimes); SUNDIALS_EXPORT SUNErrCode SUNLinSolSetPreconditioner(SUNLinearSolver S, void* P_data, SUNPSetupFn Pset, SUNPSolveFn Psol); SUNDIALS_EXPORT SUNErrCode SUNLinSolSetScalingVectors(SUNLinearSolver S, N_Vector s1, N_Vector s2); SUNDIALS_EXPORT SUNErrCode SUNLinSolSetZeroGuess(SUNLinearSolver S, sunbooleantype onoff); SUNDIALS_EXPORT SUNErrCode SUNLinSolInitialize(SUNLinearSolver S); SUNDIALS_EXPORT int SUNLinSolSetup(SUNLinearSolver S, SUNMatrix A); SUNDIALS_EXPORT int SUNLinSolSolve(SUNLinearSolver S, SUNMatrix A, N_Vector x, N_Vector b, sunrealtype tol); /* TODO(CJB): We should consider changing the return type to long int since batched solvers could in theory return a very large number here. */ SUNDIALS_EXPORT int SUNLinSolNumIters(SUNLinearSolver S); SUNDIALS_EXPORT sunrealtype SUNLinSolResNorm(SUNLinearSolver S); SUNDIALS_EXPORT N_Vector SUNLinSolResid(SUNLinearSolver S); /* TODO(CJB): sunindextype being the return type here could cause a problem if sunindextype happened to be smaller than an int. */ SUNDIALS_EXPORT sunindextype SUNLinSolLastFlag(SUNLinearSolver S); SUNDIALS_EXPORT SUNErrCode SUNLinSolSpace(SUNLinearSolver S, long int* lenrwLS, long int* leniwLS); SUNDIALS_EXPORT SUNErrCode SUNLinSolFree(SUNLinearSolver S); /* ----------------------------------------------------------------- * SUNLinearSolver return values * ----------------------------------------------------------------- */ #define SUNLS_ATIMES_NULL -804 /* atimes function is NULL */ #define SUNLS_ATIMES_FAIL_UNREC -805 /* atimes unrecoverable failure */ #define SUNLS_PSET_FAIL_UNREC -806 /* pset unrecoverable failure */ #define SUNLS_PSOLVE_NULL -807 /* psolve function is NULL */ #define SUNLS_PSOLVE_FAIL_UNREC -808 /* psolve unrecoverable failure */ #define SUNLS_GS_FAIL -810 /* Gram-Schmidt failure */ #define SUNLS_QRSOL_FAIL -811 /* QRsol found singular R */ #define SUNLS_RECOV_FAILURE 800 /* generic recoverable failure */ #define SUNLS_RES_REDUCED 801 /* nonconv. solve, resid reduced */ #define SUNLS_CONV_FAIL 802 /* nonconvergent solve */ #define SUNLS_ATIMES_FAIL_REC 803 /* atimes failed recoverably */ #define SUNLS_PSET_FAIL_REC 804 /* pset failed recoverably */ #define SUNLS_PSOLVE_FAIL_REC 805 /* psolve failed recoverably */ #define SUNLS_PACKAGE_FAIL_REC 806 /* external package recov. fail */ #define SUNLS_QRFACT_FAIL 807 /* QRfact found singular matrix */ #define SUNLS_LUFACT_FAIL 808 /* LUfact found singular matrix */ /* ----------------------------------------------------------------------------- * SUNLinearSolver messages * ---------------------------------------------------------------------------*/ #if defined(SUNDIALS_EXTENDED_PRECISION) #define SUNLS_MSG_RESIDUAL "\t\tlin. iteration %ld, lin. residual: %Lg\n" #elif defined(SUNDIALS_DOUBLE_PRECISION) #define SUNLS_MSG_RESIDUAL "\t\tlin. iteration %ld, lin. residual: %g\n" #else #define SUNLS_MSG_RESIDUAL "\t\tlin. iteration %ld, lin. residual: %g\n" #endif #ifdef __cplusplus } #endif #endif