1 /* ----------------------------------------------------------------- 2 * Programmer(s): Radu Serban and Aaron Collier @ LLNL 3 * ----------------------------------------------------------------- 4 * SUNDIALS Copyright Start 5 * Copyright (c) 2002-2021, Lawrence Livermore National Security 6 * and Southern Methodist University. 7 * All rights reserved. 8 * 9 * See the top-level LICENSE and NOTICE files for details. 10 * 11 * SPDX-License-Identifier: BSD-3-Clause 12 * SUNDIALS Copyright End 13 * ----------------------------------------------------------------- 14 * This is the header file for a generic NVECTOR package. 15 * It defines the N_Vector structure (_generic_N_Vector) which 16 * contains the following fields: 17 * - an implementation-dependent 'content' field which contains 18 * the description and actual data of the vector 19 * - an 'ops' filed which contains a structure listing operations 20 * acting on such vectors 21 * ----------------------------------------------------------------- 22 * This header file contains: 23 * - enumeration constants for all SUNDIALS-defined vector types, 24 * as well as a generic type for user-supplied vector types, 25 * - type declarations for the _generic_N_Vector and 26 * _generic_N_Vector_Ops structures, as well as references to 27 * pointers to such structures (N_Vector), and 28 * - prototypes for the vector functions which operate on 29 * N_Vector objects. 30 * ----------------------------------------------------------------- 31 * At a minimum, a particular implementation of an NVECTOR must 32 * do the following: 33 * - specify the 'content' field of N_Vector, 34 * - implement the operations on those N_Vector objects, 35 * - provide a constructor routine for new N_Vector objects 36 * 37 * Additionally, an NVECTOR implementation may provide the following: 38 * - macros to access the underlying N_Vector data 39 * - a constructor for an array of N_Vectors 40 * - a constructor for an empty N_Vector (i.e., a new N_Vector with 41 * a NULL data pointer). 42 * - a routine to print the content of an N_Vector 43 * -----------------------------------------------------------------*/ 44 45 #ifndef _NVECTOR_H 46 #define _NVECTOR_H 47 48 #include <stdio.h> 49 #include <stdlib.h> 50 51 #include <sundials/sundials_types.h> 52 53 #ifdef __cplusplus /* wrapper to enable C++ usage */ 54 extern "C" { 55 #endif 56 57 58 /* ----------------------------------------------------------------- 59 * Implemented N_Vector types 60 * ----------------------------------------------------------------- */ 61 62 typedef enum { 63 SUNDIALS_NVEC_SERIAL, 64 SUNDIALS_NVEC_PARALLEL, 65 SUNDIALS_NVEC_OPENMP, 66 SUNDIALS_NVEC_PTHREADS, 67 SUNDIALS_NVEC_PARHYP, 68 SUNDIALS_NVEC_PETSC, 69 SUNDIALS_NVEC_CUDA, 70 SUNDIALS_NVEC_HIP, 71 SUNDIALS_NVEC_SYCL, 72 SUNDIALS_NVEC_RAJA, 73 SUNDIALS_NVEC_OPENMPDEV, 74 SUNDIALS_NVEC_TRILINOS, 75 SUNDIALS_NVEC_MANYVECTOR, 76 SUNDIALS_NVEC_MPIMANYVECTOR, 77 SUNDIALS_NVEC_MPIPLUSX, 78 SUNDIALS_NVEC_CUSTOM 79 } N_Vector_ID; 80 81 82 /* ----------------------------------------------------------------- 83 * Generic definition of N_Vector 84 * ----------------------------------------------------------------- */ 85 86 /* Forward reference for pointer to N_Vector_Ops object */ 87 typedef _SUNDIALS_STRUCT_ _generic_N_Vector_Ops *N_Vector_Ops; 88 89 /* Forward reference for pointer to N_Vector object */ 90 typedef _SUNDIALS_STRUCT_ _generic_N_Vector *N_Vector; 91 92 /* Define array of N_Vectors */ 93 typedef N_Vector *N_Vector_S; 94 95 /* Structure containing function pointers to vector operations */ 96 struct _generic_N_Vector_Ops { 97 N_Vector_ID (*nvgetvectorid)(N_Vector); 98 N_Vector (*nvclone)(N_Vector); 99 N_Vector (*nvcloneempty)(N_Vector); 100 void (*nvdestroy)(N_Vector); 101 void (*nvspace)(N_Vector, sunindextype *, sunindextype *); 102 realtype* (*nvgetarraypointer)(N_Vector); 103 realtype* (*nvgetdevicearraypointer)(N_Vector); 104 void (*nvsetarraypointer)(realtype *, N_Vector); 105 void* (*nvgetcommunicator)(N_Vector); 106 sunindextype (*nvgetlength)(N_Vector); 107 108 /* standard vector operations */ 109 void (*nvlinearsum)(realtype, N_Vector, realtype, N_Vector, N_Vector); 110 void (*nvconst)(realtype, N_Vector); 111 void (*nvprod)(N_Vector, N_Vector, N_Vector); 112 void (*nvdiv)(N_Vector, N_Vector, N_Vector); 113 void (*nvscale)(realtype, N_Vector, N_Vector); 114 void (*nvabs)(N_Vector, N_Vector); 115 void (*nvinv)(N_Vector, N_Vector); 116 void (*nvaddconst)(N_Vector, realtype, N_Vector); 117 realtype (*nvdotprod)(N_Vector, N_Vector); 118 realtype (*nvmaxnorm)(N_Vector); 119 realtype (*nvwrmsnorm)(N_Vector, N_Vector); 120 realtype (*nvwrmsnormmask)(N_Vector, N_Vector, N_Vector); 121 realtype (*nvmin)(N_Vector); 122 realtype (*nvwl2norm)(N_Vector, N_Vector); 123 realtype (*nvl1norm)(N_Vector); 124 void (*nvcompare)(realtype, N_Vector, N_Vector); 125 booleantype (*nvinvtest)(N_Vector, N_Vector); 126 booleantype (*nvconstrmask)(N_Vector, N_Vector, N_Vector); 127 realtype (*nvminquotient)(N_Vector, N_Vector); 128 129 /* fused vector operations */ 130 int (*nvlinearcombination)(int, realtype*, N_Vector*, N_Vector); 131 int (*nvscaleaddmulti)(int, realtype*, N_Vector, N_Vector*, N_Vector*); 132 int (*nvdotprodmulti)(int, N_Vector, N_Vector*, realtype*); 133 134 /* vector array operations */ 135 int (*nvlinearsumvectorarray)(int, realtype, N_Vector*, realtype, N_Vector*, 136 N_Vector*); 137 int (*nvscalevectorarray)(int, realtype*, N_Vector*, N_Vector*); 138 int (*nvconstvectorarray)(int, realtype, N_Vector*); 139 int (*nvwrmsnormvectorarray)(int, N_Vector*, N_Vector*, realtype*); 140 int (*nvwrmsnormmaskvectorarray)(int, N_Vector*, N_Vector*, N_Vector, realtype*); 141 int (*nvscaleaddmultivectorarray)(int, int, realtype*, N_Vector*, N_Vector**, N_Vector**); 142 int (*nvlinearcombinationvectorarray)(int, int, realtype*, N_Vector**, N_Vector*); 143 144 /* OPTIONAL local reduction kernels (no parallel communication) */ 145 realtype (*nvdotprodlocal)(N_Vector, N_Vector); 146 realtype (*nvmaxnormlocal)(N_Vector); 147 realtype (*nvminlocal)(N_Vector); 148 realtype (*nvl1normlocal)(N_Vector); 149 booleantype (*nvinvtestlocal)(N_Vector, N_Vector); 150 booleantype (*nvconstrmasklocal)(N_Vector, N_Vector, N_Vector); 151 realtype (*nvminquotientlocal)(N_Vector, N_Vector); 152 realtype (*nvwsqrsumlocal)(N_Vector, N_Vector); 153 realtype (*nvwsqrsummasklocal)(N_Vector, N_Vector, N_Vector); 154 155 /* OPTIONAL XBraid interface operations */ 156 int (*nvbufsize)(N_Vector, sunindextype*); 157 int (*nvbufpack)(N_Vector, void*); 158 int (*nvbufunpack)(N_Vector, void*); 159 160 /* debugging functions (called when SUNDIALS_DEBUG_PRINTVEC is defined) */ 161 void (*nvprint)(N_Vector); 162 void (*nvprintfile)(N_Vector, FILE*); 163 }; 164 165 /* A vector is a structure with an implementation-dependent 166 'content' field, and a pointer to a structure of vector 167 operations corresponding to that implementation. */ 168 struct _generic_N_Vector { 169 void *content; 170 N_Vector_Ops ops; 171 }; 172 173 174 /* ----------------------------------------------------------------- 175 * Functions exported by NVECTOR module 176 * ----------------------------------------------------------------- */ 177 178 SUNDIALS_EXPORT N_Vector N_VNewEmpty(); 179 SUNDIALS_EXPORT void N_VFreeEmpty(N_Vector v); 180 SUNDIALS_EXPORT int N_VCopyOps(N_Vector w, N_Vector v); 181 182 SUNDIALS_EXPORT N_Vector_ID N_VGetVectorID(N_Vector w); 183 SUNDIALS_EXPORT N_Vector N_VClone(N_Vector w); 184 SUNDIALS_EXPORT N_Vector N_VCloneEmpty(N_Vector w); 185 SUNDIALS_EXPORT void N_VDestroy(N_Vector v); 186 SUNDIALS_EXPORT void N_VSpace(N_Vector v, sunindextype *lrw, sunindextype *liw); 187 SUNDIALS_EXPORT realtype *N_VGetArrayPointer(N_Vector v); 188 SUNDIALS_EXPORT realtype *N_VGetDeviceArrayPointer(N_Vector v); 189 SUNDIALS_EXPORT void N_VSetArrayPointer(realtype *v_data, N_Vector v); 190 SUNDIALS_EXPORT void *N_VGetCommunicator(N_Vector v); 191 SUNDIALS_EXPORT sunindextype N_VGetLength(N_Vector v); 192 193 /* standard vector operations */ 194 SUNDIALS_EXPORT void N_VLinearSum(realtype a, N_Vector x, realtype b, 195 N_Vector y, N_Vector z); 196 SUNDIALS_EXPORT void N_VConst(realtype c, N_Vector z); 197 SUNDIALS_EXPORT void N_VProd(N_Vector x, N_Vector y, N_Vector z); 198 SUNDIALS_EXPORT void N_VDiv(N_Vector x, N_Vector y, N_Vector z); 199 SUNDIALS_EXPORT void N_VScale(realtype c, N_Vector x, N_Vector z); 200 SUNDIALS_EXPORT void N_VAbs(N_Vector x, N_Vector z); 201 SUNDIALS_EXPORT void N_VInv(N_Vector x, N_Vector z); 202 SUNDIALS_EXPORT void N_VAddConst(N_Vector x, realtype b, N_Vector z); 203 SUNDIALS_EXPORT realtype N_VDotProd(N_Vector x, N_Vector y); 204 SUNDIALS_EXPORT realtype N_VMaxNorm(N_Vector x); 205 SUNDIALS_EXPORT realtype N_VWrmsNorm(N_Vector x, N_Vector w); 206 SUNDIALS_EXPORT realtype N_VWrmsNormMask(N_Vector x, N_Vector w, N_Vector id); 207 SUNDIALS_EXPORT realtype N_VMin(N_Vector x); 208 SUNDIALS_EXPORT realtype N_VWL2Norm(N_Vector x, N_Vector w); 209 SUNDIALS_EXPORT realtype N_VL1Norm(N_Vector x); 210 SUNDIALS_EXPORT void N_VCompare(realtype c, N_Vector x, N_Vector z); 211 SUNDIALS_EXPORT booleantype N_VInvTest(N_Vector x, N_Vector z); 212 SUNDIALS_EXPORT booleantype N_VConstrMask(N_Vector c, N_Vector x, N_Vector m); 213 SUNDIALS_EXPORT realtype N_VMinQuotient(N_Vector num, N_Vector denom); 214 215 /* OPTIONAL fused vector operations */ 216 SUNDIALS_EXPORT int N_VLinearCombination(int nvec, realtype* c, N_Vector* X, 217 N_Vector z); 218 219 SUNDIALS_EXPORT int N_VScaleAddMulti(int nvec, realtype* a, N_Vector x, 220 N_Vector* Y, N_Vector* Z); 221 222 SUNDIALS_EXPORT int N_VDotProdMulti(int nvec, N_Vector x, N_Vector* Y, 223 realtype* dotprods); 224 225 /* OPTIONAL vector array operations */ 226 SUNDIALS_EXPORT int N_VLinearSumVectorArray(int nvec, 227 realtype a, N_Vector* X, 228 realtype b, N_Vector* Y, 229 N_Vector* Z); 230 231 SUNDIALS_EXPORT int N_VScaleVectorArray(int nvec, realtype* c, N_Vector* X, 232 N_Vector* Z); 233 234 SUNDIALS_EXPORT int N_VConstVectorArray(int nvec, realtype c, N_Vector* Z); 235 236 SUNDIALS_EXPORT int N_VWrmsNormVectorArray(int nvec, N_Vector* X, N_Vector* W, 237 realtype* nrm); 238 239 SUNDIALS_EXPORT int N_VWrmsNormMaskVectorArray(int nvec, N_Vector* X, 240 N_Vector* W, N_Vector id, 241 realtype* nrm); 242 243 SUNDIALS_EXPORT int N_VScaleAddMultiVectorArray(int nvec, int nsum, 244 realtype* a, N_Vector* X, 245 N_Vector** Y, N_Vector** Z); 246 247 SUNDIALS_EXPORT int N_VLinearCombinationVectorArray(int nvec, int nsum, 248 realtype* c, N_Vector** X, 249 N_Vector* Z); 250 251 /* OPTIONAL local reduction kernels (no parallel communication) */ 252 SUNDIALS_EXPORT realtype N_VDotProdLocal(N_Vector x, N_Vector y); 253 SUNDIALS_EXPORT realtype N_VMaxNormLocal(N_Vector x); 254 SUNDIALS_EXPORT realtype N_VMinLocal(N_Vector x); 255 SUNDIALS_EXPORT realtype N_VL1NormLocal(N_Vector x); 256 SUNDIALS_EXPORT realtype N_VWSqrSumLocal(N_Vector x, N_Vector w); 257 SUNDIALS_EXPORT realtype N_VWSqrSumMaskLocal(N_Vector x, N_Vector w, N_Vector id); 258 SUNDIALS_EXPORT booleantype N_VInvTestLocal(N_Vector x, N_Vector z); 259 SUNDIALS_EXPORT booleantype N_VConstrMaskLocal(N_Vector c, N_Vector x, N_Vector m); 260 SUNDIALS_EXPORT realtype N_VMinQuotientLocal(N_Vector num, N_Vector denom); 261 262 /* OPTIONAL XBraid interface operations */ 263 SUNDIALS_EXPORT int N_VBufSize(N_Vector x, sunindextype *size); 264 SUNDIALS_EXPORT int N_VBufPack(N_Vector x, void *buf); 265 SUNDIALS_EXPORT int N_VBufUnpack(N_Vector x, void *buf); 266 267 /* ----------------------------------------------------------------- 268 * Additional functions exported by NVECTOR module 269 * ----------------------------------------------------------------- */ 270 271 SUNDIALS_EXPORT N_Vector* N_VNewVectorArray(int count); 272 SUNDIALS_EXPORT N_Vector* N_VCloneEmptyVectorArray(int count, N_Vector w); 273 SUNDIALS_EXPORT N_Vector* N_VCloneVectorArray(int count, N_Vector w); 274 SUNDIALS_EXPORT void N_VDestroyVectorArray(N_Vector* vs, int count); 275 276 /* These function are really only for users of the Fortran interface */ 277 SUNDIALS_EXPORT N_Vector N_VGetVecAtIndexVectorArray(N_Vector* vs, int index); 278 SUNDIALS_EXPORT void N_VSetVecAtIndexVectorArray(N_Vector* vs, int index, N_Vector w); 279 280 281 /* ----------------------------------------------------------------- 282 * Debugging functions 283 * ----------------------------------------------------------------- */ 284 285 SUNDIALS_EXPORT void N_VPrint(N_Vector v); 286 SUNDIALS_EXPORT void N_VPrintFile(N_Vector v, FILE* outfile); 287 288 289 #ifdef __cplusplus 290 } 291 #endif 292 293 #endif 294