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 types and macros used in user QFunction source code 10 #ifndef CEED_QFUNCTION_DEFS_H 11 #define CEED_QFUNCTION_DEFS_H 12 13 #ifndef CEED_RUNNING_JIT_PASS 14 #include <stddef.h> 15 #include <stdint.h> 16 #endif 17 18 /** 19 @ingroup CeedQFunction 20 This macro defines compiler attributes to the CEED_QFUNCTION to force inlining for called functions. 21 The `inline` declaration does not necessarily enforce a compiler to inline a function. 22 This can be detrimental to performance, so here we force inlining to occur unless inlining has been forced off (like during debugging). 23 **/ 24 #ifndef CEED_QFUNCTION_ATTR 25 #ifndef __NO_INLINE__ 26 #if defined(__GNUC__) || defined(__clang__) 27 #define CEED_QFUNCTION_ATTR __attribute__((flatten)) 28 #elif defined(__INTEL_COMPILER) 29 #define CEED_QFUNCTION_ATTR _Pragma("forceinline") 30 #else 31 #define CEED_QFUNCTION_ATTR 32 #endif 33 #else 34 #define CEED_QFUNCTION_ATTR 35 #endif 36 #if defined(__GNUC__) || defined(__clang__) 37 #define CEED_QFUNCTION_HELPER_ATTR CEED_QFUNCTION_ATTR __attribute__((always_inline)) 38 #else 39 #define CEED_QFUNCTION_HELPER_ATTR CEED_QFUNCTION_ATTR 40 #endif 41 #endif 42 43 /** 44 @ingroup CeedQFunction 45 This macro populates the correct function annotations for User QFunction source for code generation backends or populates default values for CPU 46 backends. It also creates a variable `name_loc` populated with the correct source path for creating the respective User QFunction. 47 **/ 48 #ifndef CEED_QFUNCTION 49 #define CEED_QFUNCTION(name) \ 50 static const char name##_loc[] = __FILE__ ":" #name; \ 51 CEED_QFUNCTION_ATTR static int name 52 #endif 53 54 /** 55 @ingroup CeedQFunction 56 This macro populates the correct function annotations for User QFunction helper function source for code generation backends or populates default 57 values for CPU backends. 58 **/ 59 #ifndef CEED_QFUNCTION_HELPER 60 #define CEED_QFUNCTION_HELPER CEED_QFUNCTION_HELPER_ATTR static inline 61 #endif 62 63 /** 64 @ingroup CeedQFunction 65 Using VLA syntax to reshape User QFunction inputs and outputs can make user code more readable. 66 VLA is a C99 feature that is not supported by the C++ dialect used by CUDA. 67 This macro allows users to use the VLA syntax with the CUDA backends. 68 **/ 69 #ifndef CEED_Q_VLA 70 #define CEED_Q_VLA Q 71 #endif 72 73 /** 74 @ingroup Ceed 75 This macro provides the appropriate SIMD Pragma for the compilation environment. 76 Code generation backends may redefine this macro, as needed. 77 **/ 78 #ifndef CeedPragmaSIMD 79 #if defined(__INTEL_COMPILER) 80 #define CeedPragmaSIMD _Pragma("vector") 81 /// Cannot use Intel pragma ivdep because it miscompiles unpacking symmetric tensors, as in Poisson2DApply, where the SIMD loop body contains 82 /// temporaries such as the following. 83 /// 84 /// const CeedScalar dXdxdXdxT[2][2] = {{qd[i+0*Q], qd[i+2*Q]}, 85 /// {qd[i+2*Q], qd[i+1*Q]}}; 86 /// for (int j=0; j<2; j++) 87 /// vg[i+j*Q] = (du[0] * dXdxdXdxT[0][j] + du[1] * dXdxdXdxT[1][j]); 88 /// 89 /// Miscompilation with pragma ivdep observed with icc (ICC) 19.0.5.281 20190815 at -O2 and above. 90 #elif defined(__GNUC__) && __GNUC__ >= 5 91 #define CeedPragmaSIMD _Pragma("GCC ivdep") 92 #elif defined(__clang__) 93 #define CeedPragmaSIMD _Pragma("clang loop vectorize(enable)") 94 #elif defined(_OPENMP) && _OPENMP >= 201307 // OpenMP-4.0 (July, 2013) 95 #define CeedPragmaSIMD _Pragma("omp simd") 96 #else 97 #define CeedPragmaSIMD 98 #endif 99 #endif 100 101 /// Integer type, used for indexing 102 /// @ingroup Ceed 103 typedef int32_t CeedInt; 104 #define CeedInt_FMT "d" 105 106 /// Integer type, used array sizes 107 /// @ingroup Ceed 108 typedef ptrdiff_t CeedSize; 109 #define CeedSize_FMT "td" 110 111 /// Integer type, for small integers 112 /// @ingroup Ceed 113 typedef signed char CeedInt8; 114 #define CeedInt8_FMT "d" 115 116 /// Scalar (floating point) types 117 /// 118 /// @ingroup Ceed 119 typedef enum { 120 /// Single precision 121 CEED_SCALAR_FP32, 122 /// Double precision 123 CEED_SCALAR_FP64 124 } CeedScalarType; 125 /// Base scalar type for the library to use: change which header is included to change the precision. 126 #include "ceed-f64.h" // IWYU pragma: export 127 128 /// Ceed error code. 129 /// 130 /// This enum is used to specify the type of error returned by a function. 131 /// A zero error code is success, negative error codes indicate terminal errors and positive error codes indicate nonterminal errors. 132 /// With nonterminal errors the object state has not been modified, but with terminal errors the object data is likely modified or corrupted. 133 /// @ingroup Ceed 134 typedef enum { 135 /// Success error code 136 CEED_ERROR_SUCCESS = 0, 137 /// Minor error, generic 138 CEED_ERROR_MINOR = 1, 139 /// Minor error, dimension mismatch in inputs 140 CEED_ERROR_DIMENSION = 2, 141 /// Minor error, incomplete object setup 142 CEED_ERROR_INCOMPLETE = 3, 143 /// Minor error, incompatible arguments/configuration 144 CEED_ERROR_INCOMPATIBLE = 4, 145 /// Minor error, access lock problem 146 CEED_ERROR_ACCESS = 5, 147 /// Major error, generic 148 CEED_ERROR_MAJOR = -1, 149 /// Major error, internal backend error 150 CEED_ERROR_BACKEND = -2, 151 /// Major error, operation unsupported by current backend 152 CEED_ERROR_UNSUPPORTED = -3, 153 } CeedErrorType; 154 155 /// Specify memory type. 156 /// Many Ceed interfaces take or return pointers to memory. 157 /// This enum is used to specify where the memory being provided or requested must reside. 158 /// @ingroup Ceed 159 typedef enum { 160 /// Memory resides on the host 161 CEED_MEM_HOST, 162 /// Memory resides on a device (corresponding to \ref Ceed resource) 163 CEED_MEM_DEVICE, 164 } CeedMemType; 165 166 /// Conveys ownership status of arrays passed to Ceed interfaces. 167 /// @ingroup Ceed 168 typedef enum { 169 /// Implementation will copy the values and not store the passed pointer. 170 CEED_COPY_VALUES, 171 /// Implementation can use and modify the data provided by the user, but does not take ownership. 172 CEED_USE_POINTER, 173 /// Implementation takes ownership of the pointer and will free using CeedFree() when done using it. 174 /// The user should not assume that the pointer remains valid after ownership has been transferred. 175 /// Note that arrays allocated using C++ operator new or other allocators cannot generally be freed using CeedFree(). 176 /// CeedFree() is capable of freeing any memory that can be freed using free(). 177 CEED_OWN_POINTER, 178 } CeedCopyMode; 179 180 /// Denotes type of vector norm to be computed 181 /// @ingroup CeedVector 182 typedef enum { 183 /// \f$\Vert \bm{x}\Vert_1 = \sum_i \vert x_i\vert\f$ 184 CEED_NORM_1, 185 /// \f$\Vert \bm{x} \Vert_2 = \sqrt{\sum_i x_i^2}\f$ 186 CEED_NORM_2, 187 /// \f$\Vert \bm{x} \Vert_\infty = \max_i \vert x_i \vert\f$ 188 CEED_NORM_MAX, 189 } CeedNormType; 190 191 /// Denotes whether a linear transformation or its transpose should be applied 192 /// @ingroup CeedBasis 193 typedef enum { 194 /// Apply the linear transformation 195 CEED_NOTRANSPOSE, 196 /// Apply the transpose 197 CEED_TRANSPOSE 198 } CeedTransposeMode; 199 200 /// Basis evaluation mode 201 /// @ingroup CeedBasis 202 typedef enum { 203 /// Perform no evaluation (either because there is no data or it is already at quadrature points) 204 CEED_EVAL_NONE = 0, 205 /// Interpolate from nodes to quadrature points 206 CEED_EVAL_INTERP = 1, 207 /// Evaluate gradients at quadrature points from input in the basis 208 CEED_EVAL_GRAD = 2, 209 /// Evaluate divergence at quadrature points from input in the basis 210 CEED_EVAL_DIV = 4, 211 /// Evaluate curl at quadrature points from input in the basis 212 CEED_EVAL_CURL = 8, 213 /// Using no input, evaluate quadrature weights on the reference element 214 CEED_EVAL_WEIGHT = 16, 215 } CeedEvalMode; 216 217 /// Type of quadrature; also used for location of nodes 218 /// @ingroup CeedBasis 219 typedef enum { 220 /// Gauss-Legendre quadrature 221 CEED_GAUSS = 0, 222 /// Gauss-Legendre-Lobatto quadrature 223 CEED_GAUSS_LOBATTO = 1, 224 } CeedQuadMode; 225 226 /// Type of basis shape to create non-tensor element basis. 227 /// Dimension can be extracted with bitwise AND (CeedElemTopology & 2**(dim + 2)) == TRUE 228 /// @ingroup CeedBasis 229 typedef enum { 230 /// Line 231 CEED_TOPOLOGY_LINE = 1 << 16 | 0, 232 /// Triangle - 2D shape 233 CEED_TOPOLOGY_TRIANGLE = 2 << 16 | 1, 234 /// Quadralateral - 2D shape 235 CEED_TOPOLOGY_QUAD = 2 << 16 | 2, 236 /// Tetrahedron - 3D shape 237 CEED_TOPOLOGY_TET = 3 << 16 | 3, 238 /// Pyramid - 3D shape 239 CEED_TOPOLOGY_PYRAMID = 3 << 16 | 4, 240 /// Prism - 3D shape 241 CEED_TOPOLOGY_PRISM = 3 << 16 | 5, 242 /// Hexehedron - 3D shape 243 CEED_TOPOLOGY_HEX = 3 << 16 | 6, 244 } CeedElemTopology; 245 246 /// Denotes type of data stored in a CeedQFunctionContext field 247 /// @ingroup CeedQFunction 248 typedef enum { 249 /// Double precision value 250 CEED_CONTEXT_FIELD_DOUBLE = 1, 251 /// 32 bit integer value 252 CEED_CONTEXT_FIELD_INT32 = 2, 253 /// Boolean value 254 CEED_CONTEXT_FIELD_BOOL = 3, 255 } CeedContextFieldType; 256 257 #endif // CEED_QFUNCTION_DEFS_H 258