1 /// Copyright (c) 2017-2025, Lawrence Livermore National Security, LLC and other CEED contributors. 2 /// All Rights Reserved. See the top-level LICENSE and NOTICE files for details. 3 /// 4 /// SPDX-License-Identifier: BSD-2-Clause 5 /// 6 /// This file is part of CEED: http://github.com/ceed 7 8 /// @file 9 /// Public header for user and utility components of libCEED 10 #pragma once 11 12 /// @defgroup Ceed Ceed: core components 13 /// @defgroup CeedVector CeedVector: storing and manipulating vectors 14 /// @defgroup CeedElemRestriction CeedElemRestriction: restriction from local vectors to elements 15 /// @defgroup CeedBasis CeedBasis: fully discrete finite element-like objects 16 /// @defgroup CeedQFunction CeedQFunction: independent operations at quadrature points 17 /// @defgroup CeedOperator CeedOperator: composed FE-type operations on vectors 18 /// 19 /// @page FunctionCategories libCEED: Types of Functions libCEED provides three different header files depending upon the type of functions a user 20 /// requires. 21 /// @section Utility Utility Functions 22 /// These functions are intended general utilities that may be useful to libCEED developers and users. 23 /// These functions can generally be found in `"ceed.h"`. 24 /// @section User User Functions 25 /// These functions are intended to be used by general users of libCEED and can generally be found in `"ceed.h"`. 26 /// @section Advanced Advanced Functions 27 /// These functions are intended to be used by advanced users of libCEED and can generally be found in `"ceed.h"`. 28 /// @section Backend Backend Developer Functions 29 /// These functions are intended to be used by backend developers of libCEED and can generally be found in `"ceed-backend.h"`. 30 /// @section Developer Library Developer Functions 31 /// These functions are intended to be used by library developers of libCEED and can generally be found in `"ceed-impl.h"`. 32 33 #if !defined(CEED_SKIP_VISIBILITY) 34 #define CEED_VISIBILITY(mode) __attribute__((visibility(#mode))) 35 #else 36 #define CEED_VISIBILITY(mode) 37 #endif 38 39 /* 40 CEED_EXTERN is used in this header to denote all publicly visible symbols. 41 42 No other file should declare publicly visible symbols, thus it should never be used outside `"ceed.h"`. 43 */ 44 #if defined(__clang_analyzer__) 45 #define CEED_EXTERN extern 46 #elif defined(__cplusplus) 47 #define CEED_EXTERN extern "C" CEED_VISIBILITY(default) 48 #else 49 #define CEED_EXTERN extern CEED_VISIBILITY(default) 50 #endif 51 52 #include <stdarg.h> 53 #include <stdbool.h> 54 #include <stdio.h> 55 56 /* 57 Typedefs and macros used in public interfaces and user `CeedQFunction` source 58 */ 59 #include "types.h" // IWYU pragma: export 60 61 /* 62 This line prevents IWYU from suggesting "ceed.h" 63 */ 64 // IWYU pragma: private, include <ceed.h> 65 66 /// Library context created by CeedInit() 67 /// @ingroup CeedUser 68 typedef struct Ceed_private *Ceed; 69 /// Non-blocking Ceed interfaces return a CeedRequest. 70 /// To perform an operation immediately, pass @ref CEED_REQUEST_IMMEDIATE instead. 71 /// @ingroup CeedUser 72 typedef struct CeedRequest_private *CeedRequest; 73 /// Handle for vectors over the field @ref CeedScalar 74 /// @ingroup CeedVectorUser 75 typedef struct CeedVector_private *CeedVector; 76 /// Handle for object describing restriction to elements 77 /// @ingroup CeedElemRestrictionUser 78 typedef struct CeedElemRestriction_private *CeedElemRestriction; 79 /// Handle for object describing discrete finite element evaluations 80 /// @ingroup CeedBasisUser 81 typedef struct CeedBasis_private *CeedBasis; 82 /// Handle for object describing CeedQFunction fields 83 /// @ingroup CeedQFunctionBackend 84 typedef struct CeedQFunctionField_private *CeedQFunctionField; 85 /// Handle for object describing functions evaluated independently at quadrature points 86 /// @ingroup CeedQFunctionUser 87 typedef struct CeedQFunction_private *CeedQFunction; 88 /// Handle for object describing CeedOperator fields 89 /// @ingroup CeedOperatorBackend 90 typedef struct CeedOperatorField_private *CeedOperatorField; 91 /// Handle for object describing context data for CeedQFunctions 92 /// @ingroup CeedQFunctionUser 93 typedef struct CeedQFunctionContext_private *CeedQFunctionContext; 94 /// Handle for object describing registered fields for CeedQFunctionContext 95 /// @ingroup CeedQFunctionUser 96 typedef struct CeedContextFieldLabel_private *CeedContextFieldLabel; 97 /// Handle for object describing FE-type operators acting on vectors 98 /// 99 /// Given an element restriction \f$E\f$, basis evaluator \f$B\f$, and quadrature function\f$f\f$, a `CeedOperator` expresses operations of the form \f$E^T B^T f(B E u)\f$ acting on the vector \f$u\f$. 100 /// @ingroup CeedOperatorUser 101 typedef struct CeedOperator_private *CeedOperator; 102 103 CEED_EXTERN int CeedRegistryGetList(size_t *n, char ***const resources, CeedInt **array); 104 CEED_EXTERN int CeedInit(const char *resource, Ceed *ceed); 105 CEED_EXTERN int CeedSetStream(Ceed ceed, void *handle); 106 CEED_EXTERN int CeedReferenceCopy(Ceed ceed, Ceed *ceed_copy); 107 CEED_EXTERN int CeedGetResource(Ceed ceed, const char **resource); 108 CEED_EXTERN int CeedIsDeterministic(Ceed ceed, bool *is_deterministic); 109 CEED_EXTERN int CeedAddJitSourceRoot(Ceed ceed, const char *jit_source_root); 110 CEED_EXTERN int CeedAddRustSourceRoot(Ceed ceed, const char *rust_source_root); 111 CEED_EXTERN int CeedAddJitDefine(Ceed ceed, const char *jit_define); 112 CEED_EXTERN int CeedView(Ceed ceed, FILE *stream); 113 CEED_EXTERN int CeedDestroy(Ceed *ceed); 114 CEED_EXTERN int CeedErrorImpl(Ceed ceed, const char *filename, int lineno, const char *func, int ecode, const char *format, ...); 115 116 /// Raise an error on `Ceed` object 117 /// 118 /// @param ceed `Ceed` library context or `NULL` 119 /// @param ecode Error code (int) 120 /// @param ... printf-style format string followed by arguments as needed 121 /// 122 /// @ingroup Ceed 123 /// @sa CeedSetErrorHandler() 124 #define CeedError(ceed, ecode, ...) (CeedErrorImpl((ceed), __FILE__, __LINE__, __func__, (ecode), __VA_ARGS__), (ecode)) 125 126 /// Ceed error handlers 127 typedef int (*CeedErrorHandler)(Ceed, const char *, int, const char *, int, const char *, va_list *); 128 CEED_EXTERN int CeedSetErrorHandler(Ceed ceed, CeedErrorHandler handler); 129 CEED_EXTERN int CeedGetErrorMessage(Ceed ceed, const char **err_msg); 130 CEED_EXTERN int CeedResetErrorMessage(Ceed ceed, const char **err_msg); 131 CEED_EXTERN int CeedErrorReturn(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args); 132 CEED_EXTERN int CeedErrorStore(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args); 133 CEED_EXTERN int CeedErrorAbort(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args); 134 CEED_EXTERN int CeedErrorExit(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args); 135 136 /// libCEED library version numbering 137 /// @ingroup Ceed 138 #define CEED_VERSION_MAJOR 0 139 #define CEED_VERSION_MINOR 12 140 #define CEED_VERSION_PATCH 0 141 #define CEED_VERSION_RELEASE false 142 143 /// Compile-time check that the the current library version is at least as recent as the specified version. 144 /// This macro is typically used in 145 /// @code 146 /// #if CEED_VERSION_GE(0, 8, 0) 147 /// code path that needs at least 0.8.0 148 /// #else 149 /// fallback code for older versions 150 /// #endif 151 /// @endcode 152 /// 153 /// A non-release version always compares as positive infinity. 154 /// 155 /// @param major Major version 156 /// @param minor Minor version 157 /// @param patch Patch (subminor) version 158 /// 159 /// @ingroup Ceed 160 /// @sa CeedGetVersion() 161 #define CEED_VERSION_GE(major, minor, patch) \ 162 (!CEED_VERSION_RELEASE || \ 163 (CEED_VERSION_MAJOR > major || \ 164 (CEED_VERSION_MAJOR == major && (CEED_VERSION_MINOR > minor || (CEED_VERSION_MINOR == minor && CEED_VERSION_PATCH >= patch))))) 165 166 CEED_EXTERN int CeedGetVersion(int *major, int *minor, int *patch, bool *release); 167 CEED_EXTERN int CeedGetGitVersion(const char **git_version); 168 CEED_EXTERN int CeedGetBuildConfiguration(const char **build_config); 169 170 CEED_EXTERN int CeedSetIsClang(Ceed ceed, bool isClang); 171 CEED_EXTERN int CeedGetIsClang(Ceed ceed, bool *isClang); 172 173 CEED_EXTERN int CeedGetScalarType(CeedScalarType *scalar_type); 174 175 /// String names for enum pretty printing 176 CEED_EXTERN const char *const *CeedErrorTypes; 177 CEED_EXTERN const char *const CeedMemTypes[]; 178 CEED_EXTERN const char *const CeedCopyModes[]; 179 CEED_EXTERN const char *const CeedTransposeModes[]; 180 CEED_EXTERN const char *const CeedEvalModes[]; 181 CEED_EXTERN const char *const CeedQuadModes[]; 182 CEED_EXTERN const char *const CeedElemTopologies[]; 183 CEED_EXTERN const char *const CeedContextFieldTypes[]; 184 185 CEED_EXTERN int CeedGetPreferredMemType(Ceed ceed, CeedMemType *type); 186 187 CEED_EXTERN int CeedVectorCreate(Ceed ceed, CeedSize len, CeedVector *vec); 188 CEED_EXTERN int CeedVectorReferenceCopy(CeedVector vec, CeedVector *vec_copy); 189 CEED_EXTERN int CeedVectorCopy(CeedVector vec, CeedVector vec_copy); 190 CEED_EXTERN int CeedVectorCopyStrided(CeedVector vec, CeedSize start, CeedSize stop, CeedSize step, CeedVector vec_copy); 191 CEED_EXTERN int CeedVectorSetArray(CeedVector vec, CeedMemType mem_type, CeedCopyMode copy_mode, CeedScalar *array); 192 CEED_EXTERN int CeedVectorSetValue(CeedVector vec, CeedScalar value); 193 CEED_EXTERN int CeedVectorSetValueStrided(CeedVector vec, CeedSize start, CeedSize stop, CeedSize step, CeedScalar value); 194 CEED_EXTERN int CeedVectorSyncArray(CeedVector vec, CeedMemType mem_type); 195 CEED_EXTERN int CeedVectorTakeArray(CeedVector vec, CeedMemType mem_type, CeedScalar **array); 196 CEED_EXTERN int CeedVectorGetArray(CeedVector vec, CeedMemType mem_type, CeedScalar **array); 197 CEED_EXTERN int CeedVectorGetArrayRead(CeedVector vec, CeedMemType mem_type, const CeedScalar **array); 198 CEED_EXTERN int CeedVectorGetArrayWrite(CeedVector vec, CeedMemType mem_type, CeedScalar **array); 199 CEED_EXTERN int CeedVectorRestoreArray(CeedVector vec, CeedScalar **array); 200 CEED_EXTERN int CeedVectorRestoreArrayRead(CeedVector vec, const CeedScalar **array); 201 CEED_EXTERN int CeedVectorNorm(CeedVector vec, CeedNormType type, CeedScalar *norm); 202 CEED_EXTERN int CeedVectorScale(CeedVector x, CeedScalar alpha); 203 CEED_EXTERN int CeedVectorAXPY(CeedVector y, CeedScalar alpha, CeedVector x); 204 CEED_EXTERN int CeedVectorAXPBY(CeedVector y, CeedScalar alpha, CeedScalar beta, CeedVector x); 205 CEED_EXTERN int CeedVectorPointwiseMult(CeedVector w, CeedVector x, CeedVector y); 206 CEED_EXTERN int CeedVectorReciprocal(CeedVector vec); 207 CEED_EXTERN int CeedVectorViewRange(CeedVector vec, CeedSize start, CeedSize stop, CeedInt step, const char *fp_fmt, FILE *stream); 208 CEED_EXTERN int CeedVectorView(CeedVector vec, const char *fp_fmt, FILE *stream); 209 CEED_EXTERN int CeedVectorGetCeed(CeedVector vec, Ceed *ceed); 210 CEED_EXTERN Ceed CeedVectorReturnCeed(CeedVector vec); 211 CEED_EXTERN int CeedVectorGetLength(CeedVector vec, CeedSize *length); 212 CEED_EXTERN int CeedVectorDestroy(CeedVector *vec); 213 214 CEED_EXTERN CeedRequest *const CEED_REQUEST_IMMEDIATE; 215 CEED_EXTERN CeedRequest *const CEED_REQUEST_ORDERED; 216 CEED_EXTERN int CeedRequestWait(CeedRequest *req); 217 218 /// Argument for @ref CeedOperatorSetField() to use active input or output. 219 /// @ingroup CeedVector 220 CEED_EXTERN const CeedVector CEED_VECTOR_ACTIVE; 221 222 /// Argument for @ref CeedOperatorSetField() to use no `CeedVector`. 223 /// Only use this option with @ref CeedEvalMode @ref CEED_EVAL_WEIGHT. 224 /// @ingroup CeedVector 225 CEED_EXTERN const CeedVector CEED_VECTOR_NONE; 226 227 /// Argument for @ref CeedOperatorSetField() that no basis operation is needed to translate between the E-vector and the Q-vector. 228 /// Only use this option with @ref CeedEvalMode @ref CEED_EVAL_NONE. 229 /// @ingroup CeedBasis 230 CEED_EXTERN const CeedBasis CEED_BASIS_NONE; 231 232 /// Argument for @ref CeedOperatorSetField() to use no `CeedElemRestriction`. 233 /// Only use this option with @ref CeedEvalMode @ref CEED_EVAL_WEIGHT. 234 /// @ingroup CeedElemRestriction 235 CEED_EXTERN const CeedElemRestriction CEED_ELEMRESTRICTION_NONE; 236 237 /// Argument for @ref CeedOperatorCreate() that `CeedQFunction` is not created by user. 238 /// Only used for `CeedQFunction` `dqf` and `dqfT`. 239 /// If implemented, a backend may attempt to provide the action of these `CeedQFunction`. 240 /// @ingroup CeedQFunction 241 CEED_EXTERN const CeedQFunction CEED_QFUNCTION_NONE; 242 243 /// Argument for @ref CeedElemRestrictionCreateStrided() that L-vector is in the Ceed backend's preferred layout. 244 /// This argument should only be used with vectors created by a Ceed backend. 245 /// @ingroup CeedElemRestriction 246 CEED_EXTERN const CeedInt CEED_STRIDES_BACKEND[3]; 247 248 CEED_EXTERN int CeedElemRestrictionCreate(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride, CeedSize l_size, 249 CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, CeedElemRestriction *rstr); 250 CEED_EXTERN int CeedElemRestrictionCreateOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride, 251 CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, 252 const bool *orients, CeedElemRestriction *rstr); 253 CEED_EXTERN int CeedElemRestrictionCreateCurlOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride, 254 CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, 255 const CeedInt8 *curl_orients, CeedElemRestriction *rstr); 256 CEED_EXTERN int CeedElemRestrictionCreateStrided(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedSize l_size, 257 const CeedInt strides[3], CeedElemRestriction *rstr); 258 CEED_EXTERN int CeedElemRestrictionCreateAtPoints(Ceed ceed, CeedInt num_elem, CeedInt num_points, CeedInt num_comp, CeedSize l_size, 259 CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, CeedElemRestriction *rstr); 260 CEED_EXTERN int CeedElemRestrictionCreateBlocked(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp, 261 CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, 262 const CeedInt *offsets, CeedElemRestriction *rstr); 263 CEED_EXTERN int CeedElemRestrictionCreateBlockedOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp, 264 CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, 265 const CeedInt *offsets, const bool *orients, CeedElemRestriction *rstr); 266 CEED_EXTERN int CeedElemRestrictionCreateBlockedCurlOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp, 267 CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, 268 const CeedInt *offsets, const CeedInt8 *curl_orients, CeedElemRestriction *rstr); 269 CEED_EXTERN int CeedElemRestrictionCreateBlockedStrided(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp, 270 CeedSize l_size, const CeedInt strides[3], CeedElemRestriction *rstr); 271 CEED_EXTERN int CeedElemRestrictionCreateUnsignedCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_unsigned); 272 CEED_EXTERN int CeedElemRestrictionCreateUnorientedCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_unoriented); 273 CEED_EXTERN int CeedElemRestrictionReferenceCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_copy); 274 CEED_EXTERN int CeedElemRestrictionCreateVector(CeedElemRestriction rstr, CeedVector *lvec, CeedVector *evec); 275 CEED_EXTERN int CeedElemRestrictionApply(CeedElemRestriction rstr, CeedTransposeMode t_mode, CeedVector u, CeedVector ru, CeedRequest *request); 276 CEED_EXTERN int CeedElemRestrictionApplyAtPointsInElement(CeedElemRestriction rstr, CeedInt elem, CeedTransposeMode t_mode, CeedVector u, 277 CeedVector ru, CeedRequest *request); 278 CEED_EXTERN int CeedElemRestrictionApplyBlock(CeedElemRestriction rstr, CeedInt block, CeedTransposeMode t_mode, CeedVector u, CeedVector ru, 279 CeedRequest *request); 280 CEED_EXTERN int CeedElemRestrictionGetCeed(CeedElemRestriction rstr, Ceed *ceed); 281 CEED_EXTERN Ceed CeedElemRestrictionReturnCeed(CeedElemRestriction rstr); 282 CEED_EXTERN int CeedElemRestrictionGetCompStride(CeedElemRestriction rstr, CeedInt *comp_stride); 283 CEED_EXTERN int CeedElemRestrictionGetNumElements(CeedElemRestriction rstr, CeedInt *num_elem); 284 CEED_EXTERN int CeedElemRestrictionGetElementSize(CeedElemRestriction rstr, CeedInt *elem_size); 285 CEED_EXTERN int CeedElemRestrictionGetNumPoints(CeedElemRestriction rstr, CeedInt *num_points); 286 CEED_EXTERN int CeedElemRestrictionGetNumPointsInElement(CeedElemRestriction rstr, CeedInt elem, CeedInt *num_points); 287 CEED_EXTERN int CeedElemRestrictionGetMaxPointsInElement(CeedElemRestriction rstr, CeedInt *max_points); 288 CEED_EXTERN int CeedElemRestrictionGetMinPointsInElement(CeedElemRestriction rstr, CeedInt *min_points); 289 CEED_EXTERN int CeedElemRestrictionGetMinMaxPointsInElement(CeedElemRestriction rstr, CeedInt *min_points, CeedInt *max_points); 290 CEED_EXTERN int CeedElemRestrictionGetLVectorSize(CeedElemRestriction rstr, CeedSize *l_size); 291 CEED_EXTERN int CeedElemRestrictionGetEVectorSize(CeedElemRestriction rstr, CeedSize *e_size); 292 CEED_EXTERN int CeedElemRestrictionGetNumComponents(CeedElemRestriction rstr, CeedInt *num_comp); 293 CEED_EXTERN int CeedElemRestrictionGetNumBlocks(CeedElemRestriction rstr, CeedInt *num_block); 294 CEED_EXTERN int CeedElemRestrictionGetBlockSize(CeedElemRestriction rstr, CeedInt *block_size); 295 CEED_EXTERN int CeedElemRestrictionGetMultiplicity(CeedElemRestriction rstr, CeedVector mult); 296 CEED_EXTERN int CeedElemRestrictionView(CeedElemRestriction rstr, FILE *stream); 297 CEED_EXTERN int CeedElemRestrictionDestroy(CeedElemRestriction *rstr); 298 299 // The formalism here is that we have the structure 300 // \int_\Omega v^T f_0(u, \nabla u, qdata) + (\nabla v)^T f_1(u, \nabla u, qdata) 301 // where gradients are with respect to the reference element. 302 303 CEED_EXTERN int CeedBasisCreateTensorH1Lagrange(Ceed ceed, CeedInt dim, CeedInt num_comp, CeedInt P, CeedInt Q, CeedQuadMode quad_mode, 304 CeedBasis *basis); 305 CEED_EXTERN int CeedBasisCreateTensorH1(Ceed ceed, CeedInt dim, CeedInt num_comp, CeedInt P_1d, CeedInt Q_1d, const CeedScalar *interp_1d, 306 const CeedScalar *grad_1d, const CeedScalar *q_ref_1d, const CeedScalar *q_weight_1d, CeedBasis *basis); 307 CEED_EXTERN int CeedBasisCreateH1(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt nqpts, const CeedScalar *interp, 308 const CeedScalar *grad, const CeedScalar *q_ref, const CeedScalar *q_weights, CeedBasis *basis); 309 CEED_EXTERN int CeedBasisCreateHdiv(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt nqpts, const CeedScalar *interp, 310 const CeedScalar *div, const CeedScalar *q_ref, const CeedScalar *q_weights, CeedBasis *basis); 311 CEED_EXTERN int CeedBasisCreateHcurl(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt nqpts, const CeedScalar *interp, 312 const CeedScalar *curl, const CeedScalar *q_ref, const CeedScalar *q_weights, CeedBasis *basis); 313 CEED_EXTERN int CeedBasisCreateProjection(CeedBasis basis_from, CeedBasis basis_to, CeedBasis *basis_project); 314 CEED_EXTERN int CeedBasisReferenceCopy(CeedBasis basis, CeedBasis *basis_copy); 315 CEED_EXTERN int CeedBasisView(CeedBasis basis, FILE *stream); 316 CEED_EXTERN int CeedBasisApply(CeedBasis basis, CeedInt num_elem, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedVector u, CeedVector v); 317 CEED_EXTERN int CeedBasisApplyAdd(CeedBasis basis, CeedInt num_elem, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedVector u, CeedVector v); 318 CEED_EXTERN int CeedBasisApplyAtPoints(CeedBasis basis, CeedInt num_elem, const CeedInt *num_points, CeedTransposeMode t_mode, CeedEvalMode eval_mode, 319 CeedVector x_ref, CeedVector u, CeedVector v); 320 CEED_EXTERN int CeedBasisApplyAddAtPoints(CeedBasis basis, CeedInt num_elem, const CeedInt *num_points, CeedTransposeMode t_mode, 321 CeedEvalMode eval_mode, CeedVector x_ref, CeedVector u, CeedVector v); 322 CEED_EXTERN int CeedBasisGetCeed(CeedBasis basis, Ceed *ceed); 323 CEED_EXTERN Ceed CeedBasisReturnCeed(CeedBasis basis); 324 CEED_EXTERN int CeedBasisGetDimension(CeedBasis basis, CeedInt *dim); 325 CEED_EXTERN int CeedBasisGetTopology(CeedBasis basis, CeedElemTopology *topo); 326 CEED_EXTERN int CeedBasisGetNumComponents(CeedBasis basis, CeedInt *num_comp); 327 CEED_EXTERN int CeedBasisGetNumNodes(CeedBasis basis, CeedInt *P); 328 CEED_EXTERN int CeedBasisGetNumNodes1D(CeedBasis basis, CeedInt *P_1d); 329 CEED_EXTERN int CeedBasisGetNumQuadraturePoints(CeedBasis basis, CeedInt *Q); 330 CEED_EXTERN int CeedBasisGetNumQuadraturePoints1D(CeedBasis basis, CeedInt *Q_1d); 331 CEED_EXTERN int CeedBasisGetQRef(CeedBasis basis, const CeedScalar **q_ref); 332 CEED_EXTERN int CeedBasisGetQWeights(CeedBasis basis, const CeedScalar **q_weights); 333 CEED_EXTERN int CeedBasisGetInterp(CeedBasis basis, const CeedScalar **interp); 334 CEED_EXTERN int CeedBasisGetInterp1D(CeedBasis basis, const CeedScalar **interp_1d); 335 CEED_EXTERN int CeedBasisGetGrad(CeedBasis basis, const CeedScalar **grad); 336 CEED_EXTERN int CeedBasisGetGrad1D(CeedBasis basis, const CeedScalar **grad_1d); 337 CEED_EXTERN int CeedBasisGetDiv(CeedBasis basis, const CeedScalar **div); 338 CEED_EXTERN int CeedBasisGetCurl(CeedBasis basis, const CeedScalar **curl); 339 CEED_EXTERN int CeedBasisDestroy(CeedBasis *basis); 340 341 CEED_EXTERN int CeedGaussQuadrature(CeedInt Q, CeedScalar *q_ref_1d, CeedScalar *q_weight_1d); 342 CEED_EXTERN int CeedLobattoQuadrature(CeedInt Q, CeedScalar *q_ref_1d, CeedScalar *q_weight_1d); 343 344 /** Handle for the user provided `CeedQFunction` callback function 345 346 @param[in,out] ctx User-defined context set using @ref CeedQFunctionSetContext() or `NULL` 347 @param[in] Q Number of quadrature points at which to evaluate 348 @param[in] in Array of pointers to each input argument in the order provided by the user in @ref CeedQFunctionAddInput(). 349 Each array has shape `[dim, num_comp, Q]` where `dim` is the geometric dimension for @ref CEED_EVAL_GRAD (`dim=1` for @ref CEED_EVAL_INTERP) and `num_comp` is the number of field components (`num_comp=1` for scalar fields). 350 This results in indexing the `i`th input at quadrature point `j` as `in[i][(d*num_comp + c)*Q + j]`. 351 @param[out] out Array of pointers to each output array in the order provided using @ref CeedQFunctionAddOutput(). 352 The shapes are as above for `in`. 353 354 @return An error code: 0 - success, otherwise - failure 355 356 @ingroup CeedQFunction 357 **/ 358 typedef int (*CeedQFunctionUser)(void *ctx, const CeedInt Q, const CeedScalar *const *in, CeedScalar *const *out); 359 360 CEED_EXTERN int CeedQFunctionCreateInterior(Ceed ceed, CeedInt vec_length, CeedQFunctionUser f, const char *source, CeedQFunction *qf); 361 CEED_EXTERN int CeedQFunctionCreateInteriorByName(Ceed ceed, const char *name, CeedQFunction *qf); 362 CEED_EXTERN int CeedQFunctionCreateIdentity(Ceed ceed, CeedInt size, CeedEvalMode in_mode, CeedEvalMode out_mode, CeedQFunction *qf); 363 CEED_EXTERN int CeedQFunctionReferenceCopy(CeedQFunction qf, CeedQFunction *qf_copy); 364 CEED_EXTERN int CeedQFunctionAddInput(CeedQFunction qf, const char *field_name, CeedInt size, CeedEvalMode eval_mode); 365 CEED_EXTERN int CeedQFunctionAddOutput(CeedQFunction qf, const char *field_name, CeedInt size, CeedEvalMode eval_mode); 366 CEED_EXTERN int CeedQFunctionGetFields(CeedQFunction qf, CeedInt *num_input_fields, CeedQFunctionField **input_fields, CeedInt *num_output_fields, 367 CeedQFunctionField **output_fields); 368 CEED_EXTERN int CeedQFunctionSetContext(CeedQFunction qf, CeedQFunctionContext ctx); 369 CEED_EXTERN int CeedQFunctionSetContextWritable(CeedQFunction qf, bool is_writable); 370 CEED_EXTERN int CeedQFunctionSetUserFlopsEstimate(CeedQFunction qf, CeedSize flops); 371 CEED_EXTERN int CeedQFunctionView(CeedQFunction qf, FILE *stream); 372 CEED_EXTERN int CeedQFunctionGetCeed(CeedQFunction qf, Ceed *ceed); 373 CEED_EXTERN Ceed CeedQFunctionReturnCeed(CeedQFunction qf); 374 CEED_EXTERN int CeedQFunctionApply(CeedQFunction qf, CeedInt Q, CeedVector *u, CeedVector *v); 375 CEED_EXTERN int CeedQFunctionDestroy(CeedQFunction *qf); 376 CEED_EXTERN int CeedQFunctionFieldGetName(CeedQFunctionField qf_field, const char **field_name); 377 CEED_EXTERN int CeedQFunctionFieldGetSize(CeedQFunctionField qf_field, CeedInt *size); 378 CEED_EXTERN int CeedQFunctionFieldGetEvalMode(CeedQFunctionField qf_field, CeedEvalMode *eval_mode); 379 CEED_EXTERN int CeedQFunctionFieldGetData(CeedQFunctionField qf_field, const char **field_name, CeedInt *size, CeedEvalMode *eval_mode); 380 381 /** Handle for the user provided @ref CeedQFunctionContextDestroy() callback function 382 383 @param[in,out] data User `CeedQFunctionContext` data 384 385 @return An error code: 0 - success, otherwise - failure 386 387 @ingroup CeedQFunction 388 **/ 389 typedef int (*CeedQFunctionContextDataDestroyUser)(void *data); 390 391 CEED_EXTERN int CeedQFunctionContextCreate(Ceed ceed, CeedQFunctionContext *ctx); 392 CEED_EXTERN int CeedQFunctionContextReferenceCopy(CeedQFunctionContext ctx, CeedQFunctionContext *ctx_copy); 393 CEED_EXTERN int CeedQFunctionContextSetData(CeedQFunctionContext ctx, CeedMemType mem_type, CeedCopyMode copy_mode, size_t size, void *data); 394 CEED_EXTERN int CeedQFunctionContextTakeData(CeedQFunctionContext ctx, CeedMemType mem_type, void *data); 395 CEED_EXTERN int CeedQFunctionContextGetData(CeedQFunctionContext ctx, CeedMemType mem_type, void *data); 396 CEED_EXTERN int CeedQFunctionContextGetDataRead(CeedQFunctionContext ctx, CeedMemType mem_type, void *data); 397 CEED_EXTERN int CeedQFunctionContextRestoreData(CeedQFunctionContext ctx, void *data); 398 CEED_EXTERN int CeedQFunctionContextRestoreDataRead(CeedQFunctionContext ctx, void *data); 399 CEED_EXTERN int CeedQFunctionContextRegisterDouble(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values, 400 const char *field_description); 401 CEED_EXTERN int CeedQFunctionContextRegisterInt32(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values, 402 const char *field_description); 403 CEED_EXTERN int CeedQFunctionContextRegisterBoolean(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values, 404 const char *field_description); 405 CEED_EXTERN int CeedQFunctionContextGetAllFieldLabels(CeedQFunctionContext ctx, const CeedContextFieldLabel **field_labels, CeedInt *num_fields); 406 CEED_EXTERN int CeedContextFieldLabelGetDescription(CeedContextFieldLabel label, const char **field_name, size_t *field_offset, size_t *num_values, 407 const char **field_description, CeedContextFieldType *field_type); 408 CEED_EXTERN int CeedQFunctionContextGetContextSize(CeedQFunctionContext ctx, size_t *ctx_size); 409 CEED_EXTERN int CeedQFunctionContextView(CeedQFunctionContext ctx, FILE *stream); 410 CEED_EXTERN int CeedQFunctionContextSetDataDestroy(CeedQFunctionContext ctx, CeedMemType f_mem_type, CeedQFunctionContextDataDestroyUser f); 411 CEED_EXTERN int CeedQFunctionContextDestroy(CeedQFunctionContext *ctx); 412 413 CEED_EXTERN int CeedOperatorCreate(Ceed ceed, CeedQFunction qf, CeedQFunction dqf, CeedQFunction dqfT, CeedOperator *op); 414 CEED_EXTERN int CeedOperatorCreateAtPoints(Ceed ceed, CeedQFunction qf, CeedQFunction dqf, CeedQFunction dqfT, CeedOperator *op); 415 CEED_EXTERN int CeedOperatorCreateComposite(Ceed ceed, CeedOperator *op); 416 CEED_EXTERN int CeedOperatorReferenceCopy(CeedOperator op, CeedOperator *op_copy); 417 CEED_EXTERN int CeedOperatorSetField(CeedOperator op, const char *field_name, CeedElemRestriction rstr, CeedBasis basis, CeedVector vec); 418 CEED_EXTERN int CeedOperatorGetFields(CeedOperator op, CeedInt *num_input_fields, CeedOperatorField **input_fields, CeedInt *num_output_fields, 419 CeedOperatorField **output_fields); 420 421 CEED_EXTERN int CeedOperatorAtPointsSetPoints(CeedOperator op, CeedElemRestriction rstr_points, CeedVector point_coords); 422 CEED_EXTERN int CeedOperatorAtPointsGetPoints(CeedOperator op, CeedElemRestriction *rstr_points, CeedVector *point_coords); 423 CEED_EXTERN int CeedOperatorIsAtPoints(CeedOperator op, bool *is_at_points); 424 CEED_EXTERN int CeedOperatorCompositeAddSub(CeedOperator composite_op, CeedOperator sub_op); 425 CEED_EXTERN int CeedOperatorCompositeGetNumSub(CeedOperator op, CeedInt *num_suboperators); 426 CEED_EXTERN int CeedOperatorCompositeGetSubList(CeedOperator op, CeedOperator **sub_operators); 427 CEED_EXTERN int CeedOperatorCompositeGetSubByName(CeedOperator op, const char *op_name, CeedOperator *sub_op); 428 CEED_EXTERN int CeedOperatorCheckReady(CeedOperator op); 429 CEED_EXTERN int CeedOperatorGetActiveVectorLengths(CeedOperator op, CeedSize *input_size, CeedSize *output_size); 430 CEED_EXTERN int CeedOperatorSetQFunctionAssemblyReuse(CeedOperator op, bool reuse_assembly_data); 431 CEED_EXTERN int CeedOperatorSetQFunctionAssemblyDataUpdateNeeded(CeedOperator op, bool needs_data_update); 432 CEED_EXTERN int CeedOperatorLinearAssembleQFunction(CeedOperator op, CeedVector *assembled, CeedElemRestriction *rstr, CeedRequest *request); 433 CEED_EXTERN int CeedOperatorLinearAssembleQFunctionBuildOrUpdate(CeedOperator op, CeedVector *assembled, CeedElemRestriction *rstr, 434 CeedRequest *request); 435 CEED_EXTERN int CeedOperatorLinearAssembleDiagonal(CeedOperator op, CeedVector assembled, CeedRequest *request); 436 CEED_EXTERN int CeedOperatorLinearAssembleAddDiagonal(CeedOperator op, CeedVector assembled, CeedRequest *request); 437 CEED_EXTERN int CeedOperatorLinearAssemblePointBlockDiagonal(CeedOperator op, CeedVector assembled, CeedRequest *request); 438 CEED_EXTERN int CeedOperatorLinearAssembleAddPointBlockDiagonal(CeedOperator op, CeedVector assembled, CeedRequest *request); 439 CEED_EXTERN int CeedOperatorLinearAssemblePointBlockDiagonalSymbolic(CeedOperator op, CeedSize *num_entries, CeedInt **rows, CeedInt **cols); 440 CEED_EXTERN int CeedOperatorLinearAssembleSymbolic(CeedOperator op, CeedSize *num_entries, CeedInt **rows, CeedInt **cols); 441 CEED_EXTERN int CeedOperatorLinearAssembleGetNumEntries(CeedOperator op, CeedSize *num_entries); 442 CEED_EXTERN int CeedOperatorLinearAssemble(CeedOperator op, CeedVector values); 443 CEED_EXTERN int CeedOperatorCompositeGetMultiplicity(CeedOperator op, CeedInt num_skip_indices, CeedInt *skip_indices, CeedVector mult); 444 CEED_EXTERN int CeedOperatorMultigridLevelCreate(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse, 445 CeedBasis basis_coarse, CeedOperator *op_coarse, CeedOperator *op_prolong, 446 CeedOperator *op_restrict); 447 CEED_EXTERN int CeedOperatorMultigridLevelCreateTensorH1(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse, 448 CeedBasis basis_coarse, const CeedScalar *interp_c_to_f, CeedOperator *op_coarse, 449 CeedOperator *op_prolong, CeedOperator *op_restrict); 450 CEED_EXTERN int CeedOperatorMultigridLevelCreateH1(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse, 451 CeedBasis basis_coarse, const CeedScalar *interp_c_to_f, CeedOperator *op_coarse, 452 CeedOperator *op_prolong, CeedOperator *op_restrict); 453 CEED_EXTERN int CeedOperatorCreateFDMElementInverse(CeedOperator op, CeedOperator *fdm_inv, CeedRequest *request); 454 CEED_EXTERN int CeedOperatorSetName(CeedOperator op, const char *name); 455 CEED_EXTERN int CeedOperatorGetName(CeedOperator op, const char **name); 456 CEED_EXTERN int CeedOperatorSetNumViewTabs(CeedOperator op, CeedInt num_tabs); 457 CEED_EXTERN int CeedOperatorView(CeedOperator op, FILE *stream); 458 CEED_EXTERN int CeedOperatorViewTerse(CeedOperator op, FILE *stream); 459 CEED_EXTERN int CeedOperatorGetCeed(CeedOperator op, Ceed *ceed); 460 CEED_EXTERN Ceed CeedOperatorReturnCeed(CeedOperator op); 461 CEED_EXTERN int CeedOperatorGetNumElements(CeedOperator op, CeedInt *num_elem); 462 CEED_EXTERN int CeedOperatorGetNumQuadraturePoints(CeedOperator op, CeedInt *num_qpts); 463 CEED_EXTERN int CeedOperatorGetFlopsEstimate(CeedOperator op, CeedSize *flops); 464 CEED_EXTERN int CeedOperatorGetContext(CeedOperator op, CeedQFunctionContext *ctx); 465 CEED_EXTERN int CeedOperatorGetContextFieldLabel(CeedOperator op, const char *field_name, CeedContextFieldLabel *field_label); 466 CEED_EXTERN int CeedOperatorSetContextDouble(CeedOperator op, CeedContextFieldLabel field_label, double *values); 467 CEED_EXTERN int CeedOperatorGetContextDoubleRead(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const double **values); 468 CEED_EXTERN int CeedOperatorRestoreContextDoubleRead(CeedOperator op, CeedContextFieldLabel field_label, const double **values); 469 CEED_EXTERN int CeedOperatorSetContextInt32(CeedOperator op, CeedContextFieldLabel field_label, int32_t *values); 470 CEED_EXTERN int CeedOperatorGetContextInt32Read(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const int32_t **values); 471 CEED_EXTERN int CeedOperatorRestoreContextInt32Read(CeedOperator op, CeedContextFieldLabel field_label, const int32_t **values); 472 CEED_EXTERN int CeedOperatorSetContextBoolean(CeedOperator op, CeedContextFieldLabel field_label, bool *values); 473 CEED_EXTERN int CeedOperatorGetContextBooleanRead(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const bool **values); 474 CEED_EXTERN int CeedOperatorRestoreContextBooleanRead(CeedOperator op, CeedContextFieldLabel field_label, const bool **values); 475 CEED_EXTERN int CeedOperatorApply(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request); 476 CEED_EXTERN int CeedOperatorApplyAdd(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request); 477 CEED_EXTERN int CeedOperatorApplyAddActive(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request); 478 CEED_EXTERN int CeedOperatorAssemblyDataStrip(CeedOperator op); 479 CEED_EXTERN int CeedOperatorDestroy(CeedOperator *op); 480 481 // Compatibility with previous composite CeedOperator naming 482 #include "deprecated.h" 483 484 CEED_EXTERN int CeedOperatorGetFieldByName(CeedOperator op, const char *field_name, CeedOperatorField *op_field); 485 CEED_EXTERN int CeedOperatorFieldGetName(CeedOperatorField op_field, const char **field_name); 486 CEED_EXTERN int CeedOperatorFieldGetElemRestriction(CeedOperatorField op_field, CeedElemRestriction *rstr); 487 CEED_EXTERN int CeedOperatorFieldGetBasis(CeedOperatorField op_field, CeedBasis *basis); 488 CEED_EXTERN int CeedOperatorFieldGetVector(CeedOperatorField op_field, CeedVector *vec); 489 CEED_EXTERN int CeedOperatorFieldGetData(CeedOperatorField op_field, const char **field_name, CeedElemRestriction *rstr, CeedBasis *basis, 490 CeedVector *vec); 491 492 /** 493 @brief Return integer power 494 495 @param[in] base The base to exponentiate 496 @param[in] power The power to raise the base to 497 498 @return base^power 499 500 @ref Utility 501 **/ 502 static inline CeedInt CeedIntPow(CeedInt base, CeedInt power) { 503 CeedInt result = 1; 504 while (power) { 505 if (power & 1) result *= base; 506 power >>= 1; 507 base *= base; 508 } 509 return result; 510 } 511 512 /** 513 @brief Return minimum of two integers 514 515 @param[in] a The first integer to compare 516 @param[in] b The second integer to compare 517 518 @return The minimum of the two integers 519 520 @ref Utility 521 **/ 522 static inline CeedInt CeedIntMin(CeedInt a, CeedInt b) { return a < b ? a : b; } 523 524 /** 525 @brief Return maximum of two integers 526 527 @param[in] a The first integer to compare 528 @param[in] b The second integer to compare 529 530 @return The maximum of the two integers 531 532 @ref Utility 533 **/ 534 static inline CeedInt CeedIntMax(CeedInt a, CeedInt b) { return a > b ? a : b; } 535 536 // Used to ensure initialization before CeedInit() 537 CEED_EXTERN int CeedRegisterAll(void); 538 // Used to ensure initialization before CeedQFunctionCreate*() 539 CEED_EXTERN int CeedQFunctionRegisterAll(void); 540