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