1 // Copyright (c) 2017-2022, 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 backend components of libCEED 10 #ifndef _ceed_backend_h 11 #define _ceed_backend_h 12 13 #include <ceed.h> 14 #include <limits.h> 15 #include <stdbool.h> 16 17 #if defined(__clang_analyzer__) 18 #define CEED_INTERN 19 #elif defined(__cplusplus) 20 #define CEED_INTERN extern "C" CEED_VISIBILITY(hidden) 21 #else 22 #define CEED_INTERN extern CEED_VISIBILITY(hidden) 23 #endif 24 25 #define CEED_UNUSED __attribute__((unused)) 26 27 #define CEED_MAX_RESOURCE_LEN 1024 28 #define CEED_MAX_BACKEND_PRIORITY UINT_MAX 29 #define CEED_ALIGN 64 30 #define CEED_COMPOSITE_MAX 16 31 #define CEED_FIELD_MAX 16 32 33 /** 34 @ingroup Ceed 35 This macro provides the ability to disable optimization flags for functions that are sensitive to floating point optimizations. 36 **/ 37 #ifndef CeedPragmaOptimizeOff 38 #if defined(__clang__) 39 #define CeedPragmaOptimizeOff _Pragma("clang optimize off") 40 #elif defined(__GNUC__) 41 #define CeedPragmaOptimizeOff _Pragma("GCC push_options") _Pragma("GCC optimize 0") 42 #elif defined(__INTEL_COMPILER) || defined(__INTEL_LLVM_COMPILER) 43 #define CeedPragmaOptimizeOff _Pragma("optimize('', off)") 44 #else 45 #define CeedPragmaOptimizeOff 46 #endif 47 #endif 48 49 /** 50 @ingroup Ceed 51 This macro restores previously set optimization flags after CeedPragmaOptimizeOff. 52 **/ 53 #ifndef CeedPragmaOptimizeOn 54 #if defined(__clang__) 55 #define CeedPragmaOptimizeOn _Pragma("clang optimize on") 56 #elif defined(__GNUC__) 57 #define CeedPragmaOptimizeOn _Pragma("GCC pop_options") 58 #elif defined(__INTEL_COMPILER) || defined(__INTEL_LLVM_COMPILER) 59 #define CeedPragmaOptimizeOff _Pragma("optimize('', on)") 60 #else 61 #define CeedPragmaOptimizeOn 62 #endif 63 #endif 64 65 /// CEED_DEBUG_COLOR default value, forward CeedDebug* declarations & macros 66 #define CEED_DEBUG_COLOR_NONE 255 67 68 CEED_EXTERN void CeedDebugImpl256(const unsigned char, const char *, ...); 69 CEED_EXTERN bool CeedDebugFlag(const Ceed ceed); 70 CEED_EXTERN bool CeedDebugFlagEnv(void); 71 #define CeedDebug256(ceed, color, ...) \ 72 { \ 73 if (CeedDebugFlag(ceed)) CeedDebugImpl256(color, ##__VA_ARGS__); \ 74 } 75 #define CeedDebug(ceed, ...) CeedDebug256(ceed, (unsigned char)CEED_DEBUG_COLOR_NONE, ##__VA_ARGS__) 76 #define CeedDebugEnv256(color, ...) \ 77 { \ 78 if (CeedDebugFlagEnv()) CeedDebugImpl256(color, ##__VA_ARGS__); \ 79 } 80 #define CeedDebugEnv(...) CeedDebugEnv256((unsigned char)CEED_DEBUG_COLOR_NONE, ##__VA_ARGS__) 81 82 /// Handle for object handling TensorContraction 83 /// @ingroup CeedBasis 84 typedef struct CeedTensorContract_private *CeedTensorContract; 85 86 /// Handle for object handling assembled QFunction data 87 /// @ingroup CeedOperator 88 typedef struct CeedQFunctionAssemblyData_private *CeedQFunctionAssemblyData; 89 90 /// Handle for object handling assembled Operator data 91 /// @ingroup CeedOperator 92 typedef struct CeedOperatorAssemblyData_private *CeedOperatorAssemblyData; 93 94 /* In the next 3 functions, p has to be the address of a pointer type, i.e. p has to be a pointer to a pointer. */ 95 CEED_INTERN int CeedMallocArray(size_t n, size_t unit, void *p); 96 CEED_INTERN int CeedCallocArray(size_t n, size_t unit, void *p); 97 CEED_INTERN int CeedReallocArray(size_t n, size_t unit, void *p); 98 CEED_INTERN int CeedStringAllocCopy(const char *source, char **copy); 99 CEED_INTERN int CeedFree(void *p); 100 101 #define CeedChk(ierr) \ 102 do { \ 103 int ierr_ = ierr; \ 104 if (ierr_) return ierr_; \ 105 } while (0) 106 #define CeedChkBackend(ierr) \ 107 do { \ 108 int ierr_ = ierr; \ 109 if (ierr_) { \ 110 if (ierr_ > CEED_ERROR_SUCCESS) return CEED_ERROR_BACKEND; \ 111 else return ierr_; \ 112 } \ 113 } while (0) 114 115 #define CeedCall(...) \ 116 do { \ 117 int ierr_q_ = __VA_ARGS__; \ 118 CeedChk(ierr_q_); \ 119 } while (0) 120 #define CeedCallBackend(...) \ 121 do { \ 122 int ierr_q_ = __VA_ARGS__; \ 123 CeedChkBackend(ierr_q_); \ 124 } while (0) 125 126 #define CeedCheck(cond, ceed, ecode, ...) \ 127 do { \ 128 if (!(cond)) { \ 129 return CeedError(ceed, ecode, __VA_ARGS__); \ 130 } \ 131 } while (0) 132 133 /* Note that CeedMalloc and CeedCalloc will, generally, return pointers with different memory alignments: 134 CeedMalloc returns pointers aligned at CEED_ALIGN bytes, while CeedCalloc uses the alignment of calloc. */ 135 #define CeedMalloc(n, p) CeedMallocArray((n), sizeof(**(p)), p) 136 #define CeedCalloc(n, p) CeedCallocArray((n), sizeof(**(p)), p) 137 #define CeedRealloc(n, p) CeedReallocArray((n), sizeof(**(p)), p) 138 139 CEED_EXTERN int CeedRegister(const char *prefix, int (*init)(const char *, Ceed), unsigned int priority); 140 CEED_EXTERN int CeedRegisterImpl(const char *prefix, int (*init)(const char *, Ceed), unsigned int priority); 141 142 CEED_EXTERN int CeedIsDebug(Ceed ceed, bool *is_debug); 143 CEED_EXTERN int CeedGetParent(Ceed ceed, Ceed *parent); 144 CEED_EXTERN int CeedGetDelegate(Ceed ceed, Ceed *delegate); 145 CEED_EXTERN int CeedSetDelegate(Ceed ceed, Ceed delegate); 146 CEED_EXTERN int CeedGetObjectDelegate(Ceed ceed, Ceed *delegate, const char *obj_name); 147 CEED_EXTERN int CeedSetObjectDelegate(Ceed ceed, Ceed delegate, const char *obj_name); 148 CEED_EXTERN int CeedGetOperatorFallbackResource(Ceed ceed, const char **resource); 149 CEED_EXTERN int CeedGetOperatorFallbackCeed(Ceed ceed, Ceed *fallback_ceed); 150 CEED_EXTERN int CeedSetOperatorFallbackResource(Ceed ceed, const char *resource); 151 CEED_EXTERN int CeedGetOperatorFallbackParentCeed(Ceed ceed, Ceed *parent); 152 CEED_EXTERN int CeedSetDeterministic(Ceed ceed, bool is_deterministic); 153 CEED_EXTERN int CeedSetBackendFunction(Ceed ceed, const char *type, void *object, const char *func_name, int (*f)()); 154 CEED_EXTERN int CeedGetData(Ceed ceed, void *data); 155 CEED_EXTERN int CeedSetData(Ceed ceed, void *data); 156 CEED_EXTERN int CeedReference(Ceed ceed); 157 158 CEED_EXTERN int CeedVectorHasValidArray(CeedVector vec, bool *has_valid_array); 159 CEED_EXTERN int CeedVectorHasBorrowedArrayOfType(CeedVector vec, CeedMemType mem_type, bool *has_borrowed_array_of_type); 160 CEED_EXTERN int CeedVectorHasValidArray(CeedVector vec, bool *has_valid_array); 161 CEED_EXTERN int CeedVectorGetState(CeedVector vec, uint64_t *state); 162 CEED_EXTERN int CeedVectorGetData(CeedVector vec, void *data); 163 CEED_EXTERN int CeedVectorSetData(CeedVector vec, void *data); 164 CEED_EXTERN int CeedVectorReference(CeedVector vec); 165 166 CEED_EXTERN int CeedElemRestrictionApplyUnsigned(CeedElemRestriction rstr, CeedTransposeMode t_mode, CeedVector u, CeedVector ru, 167 CeedRequest *request); 168 CEED_EXTERN int CeedElemRestrictionGetStrides(CeedElemRestriction rstr, CeedInt (*strides)[3]); 169 CEED_EXTERN int CeedElemRestrictionGetOffsets(CeedElemRestriction rstr, CeedMemType mem_type, const CeedInt **offsets); 170 CEED_EXTERN int CeedElemRestrictionRestoreOffsets(CeedElemRestriction rstr, const CeedInt **offsets); 171 CEED_EXTERN int CeedElemRestrictionIsStrided(CeedElemRestriction rstr, bool *is_strided); 172 CEED_EXTERN int CeedElemRestrictionIsOriented(CeedElemRestriction rstr, bool *is_oriented); 173 CEED_EXTERN int CeedElemRestrictionHasBackendStrides(CeedElemRestriction rstr, bool *has_backend_strides); 174 CEED_EXTERN int CeedElemRestrictionGetELayout(CeedElemRestriction rstr, CeedInt (*layout)[3]); 175 CEED_EXTERN int CeedElemRestrictionSetELayout(CeedElemRestriction rstr, CeedInt layout[3]); 176 CEED_EXTERN int CeedElemRestrictionGetData(CeedElemRestriction rstr, void *data); 177 CEED_EXTERN int CeedElemRestrictionSetData(CeedElemRestriction rstr, void *data); 178 CEED_EXTERN int CeedElemRestrictionReference(CeedElemRestriction rstr); 179 CEED_EXTERN int CeedElemRestrictionGetFlopsEstimate(CeedElemRestriction rstr, CeedTransposeMode t_mode, CeedSize *flops); 180 181 /// Type of FE space; 182 /// @ingroup CeedBasis 183 typedef enum { 184 /// H^1 FE space 185 CEED_FE_SPACE_H1 = 1, 186 /// H(div) FE space 187 CEED_FE_SPACE_HDIV = 2, 188 /// H(curl) FE space 189 CEED_FE_SPACE_HCURL = 3, 190 } CeedFESpace; 191 CEED_EXTERN const char *const CeedFESpaces[]; 192 193 CEED_EXTERN int CeedBasisGetCollocatedGrad(CeedBasis basis, CeedScalar *colo_grad_1d); 194 CEED_EXTERN int CeedBasisIsTensor(CeedBasis basis, bool *is_tensor); 195 CEED_EXTERN int CeedBasisGetData(CeedBasis basis, void *data); 196 CEED_EXTERN int CeedBasisSetData(CeedBasis basis, void *data); 197 CEED_EXTERN int CeedBasisReference(CeedBasis basis); 198 CEED_EXTERN int CeedBasisGetNumQuadratureComponents(CeedBasis basis, CeedEvalMode eval_mode, CeedInt *q_comp); 199 CEED_EXTERN int CeedBasisGetFlopsEstimate(CeedBasis basis, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedSize *flops); 200 CEED_EXTERN int CeedBasisGetFESpace(CeedBasis basis, CeedFESpace *fe_space); 201 CEED_EXTERN int CeedBasisGetTopologyDimension(CeedElemTopology topo, CeedInt *dim); 202 CEED_EXTERN int CeedBasisGetTensorContract(CeedBasis basis, CeedTensorContract *contract); 203 CEED_EXTERN int CeedBasisSetTensorContract(CeedBasis basis, CeedTensorContract contract); 204 205 CEED_EXTERN int CeedTensorContractCreate(Ceed ceed, CeedBasis basis, CeedTensorContract *contract); 206 CEED_EXTERN int CeedTensorContractApply(CeedTensorContract contract, CeedInt A, CeedInt B, CeedInt C, CeedInt J, const CeedScalar *__restrict__ t, 207 CeedTransposeMode t_mode, const CeedInt Add, const CeedScalar *__restrict__ u, CeedScalar *__restrict__ v); 208 CEED_EXTERN int CeedTensorContractStridedApply(CeedTensorContract contract, CeedInt A, CeedInt B, CeedInt C, CeedInt D, CeedInt J, 209 const CeedScalar *__restrict__ t, CeedTransposeMode t_mode, const CeedInt add, 210 const CeedScalar *__restrict__ u, CeedScalar *__restrict__ v); 211 CEED_EXTERN int CeedTensorContractGetCeed(CeedTensorContract contract, Ceed *ceed); 212 CEED_EXTERN int CeedTensorContractGetData(CeedTensorContract contract, void *data); 213 CEED_EXTERN int CeedTensorContractSetData(CeedTensorContract contract, void *data); 214 CEED_EXTERN int CeedTensorContractReference(CeedTensorContract contract); 215 CEED_EXTERN int CeedTensorContractDestroy(CeedTensorContract *contract); 216 217 CEED_EXTERN int CeedQFunctionRegister(const char *name, const char *source, CeedInt vec_length, CeedQFunctionUser f, 218 int (*init)(Ceed, const char *, CeedQFunction)); 219 CEED_EXTERN int CeedQFunctionSetFortranStatus(CeedQFunction qf, bool status); 220 CEED_EXTERN int CeedQFunctionGetVectorLength(CeedQFunction qf, CeedInt *vec_length); 221 CEED_EXTERN int CeedQFunctionGetNumArgs(CeedQFunction qf, CeedInt *num_input_fields, CeedInt *num_output_fields); 222 CEED_EXTERN int CeedQFunctionGetKernelName(CeedQFunction qf, char **kernel_name); 223 CEED_EXTERN int CeedQFunctionGetSourcePath(CeedQFunction qf, char **source_path); 224 CEED_EXTERN int CeedQFunctionLoadSourceToBuffer(CeedQFunction qf, char **source_buffer); 225 CEED_EXTERN int CeedQFunctionGetUserFunction(CeedQFunction qf, CeedQFunctionUser *f); 226 CEED_EXTERN int CeedQFunctionGetContext(CeedQFunction qf, CeedQFunctionContext *ctx); 227 CEED_EXTERN int CeedQFunctionGetContextData(CeedQFunction qf, CeedMemType mem_type, void *data); 228 CEED_EXTERN int CeedQFunctionRestoreContextData(CeedQFunction qf, void *data); 229 CEED_EXTERN int CeedQFunctionGetInnerContext(CeedQFunction qf, CeedQFunctionContext *ctx); 230 CEED_EXTERN int CeedQFunctionGetInnerContextData(CeedQFunction qf, CeedMemType mem_type, void *data); 231 CEED_EXTERN int CeedQFunctionRestoreInnerContextData(CeedQFunction qf, void *data); 232 CEED_EXTERN int CeedQFunctionIsIdentity(CeedQFunction qf, bool *is_identity); 233 CEED_EXTERN int CeedQFunctionIsContextWritable(CeedQFunction qf, bool *is_writable); 234 CEED_EXTERN int CeedQFunctionGetData(CeedQFunction qf, void *data); 235 CEED_EXTERN int CeedQFunctionSetData(CeedQFunction qf, void *data); 236 CEED_EXTERN int CeedQFunctionReference(CeedQFunction qf); 237 CEED_EXTERN int CeedQFunctionGetFlopsEstimate(CeedQFunction qf, CeedSize *flops); 238 239 CEED_EXTERN int CeedQFunctionContextGetCeed(CeedQFunctionContext ctx, Ceed *ceed); 240 CEED_EXTERN int CeedQFunctionContextHasValidData(CeedQFunctionContext ctx, bool *has_valid_data); 241 CEED_EXTERN int CeedQFunctionContextHasBorrowedDataOfType(CeedQFunctionContext ctx, CeedMemType mem_type, bool *has_borrowed_data_of_type); 242 CEED_EXTERN int CeedQFunctionContextGetState(CeedQFunctionContext ctx, uint64_t *state); 243 CEED_EXTERN int CeedQFunctionContextGetBackendData(CeedQFunctionContext ctx, void *data); 244 CEED_EXTERN int CeedQFunctionContextSetBackendData(CeedQFunctionContext ctx, void *data); 245 CEED_EXTERN int CeedQFunctionContextGetFieldLabel(CeedQFunctionContext ctx, const char *field_name, CeedContextFieldLabel *field_label); 246 CEED_EXTERN int CeedQFunctionContextSetGeneric(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, CeedContextFieldType field_type, 247 void *value); 248 CEED_EXTERN int CeedQFunctionContextGetGenericRead(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, CeedContextFieldType field_type, 249 size_t *num_values, void *value); 250 CEED_EXTERN int CeedQFunctionContextRestoreGenericRead(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, CeedContextFieldType field_type, 251 void *value); 252 CEED_EXTERN int CeedQFunctionContextSetDouble(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, double *values); 253 CEED_EXTERN int CeedQFunctionContextGetDoubleRead(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, size_t *num_values, 254 const double **values); 255 CEED_EXTERN int CeedQFunctionContextRestoreDoubleRead(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, const double **values); 256 CEED_EXTERN int CeedQFunctionContextSetInt32(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, int *values); 257 CEED_EXTERN int CeedQFunctionContextGetInt32Read(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, size_t *num_values, const int **values); 258 CEED_EXTERN int CeedQFunctionContextRestoreInt32Read(CeedQFunctionContext ctx, CeedContextFieldLabel field_label, const int **values); 259 CEED_EXTERN int CeedQFunctionContextGetDataDestroy(CeedQFunctionContext ctx, CeedMemType *f_mem_type, CeedQFunctionContextDataDestroyUser *f); 260 CEED_EXTERN int CeedQFunctionContextReference(CeedQFunctionContext ctx); 261 262 CEED_EXTERN int CeedQFunctionAssemblyDataCreate(Ceed ceed, CeedQFunctionAssemblyData *data); 263 CEED_EXTERN int CeedQFunctionAssemblyDataReference(CeedQFunctionAssemblyData data); 264 CEED_EXTERN int CeedQFunctionAssemblyDataSetReuse(CeedQFunctionAssemblyData data, bool reuse_assembly_data); 265 CEED_EXTERN int CeedQFunctionAssemblyDataSetUpdateNeeded(CeedQFunctionAssemblyData data, bool needs_data_update); 266 CEED_EXTERN int CeedQFunctionAssemblyDataIsUpdateNeeded(CeedQFunctionAssemblyData data, bool *is_update_needed); 267 CEED_EXTERN int CeedQFunctionAssemblyDataReferenceCopy(CeedQFunctionAssemblyData data, CeedQFunctionAssemblyData *data_copy); 268 CEED_EXTERN int CeedQFunctionAssemblyDataIsSetup(CeedQFunctionAssemblyData data, bool *is_setup); 269 CEED_EXTERN int CeedQFunctionAssemblyDataSetObjects(CeedQFunctionAssemblyData data, CeedVector vec, CeedElemRestriction rstr); 270 CEED_EXTERN int CeedQFunctionAssemblyDataGetObjects(CeedQFunctionAssemblyData data, CeedVector *vec, CeedElemRestriction *rstr); 271 CEED_EXTERN int CeedQFunctionAssemblyDataDestroy(CeedQFunctionAssemblyData *data); 272 273 CEED_EXTERN int CeedOperatorAssemblyDataCreate(Ceed ceed, CeedOperator op, CeedOperatorAssemblyData *data); 274 CEED_EXTERN int CeedOperatorAssemblyDataGetEvalModes(CeedOperatorAssemblyData data, CeedInt *num_active_bases, CeedInt **num_eval_modes_in, 275 const CeedEvalMode ***eval_modes_in, CeedSize ***eval_mode_offsets_in, 276 CeedInt **num_eval_modes_out, const CeedEvalMode ***eval_modes_out, 277 CeedSize ***eval_mode_offsets_out, CeedSize *num_output_components); 278 CEED_EXTERN int CeedOperatorAssemblyDataGetBases(CeedOperatorAssemblyData data, CeedInt *num_active_bases, CeedBasis **active_bases, 279 const CeedScalar ***assembled_bases_in, const CeedScalar ***assembled_bases_out); 280 CEED_EXTERN int CeedOperatorAssemblyDataGetElemRestrictions(CeedOperatorAssemblyData data, CeedInt *num_active_elem_rstrs, 281 CeedElemRestriction **active_elem_rstrs); 282 CEED_EXTERN int CeedOperatorAssemblyDataDestroy(CeedOperatorAssemblyData *data); 283 284 CEED_EXTERN int CeedOperatorGetOperatorAssemblyData(CeedOperator op, CeedOperatorAssemblyData *data); 285 CEED_EXTERN int CeedOperatorGetActiveBasis(CeedOperator op, CeedBasis *active_basis); 286 CEED_EXTERN int CeedOperatorGetActiveElemRestriction(CeedOperator op, CeedElemRestriction *active_rstr); 287 CEED_EXTERN int CeedOperatorGetNumArgs(CeedOperator op, CeedInt *num_args); 288 CEED_EXTERN int CeedOperatorIsSetupDone(CeedOperator op, bool *is_setup_done); 289 CEED_EXTERN int CeedOperatorGetQFunction(CeedOperator op, CeedQFunction *qf); 290 CEED_EXTERN int CeedOperatorIsComposite(CeedOperator op, bool *is_composite); 291 CEED_EXTERN int CeedOperatorGetData(CeedOperator op, void *data); 292 CEED_EXTERN int CeedOperatorSetData(CeedOperator op, void *data); 293 CEED_EXTERN int CeedOperatorReference(CeedOperator op); 294 CEED_EXTERN int CeedOperatorSetSetupDone(CeedOperator op); 295 296 CEED_INTERN int CeedMatrixMatrixMultiply(Ceed ceed, const CeedScalar *mat_A, const CeedScalar *mat_B, CeedScalar *mat_C, CeedInt m, CeedInt n, 297 CeedInt kk); 298 CEED_EXTERN int CeedQRFactorization(Ceed ceed, CeedScalar *mat, CeedScalar *tau, CeedInt m, CeedInt n); 299 CEED_EXTERN int CeedHouseholderApplyQ(CeedScalar *mat_A, const CeedScalar *mat_Q, const CeedScalar *tau, CeedTransposeMode t_mode, CeedInt m, 300 CeedInt n, CeedInt k, CeedInt row, CeedInt col); 301 CEED_EXTERN int CeedSymmetricSchurDecomposition(Ceed ceed, CeedScalar *mat, CeedScalar *lambda, CeedInt n); 302 CEED_EXTERN int CeedSimultaneousDiagonalization(Ceed ceed, CeedScalar *mat_A, CeedScalar *mat_B, CeedScalar *x, CeedScalar *lambda, CeedInt n); 303 304 #endif 305