xref: /libCEED/rust/libceed-sys/c-src/include/ceed/ceed.h (revision f2989f2b3b8649d855bed22b6730ee0ecfa6b31b) 
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 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 /// Generic type for all libCEED objects to support common functionality, such as viewing
103 /// @ingroup CeedUser
104 typedef struct CeedObject_private *CeedObject;
105 
106 CEED_EXTERN int  CeedObjectView(CeedObject obj, FILE *stream);
107 CEED_EXTERN int  CeedObjectSetNumViewTabs(CeedObject obj, CeedInt num_tabs);
108 CEED_EXTERN int  CeedObjectGetNumViewTabs(CeedObject obj, CeedInt *num_tabs);
109 CEED_EXTERN int  CeedObjectGetCeed(CeedObject obj, Ceed *ceed);
110 CEED_EXTERN Ceed CeedObjectReturnCeed(CeedObject obj);
111 CEED_EXTERN int  CeedObjectDestroy(CeedObject *obj);
112 
113 CEED_EXTERN int CeedRegistryGetList(size_t *n, char ***const resources, CeedInt **array);
114 CEED_EXTERN int CeedInit(const char *resource, Ceed *ceed);
115 CEED_EXTERN int CeedSetStream(Ceed ceed, void *handle);
116 CEED_EXTERN int CeedReferenceCopy(Ceed ceed, Ceed *ceed_copy);
117 CEED_EXTERN int CeedGetResource(Ceed ceed, const char **resource);
118 CEED_EXTERN int CeedIsDeterministic(Ceed ceed, bool *is_deterministic);
119 CEED_EXTERN int CeedAddJitSourceRoot(Ceed ceed, const char *jit_source_root);
120 CEED_EXTERN int CeedAddRustSourceRoot(Ceed ceed, const char *rust_source_root);
121 CEED_EXTERN int CeedAddJitDefine(Ceed ceed, const char *jit_define);
122 CEED_EXTERN int CeedSetNumViewTabs(Ceed ceed, CeedInt num_tabs);
123 CEED_EXTERN int CeedGetNumViewTabs(Ceed ceed, CeedInt *num_tabs);
124 CEED_EXTERN int CeedView(Ceed ceed, FILE *stream);
125 CEED_EXTERN int CeedDestroy(Ceed *ceed);
126 CEED_EXTERN int CeedErrorImpl(Ceed ceed, const char *filename, int lineno, const char *func, int ecode, const char *format, ...);
127 
128 /// Raise an error on `Ceed` object
129 ///
130 /// @param ceed `Ceed` library context or `NULL`
131 /// @param ecode Error code (int)
132 /// @param ... printf-style format string followed by arguments as needed
133 ///
134 /// @ingroup Ceed
135 /// @sa CeedSetErrorHandler()
136 #define CeedError(ceed, ecode, ...) (CeedErrorImpl((ceed), __FILE__, __LINE__, __func__, (ecode), __VA_ARGS__), (ecode))
137 
138 /// Ceed error handlers
139 typedef int (*CeedErrorHandler)(Ceed, const char *, int, const char *, int, const char *, va_list *);
140 CEED_EXTERN int CeedSetErrorHandler(Ceed ceed, CeedErrorHandler handler);
141 CEED_EXTERN int CeedGetErrorMessage(Ceed ceed, const char **err_msg);
142 CEED_EXTERN int CeedResetErrorMessage(Ceed ceed, const char **err_msg);
143 CEED_EXTERN int CeedErrorReturn(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args);
144 CEED_EXTERN int CeedErrorStore(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args);
145 CEED_EXTERN int CeedErrorAbort(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args);
146 CEED_EXTERN int CeedErrorExit(Ceed ceed, const char *filename, int line_no, const char *func, int err_code, const char *format, va_list *args);
147 
148 /// libCEED library version numbering
149 /// @ingroup Ceed
150 #define CEED_VERSION_MAJOR 0
151 #define CEED_VERSION_MINOR 12
152 #define CEED_VERSION_PATCH 0
153 #define CEED_VERSION_RELEASE false
154 
155 /// Compile-time check that the the current library version is at least as recent as the specified version.
156 /// This macro is typically used in
157 /// @code
158 /// #if CEED_VERSION_GE(0, 8, 0)
159 ///   code path that needs at least 0.8.0
160 /// #else
161 ///   fallback code for older versions
162 /// #endif
163 /// @endcode
164 ///
165 /// A non-release version always compares as positive infinity.
166 ///
167 /// @param major   Major version
168 /// @param minor   Minor version
169 /// @param patch   Patch (subminor) version
170 ///
171 /// @ingroup Ceed
172 /// @sa CeedGetVersion()
173 #define CEED_VERSION_GE(major, minor, patch) \
174   (!CEED_VERSION_RELEASE ||                  \
175    (CEED_VERSION_MAJOR > major ||            \
176     (CEED_VERSION_MAJOR == major && (CEED_VERSION_MINOR > minor || (CEED_VERSION_MINOR == minor && CEED_VERSION_PATCH >= patch)))))
177 
178 CEED_EXTERN int CeedGetVersion(int *major, int *minor, int *patch, bool *release);
179 CEED_EXTERN int CeedGetGitVersion(const char **git_version);
180 CEED_EXTERN int CeedGetBuildConfiguration(const char **build_config);
181 
182 CEED_EXTERN int CeedSetIsClang(Ceed ceed, bool isClang);
183 CEED_EXTERN int CeedGetIsClang(Ceed ceed, bool *isClang);
184 
185 CEED_EXTERN int CeedGetScalarType(CeedScalarType *scalar_type);
186 
187 /// String names for enum pretty printing
188 CEED_EXTERN const char *const *CeedErrorTypes;
189 CEED_EXTERN const char *const  CeedMemTypes[];
190 CEED_EXTERN const char *const  CeedCopyModes[];
191 CEED_EXTERN const char *const  CeedTransposeModes[];
192 CEED_EXTERN const char *const  CeedEvalModes[];
193 CEED_EXTERN const char *const  CeedQuadModes[];
194 CEED_EXTERN const char *const  CeedElemTopologies[];
195 CEED_EXTERN const char *const  CeedContextFieldTypes[];
196 
197 CEED_EXTERN int CeedGetPreferredMemType(Ceed ceed, CeedMemType *type);
198 
199 CEED_EXTERN int  CeedVectorCreate(Ceed ceed, CeedSize len, CeedVector *vec);
200 CEED_EXTERN int  CeedVectorReferenceCopy(CeedVector vec, CeedVector *vec_copy);
201 CEED_EXTERN int  CeedVectorCopy(CeedVector vec, CeedVector vec_copy);
202 CEED_EXTERN int  CeedVectorCopyStrided(CeedVector vec, CeedSize start, CeedSize stop, CeedSize step, CeedVector vec_copy);
203 CEED_EXTERN int  CeedVectorSetArray(CeedVector vec, CeedMemType mem_type, CeedCopyMode copy_mode, CeedScalar *array);
204 CEED_EXTERN int  CeedVectorSetValue(CeedVector vec, CeedScalar value);
205 CEED_EXTERN int  CeedVectorSetValueStrided(CeedVector vec, CeedSize start, CeedSize stop, CeedSize step, CeedScalar value);
206 CEED_EXTERN int  CeedVectorSyncArray(CeedVector vec, CeedMemType mem_type);
207 CEED_EXTERN int  CeedVectorTakeArray(CeedVector vec, CeedMemType mem_type, CeedScalar **array);
208 CEED_EXTERN int  CeedVectorGetArray(CeedVector vec, CeedMemType mem_type, CeedScalar **array);
209 CEED_EXTERN int  CeedVectorGetArrayRead(CeedVector vec, CeedMemType mem_type, const CeedScalar **array);
210 CEED_EXTERN int  CeedVectorGetArrayWrite(CeedVector vec, CeedMemType mem_type, CeedScalar **array);
211 CEED_EXTERN int  CeedVectorRestoreArray(CeedVector vec, CeedScalar **array);
212 CEED_EXTERN int  CeedVectorRestoreArrayRead(CeedVector vec, const CeedScalar **array);
213 CEED_EXTERN int  CeedVectorNorm(CeedVector vec, CeedNormType type, CeedScalar *norm);
214 CEED_EXTERN int  CeedVectorScale(CeedVector x, CeedScalar alpha);
215 CEED_EXTERN int  CeedVectorAXPY(CeedVector y, CeedScalar alpha, CeedVector x);
216 CEED_EXTERN int  CeedVectorAXPBY(CeedVector y, CeedScalar alpha, CeedScalar beta, CeedVector x);
217 CEED_EXTERN int  CeedVectorPointwiseMult(CeedVector w, CeedVector x, CeedVector y);
218 CEED_EXTERN int  CeedVectorReciprocal(CeedVector vec);
219 CEED_EXTERN int  CeedVectorSetNumViewTabs(CeedVector vec, CeedInt num_tabs);
220 CEED_EXTERN int  CeedVectorGetNumViewTabs(CeedVector vec, CeedInt *num_tabs);
221 CEED_EXTERN int  CeedVectorViewRange(CeedVector vec, CeedSize start, CeedSize stop, CeedInt step, const char *fp_fmt, FILE *stream);
222 CEED_EXTERN int  CeedVectorView(CeedVector vec, const char *fp_fmt, FILE *stream);
223 CEED_EXTERN int  CeedVectorGetCeed(CeedVector vec, Ceed *ceed);
224 CEED_EXTERN Ceed CeedVectorReturnCeed(CeedVector vec);
225 CEED_EXTERN int  CeedVectorGetLength(CeedVector vec, CeedSize *length);
226 CEED_EXTERN int  CeedVectorDestroy(CeedVector *vec);
227 
228 CEED_EXTERN CeedRequest *const CEED_REQUEST_IMMEDIATE;
229 CEED_EXTERN CeedRequest *const CEED_REQUEST_ORDERED;
230 CEED_EXTERN int                CeedRequestWait(CeedRequest *req);
231 
232 /// Argument for @ref CeedOperatorSetField() to use active input or output.
233 /// @ingroup CeedVector
234 CEED_EXTERN const CeedVector CEED_VECTOR_ACTIVE;
235 
236 /// Argument for @ref CeedOperatorSetField() to use no `CeedVector`.
237 /// Only use this option with @ref CeedEvalMode @ref CEED_EVAL_WEIGHT.
238 /// @ingroup CeedVector
239 CEED_EXTERN const CeedVector CEED_VECTOR_NONE;
240 
241 /// Argument for @ref CeedOperatorSetField() that no basis operation is needed to translate between the E-vector and the Q-vector.
242 /// Only use this option with @ref CeedEvalMode @ref CEED_EVAL_NONE.
243 /// @ingroup CeedBasis
244 CEED_EXTERN const CeedBasis CEED_BASIS_NONE;
245 
246 /// Argument for @ref CeedOperatorSetField() to use no `CeedElemRestriction`.
247 /// Only use this option with @ref CeedEvalMode @ref CEED_EVAL_WEIGHT.
248 /// @ingroup CeedElemRestriction
249 CEED_EXTERN const CeedElemRestriction CEED_ELEMRESTRICTION_NONE;
250 
251 /// Argument for @ref CeedOperatorCreate() that `CeedQFunction` is not created by user.
252 /// Only used for `CeedQFunction` `dqf` and `dqfT`.
253 /// If implemented, a backend may attempt to provide the action of these `CeedQFunction`.
254 /// @ingroup CeedQFunction
255 CEED_EXTERN const CeedQFunction CEED_QFUNCTION_NONE;
256 
257 /// Argument for @ref CeedElemRestrictionCreateStrided() that L-vector is in the Ceed backend's preferred layout.
258 /// This argument should only be used with vectors created by a Ceed backend.
259 /// @ingroup CeedElemRestriction
260 CEED_EXTERN const CeedInt CEED_STRIDES_BACKEND[3];
261 
262 CEED_EXTERN int  CeedElemRestrictionCreate(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride, CeedSize l_size,
263                                            CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, CeedElemRestriction *rstr);
264 CEED_EXTERN int  CeedElemRestrictionCreateOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride,
265                                                    CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets,
266                                                    const bool *orients, CeedElemRestriction *rstr);
267 CEED_EXTERN int  CeedElemRestrictionCreateCurlOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride,
268                                                        CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets,
269                                                        const CeedInt8 *curl_orients, CeedElemRestriction *rstr);
270 CEED_EXTERN int  CeedElemRestrictionCreateStrided(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedSize l_size,
271                                                   const CeedInt strides[3], CeedElemRestriction *rstr);
272 CEED_EXTERN int  CeedElemRestrictionCreateAtPoints(Ceed ceed, CeedInt num_elem, CeedInt num_points, CeedInt num_comp, CeedSize l_size,
273                                                    CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, CeedElemRestriction *rstr);
274 CEED_EXTERN int  CeedElemRestrictionCreateBlocked(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp,
275                                                   CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode,
276                                                   const CeedInt *offsets, CeedElemRestriction *rstr);
277 CEED_EXTERN int  CeedElemRestrictionCreateBlockedOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp,
278                                                           CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode,
279                                                           const CeedInt *offsets, const bool *orients, CeedElemRestriction *rstr);
280 CEED_EXTERN int  CeedElemRestrictionCreateBlockedCurlOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp,
281                                                               CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode,
282                                                               const CeedInt *offsets, const CeedInt8 *curl_orients, CeedElemRestriction *rstr);
283 CEED_EXTERN int  CeedElemRestrictionCreateBlockedStrided(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp,
284                                                          CeedSize l_size, const CeedInt strides[3], CeedElemRestriction *rstr);
285 CEED_EXTERN int  CeedElemRestrictionCreateUnsignedCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_unsigned);
286 CEED_EXTERN int  CeedElemRestrictionCreateUnorientedCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_unoriented);
287 CEED_EXTERN int  CeedElemRestrictionReferenceCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_copy);
288 CEED_EXTERN int  CeedElemRestrictionCreateVector(CeedElemRestriction rstr, CeedVector *lvec, CeedVector *evec);
289 CEED_EXTERN int  CeedElemRestrictionApply(CeedElemRestriction rstr, CeedTransposeMode t_mode, CeedVector u, CeedVector ru, CeedRequest *request);
290 CEED_EXTERN int  CeedElemRestrictionApplyAtPointsInElement(CeedElemRestriction rstr, CeedInt elem, CeedTransposeMode t_mode, CeedVector u,
291                                                            CeedVector ru, CeedRequest *request);
292 CEED_EXTERN int  CeedElemRestrictionApplyBlock(CeedElemRestriction rstr, CeedInt block, CeedTransposeMode t_mode, CeedVector u, CeedVector ru,
293                                                CeedRequest *request);
294 CEED_EXTERN int  CeedElemRestrictionGetCeed(CeedElemRestriction rstr, Ceed *ceed);
295 CEED_EXTERN Ceed CeedElemRestrictionReturnCeed(CeedElemRestriction rstr);
296 CEED_EXTERN int  CeedElemRestrictionGetCompStride(CeedElemRestriction rstr, CeedInt *comp_stride);
297 CEED_EXTERN int  CeedElemRestrictionGetNumElements(CeedElemRestriction rstr, CeedInt *num_elem);
298 CEED_EXTERN int  CeedElemRestrictionGetElementSize(CeedElemRestriction rstr, CeedInt *elem_size);
299 CEED_EXTERN int  CeedElemRestrictionGetNumPoints(CeedElemRestriction rstr, CeedInt *num_points);
300 CEED_EXTERN int  CeedElemRestrictionGetNumPointsInElement(CeedElemRestriction rstr, CeedInt elem, CeedInt *num_points);
301 CEED_EXTERN int  CeedElemRestrictionGetMaxPointsInElement(CeedElemRestriction rstr, CeedInt *max_points);
302 CEED_EXTERN int  CeedElemRestrictionGetMinPointsInElement(CeedElemRestriction rstr, CeedInt *min_points);
303 CEED_EXTERN int  CeedElemRestrictionGetMinMaxPointsInElement(CeedElemRestriction rstr, CeedInt *min_points, CeedInt *max_points);
304 CEED_EXTERN int  CeedElemRestrictionGetLVectorSize(CeedElemRestriction rstr, CeedSize *l_size);
305 CEED_EXTERN int  CeedElemRestrictionGetEVectorSize(CeedElemRestriction rstr, CeedSize *e_size);
306 CEED_EXTERN int  CeedElemRestrictionGetNumComponents(CeedElemRestriction rstr, CeedInt *num_comp);
307 CEED_EXTERN int  CeedElemRestrictionGetNumBlocks(CeedElemRestriction rstr, CeedInt *num_block);
308 CEED_EXTERN int  CeedElemRestrictionGetBlockSize(CeedElemRestriction rstr, CeedInt *block_size);
309 CEED_EXTERN int  CeedElemRestrictionGetMultiplicity(CeedElemRestriction rstr, CeedVector mult);
310 CEED_EXTERN int  CeedElemRestrictionSetNumViewTabs(CeedElemRestriction rstr, CeedInt num_tabs);
311 CEED_EXTERN int  CeedElemRestrictionGetNumViewTabs(CeedElemRestriction rstr, CeedInt *num_tabs);
312 CEED_EXTERN int  CeedElemRestrictionView(CeedElemRestriction rstr, FILE *stream);
313 CEED_EXTERN int  CeedElemRestrictionDestroy(CeedElemRestriction *rstr);
314 
315 // The formalism here is that we have the structure
316 //  \int_\Omega v^T f_0(u, \nabla u, qdata) + (\nabla v)^T f_1(u, \nabla u, qdata)
317 // where gradients are with respect to the reference element.
318 
319 CEED_EXTERN int CeedBasisCreateTensorH1Lagrange(Ceed ceed, CeedInt dim, CeedInt num_comp, CeedInt P, CeedInt Q, CeedQuadMode quad_mode,
320                                                 CeedBasis *basis);
321 CEED_EXTERN int CeedBasisCreateTensorH1(Ceed ceed, CeedInt dim, CeedInt num_comp, CeedInt P_1d, CeedInt Q_1d, const CeedScalar *interp_1d,
322                                         const CeedScalar *grad_1d, const CeedScalar *q_ref_1d, const CeedScalar *q_weight_1d, CeedBasis *basis);
323 CEED_EXTERN int CeedBasisCreateH1(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt nqpts, const CeedScalar *interp,
324                                   const CeedScalar *grad, const CeedScalar *q_ref, const CeedScalar *q_weights, CeedBasis *basis);
325 CEED_EXTERN int CeedBasisCreateHdiv(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt nqpts, const CeedScalar *interp,
326                                     const CeedScalar *div, const CeedScalar *q_ref, const CeedScalar *q_weights, CeedBasis *basis);
327 CEED_EXTERN int CeedBasisCreateHcurl(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt nqpts, const CeedScalar *interp,
328                                      const CeedScalar *curl, const CeedScalar *q_ref, const CeedScalar *q_weights, CeedBasis *basis);
329 CEED_EXTERN int CeedBasisCreateProjection(CeedBasis basis_from, CeedBasis basis_to, CeedBasis *basis_project);
330 CEED_EXTERN int CeedBasisReferenceCopy(CeedBasis basis, CeedBasis *basis_copy);
331 CEED_EXTERN int CeedBasisSetNumViewTabs(CeedBasis basis, CeedInt num_tabs);
332 CEED_EXTERN int CeedBasisGetNumViewTabs(CeedBasis basis, CeedInt *num_tabs);
333 CEED_EXTERN int CeedBasisView(CeedBasis basis, FILE *stream);
334 CEED_EXTERN int CeedBasisApply(CeedBasis basis, CeedInt num_elem, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedVector u, CeedVector v);
335 CEED_EXTERN int CeedBasisApplyAdd(CeedBasis basis, CeedInt num_elem, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedVector u, CeedVector v);
336 CEED_EXTERN int CeedBasisApplyAtPoints(CeedBasis basis, CeedInt num_elem, const CeedInt *num_points, CeedTransposeMode t_mode, CeedEvalMode eval_mode,
337                                        CeedVector x_ref, CeedVector u, CeedVector v);
338 CEED_EXTERN int CeedBasisApplyAddAtPoints(CeedBasis basis, CeedInt num_elem, const CeedInt *num_points, CeedTransposeMode t_mode,
339                                           CeedEvalMode eval_mode, CeedVector x_ref, CeedVector u, CeedVector v);
340 CEED_EXTERN int CeedBasisGetCeed(CeedBasis basis, Ceed *ceed);
341 CEED_EXTERN Ceed CeedBasisReturnCeed(CeedBasis basis);
342 CEED_EXTERN int  CeedBasisGetDimension(CeedBasis basis, CeedInt *dim);
343 CEED_EXTERN int  CeedBasisGetTopology(CeedBasis basis, CeedElemTopology *topo);
344 CEED_EXTERN int  CeedBasisGetNumComponents(CeedBasis basis, CeedInt *num_comp);
345 CEED_EXTERN int  CeedBasisGetNumNodes(CeedBasis basis, CeedInt *P);
346 CEED_EXTERN int  CeedBasisGetNumNodes1D(CeedBasis basis, CeedInt *P_1d);
347 CEED_EXTERN int  CeedBasisGetNumQuadraturePoints(CeedBasis basis, CeedInt *Q);
348 CEED_EXTERN int  CeedBasisGetNumQuadraturePoints1D(CeedBasis basis, CeedInt *Q_1d);
349 CEED_EXTERN int  CeedBasisGetQRef(CeedBasis basis, const CeedScalar **q_ref);
350 CEED_EXTERN int  CeedBasisGetQWeights(CeedBasis basis, const CeedScalar **q_weights);
351 CEED_EXTERN int  CeedBasisGetInterp(CeedBasis basis, const CeedScalar **interp);
352 CEED_EXTERN int  CeedBasisGetInterp1D(CeedBasis basis, const CeedScalar **interp_1d);
353 CEED_EXTERN int  CeedBasisGetGrad(CeedBasis basis, const CeedScalar **grad);
354 CEED_EXTERN int  CeedBasisGetGrad1D(CeedBasis basis, const CeedScalar **grad_1d);
355 CEED_EXTERN int  CeedBasisGetDiv(CeedBasis basis, const CeedScalar **div);
356 CEED_EXTERN int  CeedBasisGetCurl(CeedBasis basis, const CeedScalar **curl);
357 CEED_EXTERN int  CeedBasisDestroy(CeedBasis *basis);
358 
359 CEED_EXTERN int CeedGaussQuadrature(CeedInt Q, CeedScalar *q_ref_1d, CeedScalar *q_weight_1d);
360 CEED_EXTERN int CeedLobattoQuadrature(CeedInt Q, CeedScalar *q_ref_1d, CeedScalar *q_weight_1d);
361 
362 /** Handle for the user provided `CeedQFunction` callback function
363 
364  @param[in,out] ctx User-defined context set using @ref CeedQFunctionSetContext() or `NULL`
365  @param[in] Q       Number of quadrature points at which to evaluate
366  @param[in] in      Array of pointers to each input argument in the order provided by the user in @ref CeedQFunctionAddInput().
367                       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).
368                       This results in indexing the `i`th input at quadrature point `j` as `in[i][(d*num_comp + c)*Q + j]`.
369  @param[out]   out  Array of pointers to each output array in the order provided using @ref CeedQFunctionAddOutput().
370                       The shapes are as above for `in`.
371 
372  @return An error code: 0 - success, otherwise - failure
373 
374  @ingroup CeedQFunction
375 **/
376 typedef int (*CeedQFunctionUser)(void *ctx, const CeedInt Q, const CeedScalar *const *in, CeedScalar *const *out);
377 
378 CEED_EXTERN int  CeedQFunctionCreateInterior(Ceed ceed, CeedInt vec_length, CeedQFunctionUser f, const char *source, CeedQFunction *qf);
379 CEED_EXTERN int  CeedQFunctionCreateInteriorByName(Ceed ceed, const char *name, CeedQFunction *qf);
380 CEED_EXTERN int  CeedQFunctionCreateIdentity(Ceed ceed, CeedInt size, CeedEvalMode in_mode, CeedEvalMode out_mode, CeedQFunction *qf);
381 CEED_EXTERN int  CeedQFunctionReferenceCopy(CeedQFunction qf, CeedQFunction *qf_copy);
382 CEED_EXTERN int  CeedQFunctionAddInput(CeedQFunction qf, const char *field_name, CeedInt size, CeedEvalMode eval_mode);
383 CEED_EXTERN int  CeedQFunctionAddOutput(CeedQFunction qf, const char *field_name, CeedInt size, CeedEvalMode eval_mode);
384 CEED_EXTERN int  CeedQFunctionGetFields(CeedQFunction qf, CeedInt *num_input_fields, CeedQFunctionField **input_fields, CeedInt *num_output_fields,
385                                         CeedQFunctionField **output_fields);
386 CEED_EXTERN int  CeedQFunctionSetContext(CeedQFunction qf, CeedQFunctionContext ctx);
387 CEED_EXTERN int  CeedQFunctionSetContextWritable(CeedQFunction qf, bool is_writable);
388 CEED_EXTERN int  CeedQFunctionSetUserFlopsEstimate(CeedQFunction qf, CeedSize flops);
389 CEED_EXTERN int  CeedQFunctionSetNumViewTabs(CeedQFunction qf, CeedInt num_tabs);
390 CEED_EXTERN int  CeedQFunctionGetNumViewTabs(CeedQFunction qf, CeedInt *num_tabs);
391 CEED_EXTERN int  CeedQFunctionView(CeedQFunction qf, FILE *stream);
392 CEED_EXTERN int  CeedQFunctionGetCeed(CeedQFunction qf, Ceed *ceed);
393 CEED_EXTERN Ceed CeedQFunctionReturnCeed(CeedQFunction qf);
394 CEED_EXTERN int  CeedQFunctionApply(CeedQFunction qf, CeedInt Q, CeedVector *u, CeedVector *v);
395 CEED_EXTERN int  CeedQFunctionDestroy(CeedQFunction *qf);
396 CEED_EXTERN int  CeedQFunctionFieldGetName(CeedQFunctionField qf_field, const char **field_name);
397 CEED_EXTERN int  CeedQFunctionFieldGetSize(CeedQFunctionField qf_field, CeedInt *size);
398 CEED_EXTERN int  CeedQFunctionFieldGetEvalMode(CeedQFunctionField qf_field, CeedEvalMode *eval_mode);
399 CEED_EXTERN int  CeedQFunctionFieldGetData(CeedQFunctionField qf_field, const char **field_name, CeedInt *size, CeedEvalMode *eval_mode);
400 
401 /** Handle for the user provided @ref CeedQFunctionContextDestroy() callback function
402 
403  @param[in,out] data  User `CeedQFunctionContext` data
404 
405  @return An error code: 0 - success, otherwise - failure
406 
407  @ingroup CeedQFunction
408 **/
409 typedef int (*CeedQFunctionContextDataDestroyUser)(void *data);
410 
411 CEED_EXTERN int CeedQFunctionContextCreate(Ceed ceed, CeedQFunctionContext *ctx);
412 CEED_EXTERN int CeedQFunctionContextReferenceCopy(CeedQFunctionContext ctx, CeedQFunctionContext *ctx_copy);
413 CEED_EXTERN int CeedQFunctionContextSetData(CeedQFunctionContext ctx, CeedMemType mem_type, CeedCopyMode copy_mode, size_t size, void *data);
414 CEED_EXTERN int CeedQFunctionContextTakeData(CeedQFunctionContext ctx, CeedMemType mem_type, void *data);
415 CEED_EXTERN int CeedQFunctionContextGetData(CeedQFunctionContext ctx, CeedMemType mem_type, void *data);
416 CEED_EXTERN int CeedQFunctionContextGetDataRead(CeedQFunctionContext ctx, CeedMemType mem_type, void *data);
417 CEED_EXTERN int CeedQFunctionContextRestoreData(CeedQFunctionContext ctx, void *data);
418 CEED_EXTERN int CeedQFunctionContextRestoreDataRead(CeedQFunctionContext ctx, void *data);
419 CEED_EXTERN int CeedQFunctionContextRegisterDouble(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values,
420                                                    const char *field_description);
421 CEED_EXTERN int CeedQFunctionContextRegisterInt32(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values,
422                                                   const char *field_description);
423 CEED_EXTERN int CeedQFunctionContextRegisterBoolean(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values,
424                                                     const char *field_description);
425 CEED_EXTERN int CeedQFunctionContextGetAllFieldLabels(CeedQFunctionContext ctx, const CeedContextFieldLabel **field_labels, CeedInt *num_fields);
426 CEED_EXTERN int CeedContextFieldLabelGetDescription(CeedContextFieldLabel label, const char **field_name, size_t *field_offset, size_t *num_values,
427                                                     const char **field_description, CeedContextFieldType *field_type);
428 CEED_EXTERN int CeedQFunctionContextGetContextSize(CeedQFunctionContext ctx, size_t *ctx_size);
429 CEED_EXTERN int CeedQFunctionContextSetNumViewTabs(CeedQFunctionContext ctx, CeedInt num_tabs);
430 CEED_EXTERN int CeedQFunctionContextGetNumViewTabs(CeedQFunctionContext ctx, CeedInt *num_tabs);
431 CEED_EXTERN int CeedQFunctionContextView(CeedQFunctionContext ctx, FILE *stream);
432 CEED_EXTERN int CeedQFunctionContextSetDataDestroy(CeedQFunctionContext ctx, CeedMemType f_mem_type, CeedQFunctionContextDataDestroyUser f);
433 CEED_EXTERN int CeedQFunctionContextDestroy(CeedQFunctionContext *ctx);
434 
435 CEED_EXTERN int CeedOperatorCreate(Ceed ceed, CeedQFunction qf, CeedQFunction dqf, CeedQFunction dqfT, CeedOperator *op);
436 CEED_EXTERN int CeedOperatorCreateAtPoints(Ceed ceed, CeedQFunction qf, CeedQFunction dqf, CeedQFunction dqfT, CeedOperator *op);
437 CEED_EXTERN int CeedOperatorCreateComposite(Ceed ceed, CeedOperator *op);
438 CEED_EXTERN int CeedOperatorReferenceCopy(CeedOperator op, CeedOperator *op_copy);
439 CEED_EXTERN int CeedOperatorSetField(CeedOperator op, const char *field_name, CeedElemRestriction rstr, CeedBasis basis, CeedVector vec);
440 CEED_EXTERN int CeedOperatorGetFields(CeedOperator op, CeedInt *num_input_fields, CeedOperatorField **input_fields, CeedInt *num_output_fields,
441                                       CeedOperatorField **output_fields);
442 
443 CEED_EXTERN int  CeedOperatorAtPointsSetPoints(CeedOperator op, CeedElemRestriction rstr_points, CeedVector point_coords);
444 CEED_EXTERN int  CeedOperatorAtPointsGetPoints(CeedOperator op, CeedElemRestriction *rstr_points, CeedVector *point_coords);
445 CEED_EXTERN int  CeedOperatorIsAtPoints(CeedOperator op, bool *is_at_points);
446 CEED_EXTERN int  CeedOperatorCompositeAddSub(CeedOperator composite_op, CeedOperator sub_op);
447 CEED_EXTERN int  CeedOperatorCompositeGetNumSub(CeedOperator op, CeedInt *num_suboperators);
448 CEED_EXTERN int  CeedOperatorCompositeGetSubList(CeedOperator op, CeedOperator **sub_operators);
449 CEED_EXTERN int  CeedOperatorCompositeGetSubByName(CeedOperator op, const char *op_name, CeedOperator *sub_op);
450 CEED_EXTERN int  CeedOperatorCheckReady(CeedOperator op);
451 CEED_EXTERN int  CeedOperatorGetActiveVectorLengths(CeedOperator op, CeedSize *input_size, CeedSize *output_size);
452 CEED_EXTERN int  CeedOperatorSetQFunctionAssemblyReuse(CeedOperator op, bool reuse_assembly_data);
453 CEED_EXTERN int  CeedOperatorSetQFunctionAssemblyDataUpdateNeeded(CeedOperator op, bool needs_data_update);
454 CEED_EXTERN int  CeedOperatorLinearAssembleQFunction(CeedOperator op, CeedVector *assembled, CeedElemRestriction *rstr, CeedRequest *request);
455 CEED_EXTERN int  CeedOperatorLinearAssembleQFunctionBuildOrUpdate(CeedOperator op, CeedVector *assembled, CeedElemRestriction *rstr,
456                                                                   CeedRequest *request);
457 CEED_EXTERN int  CeedOperatorLinearAssembleDiagonal(CeedOperator op, CeedVector assembled, CeedRequest *request);
458 CEED_EXTERN int  CeedOperatorLinearAssembleAddDiagonal(CeedOperator op, CeedVector assembled, CeedRequest *request);
459 CEED_EXTERN int  CeedOperatorLinearAssemblePointBlockDiagonal(CeedOperator op, CeedVector assembled, CeedRequest *request);
460 CEED_EXTERN int  CeedOperatorLinearAssembleAddPointBlockDiagonal(CeedOperator op, CeedVector assembled, CeedRequest *request);
461 CEED_EXTERN int  CeedOperatorLinearAssemblePointBlockDiagonalSymbolic(CeedOperator op, CeedSize *num_entries, CeedInt **rows, CeedInt **cols);
462 CEED_EXTERN int  CeedOperatorLinearAssembleSymbolic(CeedOperator op, CeedSize *num_entries, CeedInt **rows, CeedInt **cols);
463 CEED_EXTERN int  CeedOperatorLinearAssembleGetNumEntries(CeedOperator op, CeedSize *num_entries);
464 CEED_EXTERN int  CeedOperatorLinearAssemble(CeedOperator op, CeedVector values);
465 CEED_EXTERN int  CeedOperatorCompositeGetMultiplicity(CeedOperator op, CeedInt num_skip_indices, CeedInt *skip_indices, CeedVector mult);
466 CEED_EXTERN int  CeedOperatorMultigridLevelCreate(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse,
467                                                   CeedBasis basis_coarse, CeedOperator *op_coarse, CeedOperator *op_prolong,
468                                                   CeedOperator *op_restrict);
469 CEED_EXTERN int  CeedOperatorMultigridLevelCreateTensorH1(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse,
470                                                           CeedBasis basis_coarse, const CeedScalar *interp_c_to_f, CeedOperator *op_coarse,
471                                                           CeedOperator *op_prolong, CeedOperator *op_restrict);
472 CEED_EXTERN int  CeedOperatorMultigridLevelCreateH1(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse,
473                                                     CeedBasis basis_coarse, const CeedScalar *interp_c_to_f, CeedOperator *op_coarse,
474                                                     CeedOperator *op_prolong, CeedOperator *op_restrict);
475 CEED_EXTERN int  CeedOperatorCreateFDMElementInverse(CeedOperator op, CeedOperator *fdm_inv, CeedRequest *request);
476 CEED_EXTERN int  CeedOperatorSetName(CeedOperator op, const char *name);
477 CEED_EXTERN int  CeedOperatorGetName(CeedOperator op, const char **name);
478 CEED_EXTERN int  CeedOperatorSetNumViewTabs(CeedOperator op, CeedInt num_tabs);
479 CEED_EXTERN int  CeedOperatorGetNumViewTabs(CeedOperator op, CeedInt *num_tabs);
480 CEED_EXTERN int  CeedOperatorView(CeedOperator op, FILE *stream);
481 CEED_EXTERN int  CeedOperatorViewTerse(CeedOperator op, FILE *stream);
482 CEED_EXTERN int  CeedOperatorGetCeed(CeedOperator op, Ceed *ceed);
483 CEED_EXTERN Ceed CeedOperatorReturnCeed(CeedOperator op);
484 CEED_EXTERN int  CeedOperatorGetNumElements(CeedOperator op, CeedInt *num_elem);
485 CEED_EXTERN int  CeedOperatorGetNumQuadraturePoints(CeedOperator op, CeedInt *num_qpts);
486 CEED_EXTERN int  CeedOperatorGetFlopsEstimate(CeedOperator op, CeedSize *flops);
487 CEED_EXTERN int  CeedOperatorGetContext(CeedOperator op, CeedQFunctionContext *ctx);
488 CEED_EXTERN int  CeedOperatorGetContextFieldLabel(CeedOperator op, const char *field_name, CeedContextFieldLabel *field_label);
489 CEED_EXTERN int  CeedOperatorSetContextDouble(CeedOperator op, CeedContextFieldLabel field_label, double *values);
490 CEED_EXTERN int  CeedOperatorGetContextDoubleRead(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const double **values);
491 CEED_EXTERN int  CeedOperatorRestoreContextDoubleRead(CeedOperator op, CeedContextFieldLabel field_label, const double **values);
492 CEED_EXTERN int  CeedOperatorSetContextInt32(CeedOperator op, CeedContextFieldLabel field_label, int32_t *values);
493 CEED_EXTERN int  CeedOperatorGetContextInt32Read(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const int32_t **values);
494 CEED_EXTERN int  CeedOperatorRestoreContextInt32Read(CeedOperator op, CeedContextFieldLabel field_label, const int32_t **values);
495 CEED_EXTERN int  CeedOperatorSetContextBoolean(CeedOperator op, CeedContextFieldLabel field_label, bool *values);
496 CEED_EXTERN int  CeedOperatorGetContextBooleanRead(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const bool **values);
497 CEED_EXTERN int  CeedOperatorRestoreContextBooleanRead(CeedOperator op, CeedContextFieldLabel field_label, const bool **values);
498 CEED_EXTERN int  CeedOperatorApply(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request);
499 CEED_EXTERN int  CeedOperatorApplyAdd(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request);
500 CEED_EXTERN int  CeedOperatorApplyAddActive(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request);
501 CEED_EXTERN int  CeedOperatorAssemblyDataStrip(CeedOperator op);
502 CEED_EXTERN int  CeedOperatorDestroy(CeedOperator *op);
503 
504 // Compatibility with previous composite CeedOperator naming
505 #include "deprecated.h"
506 
507 CEED_EXTERN int CeedOperatorGetFieldByName(CeedOperator op, const char *field_name, CeedOperatorField *op_field);
508 CEED_EXTERN int CeedOperatorFieldGetName(CeedOperatorField op_field, const char **field_name);
509 CEED_EXTERN int CeedOperatorFieldGetElemRestriction(CeedOperatorField op_field, CeedElemRestriction *rstr);
510 CEED_EXTERN int CeedOperatorFieldGetBasis(CeedOperatorField op_field, CeedBasis *basis);
511 CEED_EXTERN int CeedOperatorFieldGetVector(CeedOperatorField op_field, CeedVector *vec);
512 CEED_EXTERN int CeedOperatorFieldGetData(CeedOperatorField op_field, const char **field_name, CeedElemRestriction *rstr, CeedBasis *basis,
513                                          CeedVector *vec);
514 
515 /**
516   @brief Return integer power
517 
518   @param[in] base  The base to exponentiate
519   @param[in] power The power to raise the base to
520 
521   @return base^power
522 
523   @ref Utility
524 **/
525 static inline CeedInt CeedIntPow(CeedInt base, CeedInt power) {
526   CeedInt result = 1;
527   while (power) {
528     if (power & 1) result *= base;
529     power >>= 1;
530     base *= base;
531   }
532   return result;
533 }
534 
535 /**
536   @brief Return minimum of two integers
537 
538   @param[in] a The first integer to compare
539   @param[in] b The second integer to compare
540 
541   @return The minimum of the two integers
542 
543   @ref Utility
544 **/
545 static inline CeedInt CeedIntMin(CeedInt a, CeedInt b) { return a < b ? a : b; }
546 
547 /**
548   @brief Return maximum of two integers
549 
550   @param[in] a The first integer to compare
551   @param[in] b The second integer to compare
552 
553   @return The maximum of the two integers
554 
555   @ref Utility
556 **/
557 static inline CeedInt CeedIntMax(CeedInt a, CeedInt b) { return a > b ? a : b; }
558 
559 // Used to ensure initialization before CeedInit()
560 CEED_EXTERN int CeedRegisterAll(void);
561 // Used to ensure initialization before CeedQFunctionCreate*()
562 CEED_EXTERN int CeedQFunctionRegisterAll(void);
563