xref: /libCEED/rust/libceed-sys/c-src/interface/ceed-basis.c (revision a82cd097ff20f09688a65f4c4c86d934c8731d68)
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 #include <ceed-impl.h>
9 #include <ceed.h>
10 #include <ceed/backend.h>
11 #include <math.h>
12 #include <stdbool.h>
13 #include <stdio.h>
14 #include <string.h>
15 
16 /// @file
17 /// Implementation of CeedBasis interfaces
18 
19 /// @cond DOXYGEN_SKIP
20 static struct CeedBasis_private ceed_basis_none;
21 /// @endcond
22 
23 /// @addtogroup CeedBasisUser
24 /// @{
25 
26 /// Argument for @ref CeedOperatorSetField() indicating that the field does not require a `CeedBasis`
27 const CeedBasis CEED_BASIS_NONE = &ceed_basis_none;
28 
29 /// @}
30 
31 /// ----------------------------------------------------------------------------
32 /// CeedBasis Library Internal Functions
33 /// ----------------------------------------------------------------------------
34 /// @addtogroup CeedBasisDeveloper
35 /// @{
36 
37 /**
38   @brief Compute Chebyshev polynomial values at a point
39 
40   @param[in]  x           Coordinate to evaluate Chebyshev polynomials at
41   @param[in]  n           Number of Chebyshev polynomials to evaluate, `n >= 2`
42   @param[out] chebyshev_x Array of Chebyshev polynomial values
43 
44   @return An error code: 0 - success, otherwise - failure
45 
46   @ref Developer
47 **/
48 static int CeedChebyshevPolynomialsAtPoint(CeedScalar x, CeedInt n, CeedScalar *chebyshev_x) {
49   chebyshev_x[0] = 1.0;
50   chebyshev_x[1] = 2 * x;
51   for (CeedInt i = 2; i < n; i++) chebyshev_x[i] = 2 * x * chebyshev_x[i - 1] - chebyshev_x[i - 2];
52   return CEED_ERROR_SUCCESS;
53 }
54 
55 /**
56   @brief Compute values of the derivative of Chebyshev polynomials at a point
57 
58   @param[in]  x            Coordinate to evaluate derivative of Chebyshev polynomials at
59   @param[in]  n            Number of Chebyshev polynomials to evaluate, `n >= 2`
60   @param[out] chebyshev_dx Array of Chebyshev polynomial derivative values
61 
62   @return An error code: 0 - success, otherwise - failure
63 
64   @ref Developer
65 **/
66 static int CeedChebyshevDerivativeAtPoint(CeedScalar x, CeedInt n, CeedScalar *chebyshev_dx) {
67   CeedScalar chebyshev_x[3];
68 
69   chebyshev_x[1]  = 1.0;
70   chebyshev_x[2]  = 2 * x;
71   chebyshev_dx[0] = 0.0;
72   chebyshev_dx[1] = 2.0;
73   for (CeedInt i = 2; i < n; i++) {
74     chebyshev_x[0]  = chebyshev_x[1];
75     chebyshev_x[1]  = chebyshev_x[2];
76     chebyshev_x[2]  = 2 * x * chebyshev_x[1] - chebyshev_x[0];
77     chebyshev_dx[i] = 2 * x * chebyshev_dx[i - 1] + 2 * chebyshev_x[1] - chebyshev_dx[i - 2];
78   }
79   return CEED_ERROR_SUCCESS;
80 }
81 
82 /**
83   @brief Compute Householder reflection.
84 
85   Computes \f$A = (I - b v v^T) A\f$, where \f$A\f$ is an \f$m \times n\f$ matrix indexed as `A[i*row + j*col]`.
86 
87   @param[in,out] A   Matrix to apply Householder reflection to, in place
88   @param[in]     v   Householder vector
89   @param[in]     b   Scaling factor
90   @param[in]     m   Number of rows in `A`
91   @param[in]     n   Number of columns in `A`
92   @param[in]     row Row stride
93   @param[in]     col Col stride
94 
95   @return An error code: 0 - success, otherwise - failure
96 
97   @ref Developer
98 **/
99 static int CeedHouseholderReflect(CeedScalar *A, const CeedScalar *v, CeedScalar b, CeedInt m, CeedInt n, CeedInt row, CeedInt col) {
100   for (CeedInt j = 0; j < n; j++) {
101     CeedScalar w = A[0 * row + j * col];
102 
103     for (CeedInt i = 1; i < m; i++) w += v[i] * A[i * row + j * col];
104     A[0 * row + j * col] -= b * w;
105     for (CeedInt i = 1; i < m; i++) A[i * row + j * col] -= b * w * v[i];
106   }
107   return CEED_ERROR_SUCCESS;
108 }
109 
110 /**
111   @brief Compute Givens rotation
112 
113   Computes \f$A = G A\f$ (or \f$G^T A\f$ in transpose mode), where \f$A\f$ is an \f$m \times n\f$ matrix indexed as `A[i*n + j*m]`.
114 
115   @param[in,out] A      Row major matrix to apply Givens rotation to, in place
116   @param[in]     c      Cosine factor
117   @param[in]     s      Sine factor
118   @param[in]     t_mode @ref CEED_NOTRANSPOSE to rotate the basis counter-clockwise, which has the effect of rotating columns of `A` clockwise;
119                           @ref CEED_TRANSPOSE for the opposite rotation
120   @param[in]     i      First row/column to apply rotation
121   @param[in]     k      Second row/column to apply rotation
122   @param[in]     m      Number of rows in `A`
123   @param[in]     n      Number of columns in `A`
124 
125   @return An error code: 0 - success, otherwise - failure
126 
127   @ref Developer
128 **/
129 static int CeedGivensRotation(CeedScalar *A, CeedScalar c, CeedScalar s, CeedTransposeMode t_mode, CeedInt i, CeedInt k, CeedInt m, CeedInt n) {
130   CeedInt stride_j = 1, stride_ik = m, num_its = n;
131 
132   if (t_mode == CEED_NOTRANSPOSE) {
133     stride_j  = n;
134     stride_ik = 1;
135     num_its   = m;
136   }
137 
138   // Apply rotation
139   for (CeedInt j = 0; j < num_its; j++) {
140     CeedScalar tau1 = A[i * stride_ik + j * stride_j], tau2 = A[k * stride_ik + j * stride_j];
141 
142     A[i * stride_ik + j * stride_j] = c * tau1 - s * tau2;
143     A[k * stride_ik + j * stride_j] = s * tau1 + c * tau2;
144   }
145   return CEED_ERROR_SUCCESS;
146 }
147 
148 /**
149   @brief View an array stored in a `CeedBasis`
150 
151   @param[in] name   Name of array
152   @param[in] fp_fmt Printing format
153   @param[in] m      Number of rows in array
154   @param[in] n      Number of columns in array
155   @param[in] a      Array to be viewed
156   @param[in] stream Stream to view to, e.g., `stdout`
157 
158   @return An error code: 0 - success, otherwise - failure
159 
160   @ref Developer
161 **/
162 static int CeedScalarView(const char *name, const char *fp_fmt, CeedInt m, CeedInt n, const CeedScalar *a, FILE *stream) {
163   if (m > 1) {
164     fprintf(stream, "  %s:\n", name);
165   } else {
166     char padded_name[12];
167 
168     snprintf(padded_name, 11, "%s:", name);
169     fprintf(stream, "  %-10s", padded_name);
170   }
171   for (CeedInt i = 0; i < m; i++) {
172     if (m > 1) fprintf(stream, "    [%" CeedInt_FMT "]", i);
173     for (CeedInt j = 0; j < n; j++) fprintf(stream, fp_fmt, fabs(a[i * n + j]) > 1E-14 ? a[i * n + j] : 0);
174     fputs("\n", stream);
175   }
176   return CEED_ERROR_SUCCESS;
177 }
178 
179 /**
180   @brief Create the interpolation and gradient matrices for projection from the nodes of `basis_from` to the nodes of `basis_to`.
181 
182   The interpolation is given by `interp_project = interp_to^+ * interp_from`, where the pseudoinverse `interp_to^+` is given by QR factorization.
183   The gradient is given by `grad_project = interp_to^+ * grad_from`, and is only computed for \f$H^1\f$ spaces otherwise it should not be used.
184 
185   Note: `basis_from` and `basis_to` must have compatible quadrature spaces.
186 
187   @param[in]  basis_from     `CeedBasis` to project from
188   @param[in]  basis_to       `CeedBasis` to project to
189   @param[out] interp_project Address of the variable where the newly created interpolation matrix will be stored
190   @param[out] grad_project   Address of the variable where the newly created gradient matrix will be stored
191 
192   @return An error code: 0 - success, otherwise - failure
193 
194   @ref Developer
195 **/
196 static int CeedBasisCreateProjectionMatrices(CeedBasis basis_from, CeedBasis basis_to, CeedScalar **interp_project, CeedScalar **grad_project) {
197   bool    are_both_tensor;
198   CeedInt Q, Q_to, Q_from, P_to, P_from;
199 
200   // Check for compatible quadrature spaces
201   CeedCall(CeedBasisGetNumQuadraturePoints(basis_to, &Q_to));
202   CeedCall(CeedBasisGetNumQuadraturePoints(basis_from, &Q_from));
203   CeedCheck(Q_to == Q_from, CeedBasisReturnCeed(basis_to), CEED_ERROR_DIMENSION,
204             "Bases must have compatible quadrature spaces."
205             " 'basis_from' has %" CeedInt_FMT " points and 'basis_to' has %" CeedInt_FMT,
206             Q_from, Q_to);
207   Q = Q_to;
208 
209   // Check for matching tensor or non-tensor
210   {
211     bool is_tensor_to, is_tensor_from;
212 
213     CeedCall(CeedBasisIsTensor(basis_to, &is_tensor_to));
214     CeedCall(CeedBasisIsTensor(basis_from, &is_tensor_from));
215     are_both_tensor = is_tensor_to && is_tensor_from;
216   }
217   if (are_both_tensor) {
218     CeedCall(CeedBasisGetNumNodes1D(basis_to, &P_to));
219     CeedCall(CeedBasisGetNumNodes1D(basis_from, &P_from));
220     CeedCall(CeedBasisGetNumQuadraturePoints1D(basis_from, &Q));
221   } else {
222     CeedCall(CeedBasisGetNumNodes(basis_to, &P_to));
223     CeedCall(CeedBasisGetNumNodes(basis_from, &P_from));
224   }
225 
226   // Check for matching FE space
227   CeedFESpace fe_space_to, fe_space_from;
228 
229   CeedCall(CeedBasisGetFESpace(basis_to, &fe_space_to));
230   CeedCall(CeedBasisGetFESpace(basis_from, &fe_space_from));
231   CeedCheck(fe_space_to == fe_space_from, CeedBasisReturnCeed(basis_to), CEED_ERROR_MINOR,
232             "Bases must both be the same FE space type."
233             " 'basis_from' is a %s and 'basis_to' is a %s",
234             CeedFESpaces[fe_space_from], CeedFESpaces[fe_space_to]);
235 
236   // Get source matrices
237   CeedInt           dim, q_comp = 1;
238   CeedScalar       *interp_to_inv, *interp_from;
239   const CeedScalar *interp_to_source = NULL, *interp_from_source = NULL, *grad_from_source = NULL;
240 
241   CeedCall(CeedBasisGetDimension(basis_from, &dim));
242   if (are_both_tensor) {
243     CeedCall(CeedBasisGetInterp1D(basis_to, &interp_to_source));
244     CeedCall(CeedBasisGetInterp1D(basis_from, &interp_from_source));
245   } else {
246     CeedCall(CeedBasisGetNumQuadratureComponents(basis_from, CEED_EVAL_INTERP, &q_comp));
247     CeedCall(CeedBasisGetInterp(basis_to, &interp_to_source));
248     CeedCall(CeedBasisGetInterp(basis_from, &interp_from_source));
249   }
250   CeedCall(CeedMalloc(Q * P_from * q_comp, &interp_from));
251   CeedCall(CeedCalloc(P_to * P_from, interp_project));
252 
253   // `grad_project = interp_to^+ * grad_from` is computed for the H^1 space case so the
254   // projection basis will have a gradient operation (allocated even if not H^1 for the
255   // basis construction later on)
256   if (fe_space_to == CEED_FE_SPACE_H1) {
257     if (are_both_tensor) {
258       CeedCall(CeedBasisGetGrad1D(basis_from, &grad_from_source));
259     } else {
260       CeedCall(CeedBasisGetGrad(basis_from, &grad_from_source));
261     }
262   }
263   CeedCall(CeedCalloc(P_to * P_from * (are_both_tensor ? 1 : dim), grad_project));
264 
265   // Compute interp_to^+, pseudoinverse of interp_to
266   CeedCall(CeedCalloc(Q * q_comp * P_to, &interp_to_inv));
267   CeedCall(CeedMatrixPseudoinverse(CeedBasisReturnCeed(basis_to), interp_to_source, Q * q_comp, P_to, interp_to_inv));
268   // Build matrices
269   CeedInt     num_matrices = 1 + (fe_space_to == CEED_FE_SPACE_H1) * (are_both_tensor ? 1 : dim);
270   CeedScalar *input_from[num_matrices], *output_project[num_matrices];
271 
272   input_from[0]     = (CeedScalar *)interp_from_source;
273   output_project[0] = *interp_project;
274   for (CeedInt m = 1; m < num_matrices; m++) {
275     input_from[m]     = (CeedScalar *)&grad_from_source[(m - 1) * Q * P_from];
276     output_project[m] = &((*grad_project)[(m - 1) * P_to * P_from]);
277   }
278   for (CeedInt m = 0; m < num_matrices; m++) {
279     // output_project = interp_to^+ * interp_from
280     memcpy(interp_from, input_from[m], Q * P_from * q_comp * sizeof(input_from[m][0]));
281     CeedCall(CeedMatrixMatrixMultiply(CeedBasisReturnCeed(basis_to), interp_to_inv, input_from[m], output_project[m], P_to, P_from, Q * q_comp));
282     // Round zero to machine precision
283     for (CeedInt i = 0; i < P_to * P_from; i++) {
284       if (fabs(output_project[m][i]) < 10 * CEED_EPSILON) output_project[m][i] = 0.0;
285     }
286   }
287 
288   // Cleanup
289   CeedCall(CeedFree(&interp_to_inv));
290   CeedCall(CeedFree(&interp_from));
291   return CEED_ERROR_SUCCESS;
292 }
293 
294 /**
295   @brief Check input vector dimensions for CeedBasisApply[Add]
296 
297   @param[in]  basis     `CeedBasis` to evaluate
298   @param[in]  num_elem  The number of elements to apply the basis evaluation to;
299                           the backend will specify the ordering in @ref CeedElemRestrictionCreate()
300   @param[in]  t_mode    @ref CEED_NOTRANSPOSE to evaluate from nodes to quadrature points;
301                           @ref CEED_TRANSPOSE to apply the transpose, mapping from quadrature points to nodes
302   @param[in]  eval_mode @ref CEED_EVAL_NONE to use values directly,
303                           @ref CEED_EVAL_INTERP to use interpolated values,
304                           @ref CEED_EVAL_GRAD to use gradients,
305                           @ref CEED_EVAL_DIV to use divergence,
306                           @ref CEED_EVAL_CURL to use curl,
307                           @ref CEED_EVAL_WEIGHT to use quadrature weights
308   @param[in]  u         Input `CeedVector`
309   @param[out] v         Output `CeedVector`
310 
311   @return An error code: 0 - success, otherwise - failure
312 
313   @ref Developer
314 **/
315 static int CeedBasisApplyCheckDims(CeedBasis basis, CeedInt num_elem, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedVector u, CeedVector v) {
316   CeedInt  dim, num_comp, q_comp, num_nodes, num_qpts;
317   CeedSize u_length = 0, v_length;
318 
319   CeedCall(CeedBasisGetDimension(basis, &dim));
320   CeedCall(CeedBasisGetNumComponents(basis, &num_comp));
321   CeedCall(CeedBasisGetNumQuadratureComponents(basis, eval_mode, &q_comp));
322   CeedCall(CeedBasisGetNumNodes(basis, &num_nodes));
323   CeedCall(CeedBasisGetNumQuadraturePoints(basis, &num_qpts));
324   CeedCall(CeedVectorGetLength(v, &v_length));
325   if (u) CeedCall(CeedVectorGetLength(u, &u_length));
326 
327   // Check vector lengths to prevent out of bounds issues
328   bool has_good_dims = true;
329   switch (eval_mode) {
330     case CEED_EVAL_NONE:
331     case CEED_EVAL_INTERP:
332     case CEED_EVAL_GRAD:
333     case CEED_EVAL_DIV:
334     case CEED_EVAL_CURL:
335       has_good_dims = ((t_mode == CEED_TRANSPOSE && u_length >= (CeedSize)num_elem * (CeedSize)num_comp * (CeedSize)num_qpts * (CeedSize)q_comp &&
336                         v_length >= (CeedSize)num_elem * (CeedSize)num_comp * (CeedSize)num_nodes) ||
337                        (t_mode == CEED_NOTRANSPOSE && v_length >= (CeedSize)num_elem * (CeedSize)num_qpts * (CeedSize)num_comp * (CeedSize)q_comp &&
338                         u_length >= (CeedSize)num_elem * (CeedSize)num_comp * (CeedSize)num_nodes));
339       break;
340     case CEED_EVAL_WEIGHT:
341       has_good_dims = v_length >= (CeedSize)num_elem * (CeedSize)num_qpts;
342       break;
343   }
344   CeedCheck(has_good_dims, CeedBasisReturnCeed(basis), CEED_ERROR_DIMENSION, "Input/output vectors too short for basis and evaluation mode");
345   return CEED_ERROR_SUCCESS;
346 }
347 
348 /**
349   @brief Check input vector dimensions for CeedBasisApply[Add]AtPoints
350 
351   @param[in]  basis      `CeedBasis` to evaluate
352   @param[in]  num_elem   The number of elements to apply the basis evaluation to;
353                           the backend will specify the ordering in @ref CeedElemRestrictionCreate()
354   @param[in]  num_points Array of the number of points to apply the basis evaluation to in each element, size `num_elem`
355   @param[in]  t_mode     @ref CEED_NOTRANSPOSE to evaluate from nodes to points;
356                            @ref CEED_TRANSPOSE to apply the transpose, mapping from points to nodes
357   @param[in]  eval_mode  @ref CEED_EVAL_INTERP to use interpolated values,
358                            @ref CEED_EVAL_GRAD to use gradients,
359                            @ref CEED_EVAL_WEIGHT to use quadrature weights
360   @param[in]  x_ref      `CeedVector` holding reference coordinates of each point
361   @param[in]  u          Input `CeedVector`, of length `num_nodes * num_comp` for @ref CEED_NOTRANSPOSE
362   @param[out] v          Output `CeedVector`, of length `num_points * num_q_comp` for @ref CEED_NOTRANSPOSE with @ref CEED_EVAL_INTERP
363 
364   @return An error code: 0 - success, otherwise - failure
365 
366   @ref Developer
367 **/
368 static int CeedBasisApplyAtPointsCheckDims(CeedBasis basis, CeedInt num_elem, const CeedInt *num_points, CeedTransposeMode t_mode,
369                                            CeedEvalMode eval_mode, CeedVector x_ref, CeedVector u, CeedVector v) {
370   CeedInt  dim, num_comp, num_q_comp, num_nodes, P_1d = 1, Q_1d = 1, total_num_points = 0;
371   CeedSize x_length = 0, u_length = 0, v_length;
372 
373   CeedCall(CeedBasisGetDimension(basis, &dim));
374   CeedCall(CeedBasisGetNumNodes1D(basis, &P_1d));
375   CeedCall(CeedBasisGetNumQuadraturePoints1D(basis, &Q_1d));
376   CeedCall(CeedBasisGetNumComponents(basis, &num_comp));
377   CeedCall(CeedBasisGetNumQuadratureComponents(basis, eval_mode, &num_q_comp));
378   CeedCall(CeedBasisGetNumNodes(basis, &num_nodes));
379   CeedCall(CeedVectorGetLength(v, &v_length));
380   if (x_ref != CEED_VECTOR_NONE) CeedCall(CeedVectorGetLength(x_ref, &x_length));
381   if (u != CEED_VECTOR_NONE) CeedCall(CeedVectorGetLength(u, &u_length));
382 
383   // Check compatibility coordinates vector
384   for (CeedInt i = 0; i < num_elem; i++) total_num_points += num_points[i];
385   CeedCheck((x_length >= (CeedSize)total_num_points * (CeedSize)dim) || (eval_mode == CEED_EVAL_WEIGHT), CeedBasisReturnCeed(basis),
386             CEED_ERROR_DIMENSION,
387             "Length of reference coordinate vector incompatible with basis dimension and number of points."
388             " Found reference coordinate vector of length %" CeedSize_FMT ", not of length %" CeedSize_FMT ".",
389             x_length, (CeedSize)total_num_points * (CeedSize)dim);
390 
391   // Check CEED_EVAL_WEIGHT only on CEED_NOTRANSPOSE
392   CeedCheck(eval_mode != CEED_EVAL_WEIGHT || t_mode == CEED_NOTRANSPOSE, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED,
393             "CEED_EVAL_WEIGHT only supported with CEED_NOTRANSPOSE");
394 
395   // Check vector lengths to prevent out of bounds issues
396   bool has_good_dims = true;
397   switch (eval_mode) {
398     case CEED_EVAL_INTERP:
399       has_good_dims = ((t_mode == CEED_TRANSPOSE && (u_length >= (CeedSize)total_num_points * (CeedSize)num_q_comp ||
400                                                      v_length >= (CeedSize)num_elem * (CeedSize)num_nodes * (CeedSize)num_comp)) ||
401                        (t_mode == CEED_NOTRANSPOSE && (v_length >= (CeedSize)total_num_points * (CeedSize)num_q_comp ||
402                                                        u_length >= (CeedSize)num_elem * (CeedSize)num_nodes * (CeedSize)num_comp)));
403       break;
404     case CEED_EVAL_GRAD:
405       has_good_dims = ((t_mode == CEED_TRANSPOSE && (u_length >= (CeedSize)total_num_points * (CeedSize)num_q_comp * (CeedSize)dim ||
406                                                      v_length >= (CeedSize)num_elem * (CeedSize)num_nodes * (CeedSize)num_comp)) ||
407                        (t_mode == CEED_NOTRANSPOSE && (v_length >= (CeedSize)total_num_points * (CeedSize)num_q_comp * (CeedSize)dim ||
408                                                        u_length >= (CeedSize)num_elem * (CeedSize)num_nodes * (CeedSize)num_comp)));
409       break;
410     case CEED_EVAL_WEIGHT:
411       has_good_dims = t_mode == CEED_NOTRANSPOSE && (v_length >= total_num_points);
412       break;
413       // LCOV_EXCL_START
414     case CEED_EVAL_NONE:
415     case CEED_EVAL_DIV:
416     case CEED_EVAL_CURL:
417       return CeedError(CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED, "Evaluation at arbitrary points not supported for %s",
418                        CeedEvalModes[eval_mode]);
419       // LCOV_EXCL_STOP
420   }
421   CeedCheck(has_good_dims, CeedBasisReturnCeed(basis), CEED_ERROR_DIMENSION, "Input/output vectors too short for basis and evaluation mode");
422   return CEED_ERROR_SUCCESS;
423 }
424 
425 /**
426   @brief Default implimentation to apply basis evaluation from nodes to arbitrary points
427 
428   @param[in]  basis      `CeedBasis` to evaluate
429   @param[in]  apply_add  Sum result into target vector or overwrite
430   @param[in]  num_elem   The number of elements to apply the basis evaluation to;
431                           the backend will specify the ordering in @ref CeedElemRestrictionCreate()
432   @param[in]  num_points Array of the number of points to apply the basis evaluation to in each element, size `num_elem`
433   @param[in]  t_mode     @ref CEED_NOTRANSPOSE to evaluate from nodes to points;
434                            @ref CEED_TRANSPOSE to apply the transpose, mapping from points to nodes
435   @param[in]  eval_mode  @ref CEED_EVAL_INTERP to use interpolated values,
436                            @ref CEED_EVAL_GRAD to use gradients,
437                            @ref CEED_EVAL_WEIGHT to use quadrature weights
438   @param[in]  x_ref      `CeedVector` holding reference coordinates of each point
439   @param[in]  u          Input `CeedVector`, of length `num_nodes * num_comp` for @ref CEED_NOTRANSPOSE
440   @param[out] v          Output `CeedVector`, of length `num_points * num_q_comp` for @ref CEED_NOTRANSPOSE with @ref CEED_EVAL_INTERP
441 
442   @return An error code: 0 - success, otherwise - failure
443 
444   @ref Developer
445 **/
446 static int CeedBasisApplyAtPoints_Core(CeedBasis basis, bool apply_add, CeedInt num_elem, const CeedInt *num_points, CeedTransposeMode t_mode,
447                                        CeedEvalMode eval_mode, CeedVector x_ref, CeedVector u, CeedVector v) {
448   CeedInt dim, num_comp, P_1d = 1, Q_1d = 1, total_num_points = num_points[0];
449 
450   CeedCall(CeedBasisGetDimension(basis, &dim));
451   // Inserting check because clang-tidy doesn't understand this cannot occur
452   CeedCheck(dim > 0, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED, "Malformed CeedBasis, dim > 0 is required");
453   CeedCall(CeedBasisGetNumNodes1D(basis, &P_1d));
454   CeedCall(CeedBasisGetNumQuadraturePoints1D(basis, &Q_1d));
455   CeedCall(CeedBasisGetNumComponents(basis, &num_comp));
456 
457   // Default implementation
458   {
459     bool is_tensor_basis;
460 
461     CeedCall(CeedBasisIsTensor(basis, &is_tensor_basis));
462     CeedCheck(is_tensor_basis, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED,
463               "Evaluation at arbitrary points only supported for tensor product bases");
464   }
465   CeedCheck(num_elem == 1, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED,
466             "Evaluation at arbitrary  points only supported for a single element at a time");
467   if (eval_mode == CEED_EVAL_WEIGHT) {
468     CeedCall(CeedVectorSetValue(v, 1.0));
469     return CEED_ERROR_SUCCESS;
470   }
471   if (!basis->basis_chebyshev) {
472     // Build basis mapping from nodes to Chebyshev coefficients
473     CeedScalar       *chebyshev_interp_1d, *chebyshev_grad_1d, *chebyshev_q_weight_1d;
474     const CeedScalar *q_ref_1d;
475     Ceed              ceed;
476 
477     CeedCall(CeedCalloc(P_1d * Q_1d, &chebyshev_interp_1d));
478     CeedCall(CeedCalloc(P_1d * Q_1d, &chebyshev_grad_1d));
479     CeedCall(CeedCalloc(Q_1d, &chebyshev_q_weight_1d));
480     CeedCall(CeedBasisGetQRef(basis, &q_ref_1d));
481     CeedCall(CeedBasisGetChebyshevInterp1D(basis, chebyshev_interp_1d));
482 
483     CeedCall(CeedBasisGetCeed(basis, &ceed));
484     CeedCall(CeedVectorCreate(ceed, num_comp * CeedIntPow(Q_1d, dim), &basis->vec_chebyshev));
485     CeedCall(CeedBasisCreateTensorH1(ceed, dim, num_comp, P_1d, Q_1d, chebyshev_interp_1d, chebyshev_grad_1d, q_ref_1d, chebyshev_q_weight_1d,
486                                      &basis->basis_chebyshev));
487 
488     // Cleanup
489     CeedCall(CeedFree(&chebyshev_interp_1d));
490     CeedCall(CeedFree(&chebyshev_grad_1d));
491     CeedCall(CeedFree(&chebyshev_q_weight_1d));
492     CeedCall(CeedDestroy(&ceed));
493   }
494 
495   // Create TensorContract object if needed, such as a basis from the GPU backends
496   if (!basis->contract) {
497     Ceed      ceed_ref;
498     CeedBasis basis_ref = NULL;
499 
500     CeedCall(CeedInit("/cpu/self", &ceed_ref));
501     // Only need matching tensor contraction dimensions, any type of basis will work
502     CeedCall(CeedBasisCreateTensorH1Lagrange(ceed_ref, dim, num_comp, P_1d, Q_1d, CEED_GAUSS, &basis_ref));
503     // Note - clang-tidy doesn't know basis_ref->contract must be valid here
504     CeedCheck(basis_ref && basis_ref->contract, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED,
505               "Reference CPU ceed failed to create a tensor contraction object");
506     CeedCall(CeedTensorContractReferenceCopy(basis_ref->contract, &basis->contract));
507     CeedCall(CeedBasisDestroy(&basis_ref));
508     CeedCall(CeedDestroy(&ceed_ref));
509   }
510 
511   // Basis evaluation
512   switch (t_mode) {
513     case CEED_NOTRANSPOSE: {
514       // Nodes to arbitrary points
515       CeedScalar       *v_array;
516       const CeedScalar *chebyshev_coeffs, *x_array_read;
517 
518       // -- Interpolate to Chebyshev coefficients
519       CeedCall(CeedBasisApply(basis->basis_chebyshev, 1, CEED_NOTRANSPOSE, CEED_EVAL_INTERP, u, basis->vec_chebyshev));
520 
521       // -- Evaluate Chebyshev polynomials at arbitrary points
522       CeedCall(CeedVectorGetArrayRead(basis->vec_chebyshev, CEED_MEM_HOST, &chebyshev_coeffs));
523       CeedCall(CeedVectorGetArrayRead(x_ref, CEED_MEM_HOST, &x_array_read));
524       CeedCall(CeedVectorGetArrayWrite(v, CEED_MEM_HOST, &v_array));
525       switch (eval_mode) {
526         case CEED_EVAL_INTERP: {
527           CeedScalar tmp[2][num_comp * CeedIntPow(Q_1d, dim)], chebyshev_x[Q_1d];
528 
529           // ---- Values at point
530           for (CeedInt p = 0; p < total_num_points; p++) {
531             CeedInt pre = num_comp * CeedIntPow(Q_1d, dim - 1), post = 1;
532 
533             for (CeedInt d = 0; d < dim; d++) {
534               // ------ Tensor contract with current Chebyshev polynomial values
535               CeedCall(CeedChebyshevPolynomialsAtPoint(x_array_read[d * total_num_points + p], Q_1d, chebyshev_x));
536               CeedCall(CeedTensorContractApply(basis->contract, pre, Q_1d, post, 1, chebyshev_x, t_mode, false,
537                                                d == 0 ? chebyshev_coeffs : tmp[d % 2], tmp[(d + 1) % 2]));
538               pre /= Q_1d;
539               post *= 1;
540             }
541             for (CeedInt c = 0; c < num_comp; c++) v_array[c * total_num_points + p] = tmp[dim % 2][c];
542           }
543           break;
544         }
545         case CEED_EVAL_GRAD: {
546           CeedScalar tmp[2][num_comp * CeedIntPow(Q_1d, dim)], chebyshev_x[Q_1d];
547 
548           // ---- Values at point
549           for (CeedInt p = 0; p < total_num_points; p++) {
550             // Dim**2 contractions, apply grad when pass == dim
551             for (CeedInt pass = 0; pass < dim; pass++) {
552               CeedInt pre = num_comp * CeedIntPow(Q_1d, dim - 1), post = 1;
553 
554               for (CeedInt d = 0; d < dim; d++) {
555                 // ------ Tensor contract with current Chebyshev polynomial values
556                 if (pass == d) CeedCall(CeedChebyshevDerivativeAtPoint(x_array_read[d * total_num_points + p], Q_1d, chebyshev_x));
557                 else CeedCall(CeedChebyshevPolynomialsAtPoint(x_array_read[d * total_num_points + p], Q_1d, chebyshev_x));
558                 CeedCall(CeedTensorContractApply(basis->contract, pre, Q_1d, post, 1, chebyshev_x, t_mode, false,
559                                                  d == 0 ? chebyshev_coeffs : tmp[d % 2], tmp[(d + 1) % 2]));
560                 pre /= Q_1d;
561                 post *= 1;
562               }
563               for (CeedInt c = 0; c < num_comp; c++) v_array[(pass * num_comp + c) * total_num_points + p] = tmp[dim % 2][c];
564             }
565           }
566           break;
567         }
568         default:
569           // Nothing to do, excluded above
570           break;
571       }
572       CeedCall(CeedVectorRestoreArrayRead(basis->vec_chebyshev, &chebyshev_coeffs));
573       CeedCall(CeedVectorRestoreArrayRead(x_ref, &x_array_read));
574       CeedCall(CeedVectorRestoreArray(v, &v_array));
575       break;
576     }
577     case CEED_TRANSPOSE: {
578       // Note: No switch on e_mode here because only CEED_EVAL_INTERP is supported at this time
579       // Arbitrary points to nodes
580       CeedScalar       *chebyshev_coeffs;
581       const CeedScalar *u_array, *x_array_read;
582 
583       // -- Transpose of evaluation of Chebyshev polynomials at arbitrary points
584       CeedCall(CeedVectorGetArrayWrite(basis->vec_chebyshev, CEED_MEM_HOST, &chebyshev_coeffs));
585       CeedCall(CeedVectorGetArrayRead(x_ref, CEED_MEM_HOST, &x_array_read));
586       CeedCall(CeedVectorGetArrayRead(u, CEED_MEM_HOST, &u_array));
587 
588       switch (eval_mode) {
589         case CEED_EVAL_INTERP: {
590           CeedScalar tmp[2][num_comp * CeedIntPow(Q_1d, dim)], chebyshev_x[Q_1d];
591 
592           // ---- Values at point
593           for (CeedInt p = 0; p < total_num_points; p++) {
594             CeedInt pre = num_comp * 1, post = 1;
595 
596             for (CeedInt c = 0; c < num_comp; c++) tmp[0][c] = u_array[c * total_num_points + p];
597             for (CeedInt d = 0; d < dim; d++) {
598               // ------ Tensor contract with current Chebyshev polynomial values
599               CeedCall(CeedChebyshevPolynomialsAtPoint(x_array_read[d * total_num_points + p], Q_1d, chebyshev_x));
600               CeedCall(CeedTensorContractApply(basis->contract, pre, 1, post, Q_1d, chebyshev_x, t_mode, p > 0 && d == (dim - 1), tmp[d % 2],
601                                                d == (dim - 1) ? chebyshev_coeffs : tmp[(d + 1) % 2]));
602               pre /= 1;
603               post *= Q_1d;
604             }
605           }
606           break;
607         }
608         case CEED_EVAL_GRAD: {
609           CeedScalar tmp[2][num_comp * CeedIntPow(Q_1d, dim)], chebyshev_x[Q_1d];
610 
611           // ---- Values at point
612           for (CeedInt p = 0; p < total_num_points; p++) {
613             // Dim**2 contractions, apply grad when pass == dim
614             for (CeedInt pass = 0; pass < dim; pass++) {
615               CeedInt pre = num_comp * 1, post = 1;
616 
617               for (CeedInt c = 0; c < num_comp; c++) tmp[0][c] = u_array[(pass * num_comp + c) * total_num_points + p];
618               for (CeedInt d = 0; d < dim; d++) {
619                 // ------ Tensor contract with current Chebyshev polynomial values
620                 if (pass == d) CeedCall(CeedChebyshevDerivativeAtPoint(x_array_read[d * total_num_points + p], Q_1d, chebyshev_x));
621                 else CeedCall(CeedChebyshevPolynomialsAtPoint(x_array_read[d * total_num_points + p], Q_1d, chebyshev_x));
622                 CeedCall(CeedTensorContractApply(basis->contract, pre, 1, post, Q_1d, chebyshev_x, t_mode,
623                                                  (p > 0 || (p == 0 && pass > 0)) && d == (dim - 1), tmp[d % 2],
624                                                  d == (dim - 1) ? chebyshev_coeffs : tmp[(d + 1) % 2]));
625                 pre /= 1;
626                 post *= Q_1d;
627               }
628             }
629           }
630           break;
631         }
632         default:
633           // Nothing to do, excluded above
634           break;
635       }
636       CeedCall(CeedVectorRestoreArray(basis->vec_chebyshev, &chebyshev_coeffs));
637       CeedCall(CeedVectorRestoreArrayRead(x_ref, &x_array_read));
638       CeedCall(CeedVectorRestoreArrayRead(u, &u_array));
639 
640       // -- Interpolate transpose from Chebyshev coefficients
641       if (apply_add) CeedCall(CeedBasisApplyAdd(basis->basis_chebyshev, 1, CEED_TRANSPOSE, CEED_EVAL_INTERP, basis->vec_chebyshev, v));
642       else CeedCall(CeedBasisApply(basis->basis_chebyshev, 1, CEED_TRANSPOSE, CEED_EVAL_INTERP, basis->vec_chebyshev, v));
643       break;
644     }
645   }
646   return CEED_ERROR_SUCCESS;
647 }
648 
649 /// @}
650 
651 /// ----------------------------------------------------------------------------
652 /// Ceed Backend API
653 /// ----------------------------------------------------------------------------
654 /// @addtogroup CeedBasisBackend
655 /// @{
656 
657 /**
658   @brief Fallback to a reference implementation for a non tensor-product basis for \f$H^1\f$ discretizations.
659     This function may only be called inside of a backend `BasisCreateH1` function.
660     This is used by a backend when the specific parameters for a `CeedBasis` exceed the backend's support, such as
661     when a `interp` and `grad` matrices require too many bytes to fit into shared memory on a GPU.
662 
663   @param[in]  ceed      `Ceed` object used to create the `CeedBasis`
664   @param[in]  topo      Topology of element, e.g. hypercube, simplex, etc
665   @param[in]  num_comp  Number of field components (1 for scalar fields)
666   @param[in]  num_nodes Total number of nodes
667   @param[in]  num_qpts  Total number of quadrature points
668   @param[in]  interp    Row-major (`num_qpts * num_nodes`) matrix expressing the values of nodal basis functions at quadrature points
669   @param[in]  grad      Row-major (`dim * num_qpts * num_nodes`) matrix expressing derivatives of nodal basis functions at quadrature points
670   @param[in]  q_ref     Array of length `num_qpts * dim` holding the locations of quadrature points on the reference element
671   @param[in]  q_weight  Array of length `num_qpts` holding the quadrature weights on the reference element
672   @param[out] basis     Newly created `CeedBasis`
673 
674   @return An error code: 0 - success, otherwise - failure
675 
676   @ref User
677 **/
678 int CeedBasisCreateH1Fallback(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt num_qpts, const CeedScalar *interp,
679                               const CeedScalar *grad, const CeedScalar *q_ref, const CeedScalar *q_weight, CeedBasis basis) {
680   CeedInt P = num_nodes, Q = num_qpts, dim = 0;
681   Ceed    delegate;
682 
683   CeedCall(CeedGetObjectDelegate(ceed, &delegate, "Basis"));
684   CeedCheck(delegate, ceed, CEED_ERROR_UNSUPPORTED, "Backend does not implement BasisCreateH1");
685 
686   CeedCall(CeedReferenceCopy(delegate, &(basis)->ceed));
687   CeedCall(CeedBasisGetTopologyDimension(topo, &dim));
688   CeedCall(delegate->BasisCreateH1(topo, dim, P, Q, interp, grad, q_ref, q_weight, basis));
689   CeedCall(CeedDestroy(&delegate));
690   return CEED_ERROR_SUCCESS;
691 }
692 
693 /**
694   @brief Return collocated gradient matrix
695 
696   @param[in]  basis         `CeedBasis`
697   @param[out] collo_grad_1d Row-major (`Q_1d * Q_1d`) matrix expressing derivatives of basis functions at quadrature points
698 
699   @return An error code: 0 - success, otherwise - failure
700 
701   @ref Backend
702 **/
703 int CeedBasisGetCollocatedGrad(CeedBasis basis, CeedScalar *collo_grad_1d) {
704   Ceed              ceed;
705   CeedInt           P_1d, Q_1d;
706   CeedScalar       *interp_1d_pinv;
707   const CeedScalar *grad_1d, *interp_1d;
708 
709   // Note: This function is for backend use, so all errors are terminal and we do not need to clean up memory on failure.
710   CeedCall(CeedBasisGetCeed(basis, &ceed));
711   CeedCall(CeedBasisGetNumNodes1D(basis, &P_1d));
712   CeedCall(CeedBasisGetNumQuadraturePoints1D(basis, &Q_1d));
713 
714   // Compute interp_1d^+, pseudoinverse of interp_1d
715   CeedCall(CeedCalloc(P_1d * Q_1d, &interp_1d_pinv));
716   CeedCall(CeedBasisGetInterp1D(basis, &interp_1d));
717   CeedCall(CeedMatrixPseudoinverse(ceed, interp_1d, Q_1d, P_1d, interp_1d_pinv));
718   CeedCall(CeedBasisGetGrad1D(basis, &grad_1d));
719   CeedCall(CeedMatrixMatrixMultiply(ceed, grad_1d, (const CeedScalar *)interp_1d_pinv, collo_grad_1d, Q_1d, Q_1d, P_1d));
720 
721   CeedCall(CeedFree(&interp_1d_pinv));
722   CeedCall(CeedDestroy(&ceed));
723   return CEED_ERROR_SUCCESS;
724 }
725 
726 /**
727   @brief Return 1D interpolation matrix to Chebyshev polynomial coefficients on quadrature space
728 
729   @param[in]  basis               `CeedBasis`
730   @param[out] chebyshev_interp_1d Row-major (`P_1d * Q_1d`) matrix interpolating from basis nodes to Chebyshev polynomial coefficients
731 
732   @return An error code: 0 - success, otherwise - failure
733 
734   @ref Backend
735 **/
736 int CeedBasisGetChebyshevInterp1D(CeedBasis basis, CeedScalar *chebyshev_interp_1d) {
737   CeedInt           P_1d, Q_1d;
738   CeedScalar       *C, *chebyshev_coeffs_1d_inv;
739   const CeedScalar *interp_1d, *q_ref_1d;
740   Ceed              ceed;
741 
742   CeedCall(CeedBasisGetCeed(basis, &ceed));
743   CeedCall(CeedBasisGetNumNodes1D(basis, &P_1d));
744   CeedCall(CeedBasisGetNumQuadraturePoints1D(basis, &Q_1d));
745 
746   // Build coefficient matrix
747   // -- Note: Clang-tidy needs this check
748   CeedCheck((P_1d > 0) && (Q_1d > 0), ceed, CEED_ERROR_INCOMPATIBLE, "CeedBasis dimensions are malformed");
749   CeedCall(CeedCalloc(Q_1d * Q_1d, &C));
750   CeedCall(CeedBasisGetQRef(basis, &q_ref_1d));
751   for (CeedInt i = 0; i < Q_1d; i++) CeedCall(CeedChebyshevPolynomialsAtPoint(q_ref_1d[i], Q_1d, &C[i * Q_1d]));
752 
753   // Compute C^+, pseudoinverse of coefficient matrix
754   CeedCall(CeedCalloc(Q_1d * Q_1d, &chebyshev_coeffs_1d_inv));
755   CeedCall(CeedMatrixPseudoinverse(ceed, C, Q_1d, Q_1d, chebyshev_coeffs_1d_inv));
756 
757   // Build mapping from nodes to Chebyshev coefficients
758   CeedCall(CeedBasisGetInterp1D(basis, &interp_1d));
759   CeedCall(CeedMatrixMatrixMultiply(ceed, chebyshev_coeffs_1d_inv, interp_1d, chebyshev_interp_1d, Q_1d, P_1d, Q_1d));
760 
761   // Cleanup
762   CeedCall(CeedFree(&C));
763   CeedCall(CeedFree(&chebyshev_coeffs_1d_inv));
764   CeedCall(CeedDestroy(&ceed));
765   return CEED_ERROR_SUCCESS;
766 }
767 
768 /**
769   @brief Get tensor status for given `CeedBasis`
770 
771   @param[in]  basis     `CeedBasis`
772   @param[out] is_tensor Variable to store tensor status
773 
774   @return An error code: 0 - success, otherwise - failure
775 
776   @ref Backend
777 **/
778 int CeedBasisIsTensor(CeedBasis basis, bool *is_tensor) {
779   *is_tensor = basis->is_tensor_basis;
780   return CEED_ERROR_SUCCESS;
781 }
782 
783 /**
784   @brief Get backend data of a `CeedBasis`
785 
786   @param[in]  basis `CeedBasis`
787   @param[out] data  Variable to store data
788 
789   @return An error code: 0 - success, otherwise - failure
790 
791   @ref Backend
792 **/
793 int CeedBasisGetData(CeedBasis basis, void *data) {
794   *(void **)data = basis->data;
795   return CEED_ERROR_SUCCESS;
796 }
797 
798 /**
799   @brief Set backend data of a `CeedBasis`
800 
801   @param[in,out] basis  `CeedBasis`
802   @param[in]     data   Data to set
803 
804   @return An error code: 0 - success, otherwise - failure
805 
806   @ref Backend
807 **/
808 int CeedBasisSetData(CeedBasis basis, void *data) {
809   basis->data = data;
810   return CEED_ERROR_SUCCESS;
811 }
812 
813 /**
814   @brief Increment the reference counter for a `CeedBasis`
815 
816   @param[in,out] basis `CeedBasis` to increment the reference counter
817 
818   @return An error code: 0 - success, otherwise - failure
819 
820   @ref Backend
821 **/
822 int CeedBasisReference(CeedBasis basis) {
823   basis->ref_count++;
824   return CEED_ERROR_SUCCESS;
825 }
826 
827 /**
828   @brief Get number of Q-vector components for given `CeedBasis`
829 
830   @param[in]  basis     `CeedBasis`
831   @param[in]  eval_mode @ref CEED_EVAL_INTERP to use interpolated values,
832                           @ref CEED_EVAL_GRAD to use gradients,
833                           @ref CEED_EVAL_DIV to use divergence,
834                           @ref CEED_EVAL_CURL to use curl
835   @param[out] q_comp    Variable to store number of Q-vector components of basis
836 
837   @return An error code: 0 - success, otherwise - failure
838 
839   @ref Backend
840 **/
841 int CeedBasisGetNumQuadratureComponents(CeedBasis basis, CeedEvalMode eval_mode, CeedInt *q_comp) {
842   CeedInt dim;
843 
844   CeedCall(CeedBasisGetDimension(basis, &dim));
845   switch (eval_mode) {
846     case CEED_EVAL_INTERP: {
847       CeedFESpace fe_space;
848 
849       CeedCall(CeedBasisGetFESpace(basis, &fe_space));
850       *q_comp = (fe_space == CEED_FE_SPACE_H1) ? 1 : dim;
851     } break;
852     case CEED_EVAL_GRAD:
853       *q_comp = dim;
854       break;
855     case CEED_EVAL_DIV:
856       *q_comp = 1;
857       break;
858     case CEED_EVAL_CURL:
859       *q_comp = (dim < 3) ? 1 : dim;
860       break;
861     case CEED_EVAL_NONE:
862     case CEED_EVAL_WEIGHT:
863       *q_comp = 1;
864       break;
865   }
866   return CEED_ERROR_SUCCESS;
867 }
868 
869 /**
870   @brief Estimate number of FLOPs required to apply `CeedBasis` in `t_mode` and `eval_mode`
871 
872   @param[in]  basis        `CeedBasis` to estimate FLOPs for
873   @param[in]  t_mode       Apply basis or transpose
874   @param[in]  eval_mode    @ref CeedEvalMode
875   @param[in]  is_at_points Evaluate the basis at points or quadrature points
876   @param[in]  num_points   Number of points basis is evaluated at
877   @param[out] flops        Address of variable to hold FLOPs estimate
878 
879   @ref Backend
880 **/
881 int CeedBasisGetFlopsEstimate(CeedBasis basis, CeedTransposeMode t_mode, CeedEvalMode eval_mode, bool is_at_points, CeedInt num_points,
882                               CeedSize *flops) {
883   bool is_tensor;
884 
885   CeedCall(CeedBasisIsTensor(basis, &is_tensor));
886   CeedCheck(!is_at_points || is_tensor, CeedBasisReturnCeed(basis), CEED_ERROR_INCOMPATIBLE, "Can only evaluate tensor-product bases at points");
887   if (is_tensor) {
888     CeedInt dim, num_comp, P_1d, Q_1d;
889 
890     CeedCall(CeedBasisGetDimension(basis, &dim));
891     CeedCall(CeedBasisGetNumComponents(basis, &num_comp));
892     CeedCall(CeedBasisGetNumNodes1D(basis, &P_1d));
893     CeedCall(CeedBasisGetNumQuadraturePoints1D(basis, &Q_1d));
894     if (t_mode == CEED_TRANSPOSE) {
895       P_1d = Q_1d;
896       Q_1d = P_1d;
897     }
898     CeedInt tensor_flops = 0, pre = num_comp * CeedIntPow(P_1d, dim - 1), post = 1;
899 
900     for (CeedInt d = 0; d < dim; d++) {
901       tensor_flops += 2 * pre * P_1d * post * Q_1d;
902       pre /= P_1d;
903       post *= Q_1d;
904     }
905     if (is_at_points) {
906       bool is_gpu = false;
907 
908       {
909         CeedMemType mem_type;
910 
911         CeedCall(CeedGetPreferredMemType(CeedBasisReturnCeed(basis), &mem_type));
912         is_gpu = mem_type == CEED_MEM_DEVICE;
913       }
914 
915       CeedInt chebyshev_flops = (Q_1d - 2) * 3 + 1, d_chebyshev_flops = (Q_1d - 2) * 8 + 1;
916       CeedInt point_tensor_flops = 0, pre = CeedIntPow(Q_1d, dim - 1), post = 1;
917 
918       for (CeedInt d = 0; d < dim; d++) {
919         point_tensor_flops += 2 * pre * Q_1d * post * 1;
920         pre /= P_1d;
921         post *= Q_1d;
922       }
923 
924       switch (eval_mode) {
925         case CEED_EVAL_NONE:
926           *flops = 0;
927           break;
928         case CEED_EVAL_INTERP: {
929           *flops = tensor_flops + num_points * num_comp * (point_tensor_flops + (t_mode == CEED_TRANSPOSE ? CeedIntPow(Q_1d, dim) : 0));
930           if (dim == 3 && is_gpu) {
931             *flops += num_points * num_comp * Q_1d * (dim * chebyshev_flops + 2 * Q_1d * Q_1d + (t_mode == CEED_TRANSPOSE ? 2 * Q_1d + 1 : 3 * Q_1d));
932           } else {
933             *flops += num_points * (is_gpu ? num_comp : 1) * dim * chebyshev_flops;
934           }
935           break;
936         }
937         case CEED_EVAL_GRAD: {
938           *flops = tensor_flops + num_points * num_comp * (point_tensor_flops + (t_mode == CEED_TRANSPOSE ? CeedIntPow(Q_1d, dim) : 0));
939           if (dim == 3 && is_gpu) {
940             CeedInt inner_flops = (dim - 1) * chebyshev_flops + d_chebyshev_flops + 2 * Q_1d * Q_1d + (t_mode == CEED_TRANSPOSE ? 2 : 3) * Q_1d;
941             *flops += num_points * num_comp * Q_1d * (dim * inner_flops + (t_mode == CEED_TRANSPOSE ? 1 : 0));
942           } else {
943             *flops += num_points * (is_gpu ? num_comp : 1) * dim * (d_chebyshev_flops + (dim - 1) * chebyshev_flops);
944           }
945           break;
946         }
947         case CEED_EVAL_DIV:
948         case CEED_EVAL_CURL: {
949           // LCOV_EXCL_START
950           return CeedError(CeedBasisReturnCeed(basis), CEED_ERROR_INCOMPATIBLE, "Tensor basis evaluation for %s not supported at points",
951                            CeedEvalModes[eval_mode]);
952           break;
953           // LCOV_EXCL_STOP
954         }
955         case CEED_EVAL_WEIGHT:
956           *flops = num_points;
957           break;
958       }
959     } else {
960       switch (eval_mode) {
961         case CEED_EVAL_NONE:
962           *flops = 0;
963           break;
964         case CEED_EVAL_INTERP:
965           *flops = tensor_flops;
966           break;
967         case CEED_EVAL_GRAD:
968           *flops = tensor_flops * 2;
969           break;
970         case CEED_EVAL_DIV:
971         case CEED_EVAL_CURL: {
972           // LCOV_EXCL_START
973           return CeedError(CeedBasisReturnCeed(basis), CEED_ERROR_INCOMPATIBLE, "Tensor basis evaluation for %s not supported",
974                            CeedEvalModes[eval_mode]);
975           break;
976           // LCOV_EXCL_STOP
977         }
978         case CEED_EVAL_WEIGHT:
979           *flops = dim * CeedIntPow(Q_1d, dim);
980           break;
981       }
982     }
983   } else {
984     CeedInt dim, num_comp, q_comp, num_nodes, num_qpts;
985 
986     CeedCall(CeedBasisGetDimension(basis, &dim));
987     CeedCall(CeedBasisGetNumComponents(basis, &num_comp));
988     CeedCall(CeedBasisGetNumQuadratureComponents(basis, eval_mode, &q_comp));
989     CeedCall(CeedBasisGetNumNodes(basis, &num_nodes));
990     CeedCall(CeedBasisGetNumQuadraturePoints(basis, &num_qpts));
991     switch (eval_mode) {
992       case CEED_EVAL_NONE:
993         *flops = 0;
994         break;
995       case CEED_EVAL_INTERP:
996       case CEED_EVAL_GRAD:
997       case CEED_EVAL_DIV:
998       case CEED_EVAL_CURL:
999         *flops = num_nodes * num_qpts * num_comp * q_comp;
1000         break;
1001       case CEED_EVAL_WEIGHT:
1002         *flops = 0;
1003         break;
1004     }
1005   }
1006   return CEED_ERROR_SUCCESS;
1007 }
1008 
1009 /**
1010   @brief Get `CeedFESpace` for a `CeedBasis`
1011 
1012   @param[in]  basis    `CeedBasis`
1013   @param[out] fe_space Variable to store `CeedFESpace`
1014 
1015   @return An error code: 0 - success, otherwise - failure
1016 
1017   @ref Backend
1018 **/
1019 int CeedBasisGetFESpace(CeedBasis basis, CeedFESpace *fe_space) {
1020   *fe_space = basis->fe_space;
1021   return CEED_ERROR_SUCCESS;
1022 }
1023 
1024 /**
1025   @brief Get dimension for given `CeedElemTopology`
1026 
1027   @param[in]  topo `CeedElemTopology`
1028   @param[out] dim  Variable to store dimension of topology
1029 
1030   @return An error code: 0 - success, otherwise - failure
1031 
1032   @ref Backend
1033 **/
1034 int CeedBasisGetTopologyDimension(CeedElemTopology topo, CeedInt *dim) {
1035   *dim = (CeedInt)topo >> 16;
1036   return CEED_ERROR_SUCCESS;
1037 }
1038 
1039 /**
1040   @brief Get `CeedTensorContract` of a `CeedBasis`
1041 
1042   @param[in]  basis     `CeedBasis`
1043   @param[out] contract  Variable to store `CeedTensorContract`
1044 
1045   @return An error code: 0 - success, otherwise - failure
1046 
1047   @ref Backend
1048 **/
1049 int CeedBasisGetTensorContract(CeedBasis basis, CeedTensorContract *contract) {
1050   *contract = basis->contract;
1051   return CEED_ERROR_SUCCESS;
1052 }
1053 
1054 /**
1055   @brief Set `CeedTensorContract` of a `CeedBasis`
1056 
1057   @param[in,out] basis    `CeedBasis`
1058   @param[in]     contract `CeedTensorContract` to set
1059 
1060   @return An error code: 0 - success, otherwise - failure
1061 
1062   @ref Backend
1063 **/
1064 int CeedBasisSetTensorContract(CeedBasis basis, CeedTensorContract contract) {
1065   basis->contract = contract;
1066   CeedCall(CeedTensorContractReference(contract));
1067   return CEED_ERROR_SUCCESS;
1068 }
1069 
1070 /**
1071   @brief Return a reference implementation of matrix multiplication \f$C = A B\f$.
1072 
1073   Note: This is a reference implementation for CPU `CeedScalar` pointers that is not intended for high performance.
1074 
1075   @param[in]  ceed  `Ceed` context for error handling
1076   @param[in]  mat_A Row-major matrix `A`
1077   @param[in]  mat_B Row-major matrix `B`
1078   @param[out] mat_C Row-major output matrix `C`
1079   @param[in]  m     Number of rows of `C`
1080   @param[in]  n     Number of columns of `C`
1081   @param[in]  kk    Number of columns of `A`/rows of `B`
1082 
1083   @return An error code: 0 - success, otherwise - failure
1084 
1085   @ref Utility
1086 **/
1087 int CeedMatrixMatrixMultiply(Ceed ceed, const CeedScalar *mat_A, const CeedScalar *mat_B, CeedScalar *mat_C, CeedInt m, CeedInt n, CeedInt kk) {
1088   for (CeedInt i = 0; i < m; i++) {
1089     for (CeedInt j = 0; j < n; j++) {
1090       CeedScalar sum = 0;
1091 
1092       for (CeedInt k = 0; k < kk; k++) sum += mat_A[k + i * kk] * mat_B[j + k * n];
1093       mat_C[j + i * n] = sum;
1094     }
1095   }
1096   return CEED_ERROR_SUCCESS;
1097 }
1098 
1099 /**
1100   @brief Return QR Factorization of a matrix
1101 
1102   @param[in]     ceed `Ceed` context for error handling
1103   @param[in,out] mat  Row-major matrix to be factorized in place
1104   @param[in,out] tau  Vector of length `m` of scaling factors
1105   @param[in]     m    Number of rows
1106   @param[in]     n    Number of columns
1107 
1108   @return An error code: 0 - success, otherwise - failure
1109 
1110   @ref Utility
1111 **/
1112 int CeedQRFactorization(Ceed ceed, CeedScalar *mat, CeedScalar *tau, CeedInt m, CeedInt n) {
1113   CeedScalar v[m];
1114 
1115   // Check matrix shape
1116   CeedCheck(n <= m, ceed, CEED_ERROR_UNSUPPORTED, "Cannot compute QR factorization with n > m");
1117 
1118   for (CeedInt i = 0; i < n; i++) {
1119     CeedScalar sigma = 0.0;
1120 
1121     if (i >= m - 1) {  // last row of matrix, no reflection needed
1122       tau[i] = 0.;
1123       break;
1124     }
1125     // Calculate Householder vector, magnitude
1126     v[i] = mat[i + n * i];
1127     for (CeedInt j = i + 1; j < m; j++) {
1128       v[j] = mat[i + n * j];
1129       sigma += v[j] * v[j];
1130     }
1131     const CeedScalar norm = sqrt(v[i] * v[i] + sigma);  // norm of v[i:m]
1132     const CeedScalar R_ii = -copysign(norm, v[i]);
1133 
1134     v[i] -= R_ii;
1135     // norm of v[i:m] after modification above and scaling below
1136     //   norm = sqrt(v[i]*v[i] + sigma) / v[i];
1137     //   tau = 2 / (norm*norm)
1138     tau[i] = 2 * v[i] * v[i] / (v[i] * v[i] + sigma);
1139     for (CeedInt j = i + 1; j < m; j++) v[j] /= v[i];
1140 
1141     // Apply Householder reflector to lower right panel
1142     CeedHouseholderReflect(&mat[i * n + i + 1], &v[i], tau[i], m - i, n - i - 1, n, 1);
1143     // Save v
1144     mat[i + n * i] = R_ii;
1145     for (CeedInt j = i + 1; j < m; j++) mat[i + n * j] = v[j];
1146   }
1147   return CEED_ERROR_SUCCESS;
1148 }
1149 
1150 /**
1151   @brief Apply Householder Q matrix
1152 
1153   Compute `mat_A = mat_Q mat_A`, where `mat_Q` is \f$m \times m\f$ and `mat_A` is \f$m \times n\f$.
1154 
1155   @param[in,out] mat_A  Matrix to apply Householder Q to, in place
1156   @param[in]     mat_Q  Householder Q matrix
1157   @param[in]     tau    Householder scaling factors
1158   @param[in]     t_mode Transpose mode for application
1159   @param[in]     m      Number of rows in `A`
1160   @param[in]     n      Number of columns in `A`
1161   @param[in]     k      Number of elementary reflectors in Q, `k < m`
1162   @param[in]     row    Row stride in `A`
1163   @param[in]     col    Col stride in `A`
1164 
1165   @return An error code: 0 - success, otherwise - failure
1166 
1167   @ref Utility
1168 **/
1169 int CeedHouseholderApplyQ(CeedScalar *mat_A, const CeedScalar *mat_Q, const CeedScalar *tau, CeedTransposeMode t_mode, CeedInt m, CeedInt n,
1170                           CeedInt k, CeedInt row, CeedInt col) {
1171   CeedScalar *v;
1172 
1173   CeedCall(CeedMalloc(m, &v));
1174   for (CeedInt ii = 0; ii < k; ii++) {
1175     CeedInt i = t_mode == CEED_TRANSPOSE ? ii : k - 1 - ii;
1176     for (CeedInt j = i + 1; j < m; j++) v[j] = mat_Q[j * k + i];
1177     // Apply Householder reflector (I - tau v v^T) collo_grad_1d^T
1178     CeedCall(CeedHouseholderReflect(&mat_A[i * row], &v[i], tau[i], m - i, n, row, col));
1179   }
1180   CeedCall(CeedFree(&v));
1181   return CEED_ERROR_SUCCESS;
1182 }
1183 
1184 /**
1185   @brief Return pseudoinverse of a matrix
1186 
1187   @param[in]     ceed      Ceed context for error handling
1188   @param[in]     mat       Row-major matrix to compute pseudoinverse of
1189   @param[in]     m         Number of rows
1190   @param[in]     n         Number of columns
1191   @param[out]    mat_pinv  Row-major pseudoinverse matrix
1192 
1193   @return An error code: 0 - success, otherwise - failure
1194 
1195   @ref Utility
1196 **/
1197 int CeedMatrixPseudoinverse(Ceed ceed, const CeedScalar *mat, CeedInt m, CeedInt n, CeedScalar *mat_pinv) {
1198   CeedScalar *tau, *I, *mat_copy;
1199 
1200   CeedCall(CeedCalloc(m, &tau));
1201   CeedCall(CeedCalloc(m * m, &I));
1202   CeedCall(CeedCalloc(m * n, &mat_copy));
1203   memcpy(mat_copy, mat, m * n * sizeof mat[0]);
1204 
1205   // QR Factorization, mat = Q R
1206   CeedCall(CeedQRFactorization(ceed, mat_copy, tau, m, n));
1207 
1208   // -- Apply Q^T, I = Q^T * I
1209   for (CeedInt i = 0; i < m; i++) I[i * m + i] = 1.0;
1210   CeedCall(CeedHouseholderApplyQ(I, mat_copy, tau, CEED_TRANSPOSE, m, m, n, m, 1));
1211   // -- Apply R_inv, mat_pinv = R_inv * Q^T
1212   for (CeedInt j = 0; j < m; j++) {  // Column j
1213     mat_pinv[j + m * (n - 1)] = I[j + m * (n - 1)] / mat_copy[n * n - 1];
1214     for (CeedInt i = n - 2; i >= 0; i--) {  // Row i
1215       mat_pinv[j + m * i] = I[j + m * i];
1216       for (CeedInt k = i + 1; k < n; k++) mat_pinv[j + m * i] -= mat_copy[k + n * i] * mat_pinv[j + m * k];
1217       mat_pinv[j + m * i] /= mat_copy[i + n * i];
1218     }
1219   }
1220 
1221   // Cleanup
1222   CeedCall(CeedFree(&I));
1223   CeedCall(CeedFree(&tau));
1224   CeedCall(CeedFree(&mat_copy));
1225   return CEED_ERROR_SUCCESS;
1226 }
1227 
1228 /**
1229   @brief Return symmetric Schur decomposition of the symmetric matrix mat via symmetric QR factorization
1230 
1231   @param[in]     ceed   `Ceed` context for error handling
1232   @param[in,out] mat    Row-major matrix to be factorized in place
1233   @param[out]    lambda Vector of length n of eigenvalues
1234   @param[in]     n      Number of rows/columns
1235 
1236   @return An error code: 0 - success, otherwise - failure
1237 
1238   @ref Utility
1239 **/
1240 CeedPragmaOptimizeOff
1241 int CeedSymmetricSchurDecomposition(Ceed ceed, CeedScalar *mat, CeedScalar *lambda, CeedInt n) {
1242   // Check bounds for clang-tidy
1243   CeedCheck(n > 1, ceed, CEED_ERROR_UNSUPPORTED, "Cannot compute symmetric Schur decomposition of scalars");
1244 
1245   CeedScalar v[n - 1], tau[n - 1], mat_T[n * n];
1246 
1247   // Copy mat to mat_T and set mat to I
1248   memcpy(mat_T, mat, n * n * sizeof(mat[0]));
1249   for (CeedInt i = 0; i < n; i++) {
1250     for (CeedInt j = 0; j < n; j++) mat[j + n * i] = (i == j) ? 1 : 0;
1251   }
1252 
1253   // Reduce to tridiagonal
1254   for (CeedInt i = 0; i < n - 1; i++) {
1255     // Calculate Householder vector, magnitude
1256     CeedScalar sigma = 0.0;
1257 
1258     v[i] = mat_T[i + n * (i + 1)];
1259     for (CeedInt j = i + 1; j < n - 1; j++) {
1260       v[j] = mat_T[i + n * (j + 1)];
1261       sigma += v[j] * v[j];
1262     }
1263     const CeedScalar norm = sqrt(v[i] * v[i] + sigma);  // norm of v[i:n-1]
1264     const CeedScalar R_ii = -copysign(norm, v[i]);
1265 
1266     v[i] -= R_ii;
1267     // norm of v[i:m] after modification above and scaling below
1268     //   norm = sqrt(v[i]*v[i] + sigma) / v[i];
1269     //   tau = 2 / (norm*norm)
1270     tau[i] = i == n - 2 ? 2 : 2 * v[i] * v[i] / (v[i] * v[i] + sigma);
1271     for (CeedInt j = i + 1; j < n - 1; j++) v[j] /= v[i];
1272 
1273     // Update sub and super diagonal
1274     for (CeedInt j = i + 2; j < n; j++) {
1275       mat_T[i + n * j] = 0;
1276       mat_T[j + n * i] = 0;
1277     }
1278     // Apply symmetric Householder reflector to lower right panel
1279     CeedHouseholderReflect(&mat_T[(i + 1) + n * (i + 1)], &v[i], tau[i], n - (i + 1), n - (i + 1), n, 1);
1280     CeedHouseholderReflect(&mat_T[(i + 1) + n * (i + 1)], &v[i], tau[i], n - (i + 1), n - (i + 1), 1, n);
1281 
1282     // Save v
1283     mat_T[i + n * (i + 1)] = R_ii;
1284     mat_T[(i + 1) + n * i] = R_ii;
1285     for (CeedInt j = i + 1; j < n - 1; j++) {
1286       mat_T[i + n * (j + 1)] = v[j];
1287     }
1288   }
1289   // Backwards accumulation of Q
1290   for (CeedInt i = n - 2; i >= 0; i--) {
1291     if (tau[i] > 0.0) {
1292       v[i] = 1;
1293       for (CeedInt j = i + 1; j < n - 1; j++) {
1294         v[j]                   = mat_T[i + n * (j + 1)];
1295         mat_T[i + n * (j + 1)] = 0;
1296       }
1297       CeedHouseholderReflect(&mat[(i + 1) + n * (i + 1)], &v[i], tau[i], n - (i + 1), n - (i + 1), n, 1);
1298     }
1299   }
1300 
1301   // Reduce sub and super diagonal
1302   CeedInt    p = 0, q = 0, itr = 0, max_itr = n * n * n * n;
1303   CeedScalar tol = CEED_EPSILON;
1304 
1305   while (itr < max_itr) {
1306     // Update p, q, size of reduced portions of diagonal
1307     p = 0;
1308     q = 0;
1309     for (CeedInt i = n - 2; i >= 0; i--) {
1310       if (fabs(mat_T[i + n * (i + 1)]) < tol) q += 1;
1311       else break;
1312     }
1313     for (CeedInt i = 0; i < n - q - 1; i++) {
1314       if (fabs(mat_T[i + n * (i + 1)]) < tol) p += 1;
1315       else break;
1316     }
1317     if (q == n - 1) break;  // Finished reducing
1318 
1319     // Reduce tridiagonal portion
1320     CeedScalar t_nn = mat_T[(n - 1 - q) + n * (n - 1 - q)], t_nnm1 = mat_T[(n - 2 - q) + n * (n - 1 - q)];
1321     CeedScalar d  = (mat_T[(n - 2 - q) + n * (n - 2 - q)] - t_nn) / 2;
1322     CeedScalar mu = t_nn - t_nnm1 * t_nnm1 / (d + copysign(sqrt(d * d + t_nnm1 * t_nnm1), d));
1323     CeedScalar x  = mat_T[p + n * p] - mu;
1324     CeedScalar z  = mat_T[p + n * (p + 1)];
1325 
1326     for (CeedInt k = p; k < n - q - 1; k++) {
1327       // Compute Givens rotation
1328       CeedScalar c = 1, s = 0;
1329 
1330       if (fabs(z) > tol) {
1331         if (fabs(z) > fabs(x)) {
1332           const CeedScalar tau = -x / z;
1333 
1334           s = 1 / sqrt(1 + tau * tau);
1335           c = s * tau;
1336         } else {
1337           const CeedScalar tau = -z / x;
1338 
1339           c = 1 / sqrt(1 + tau * tau);
1340           s = c * tau;
1341         }
1342       }
1343 
1344       // Apply Givens rotation to T
1345       CeedGivensRotation(mat_T, c, s, CEED_NOTRANSPOSE, k, k + 1, n, n);
1346       CeedGivensRotation(mat_T, c, s, CEED_TRANSPOSE, k, k + 1, n, n);
1347 
1348       // Apply Givens rotation to Q
1349       CeedGivensRotation(mat, c, s, CEED_NOTRANSPOSE, k, k + 1, n, n);
1350 
1351       // Update x, z
1352       if (k < n - q - 2) {
1353         x = mat_T[k + n * (k + 1)];
1354         z = mat_T[k + n * (k + 2)];
1355       }
1356     }
1357     itr++;
1358   }
1359 
1360   // Save eigenvalues
1361   for (CeedInt i = 0; i < n; i++) lambda[i] = mat_T[i + n * i];
1362 
1363   // Check convergence
1364   CeedCheck(itr < max_itr || q > n, ceed, CEED_ERROR_MINOR, "Symmetric QR failed to converge");
1365   return CEED_ERROR_SUCCESS;
1366 }
1367 CeedPragmaOptimizeOn
1368 
1369 /**
1370   @brief Return Simultaneous Diagonalization of two matrices.
1371 
1372   This solves the generalized eigenvalue problem `A x = lambda B x`, where `A` and `B` are symmetric and `B` is positive definite.
1373   We generate the matrix `X` and vector `Lambda` such that `X^T A X = Lambda` and `X^T B X = I`.
1374   This is equivalent to the LAPACK routine 'sygv' with `TYPE = 1`.
1375 
1376   @param[in]  ceed   `Ceed` context for error handling
1377   @param[in]  mat_A  Row-major matrix to be factorized with eigenvalues
1378   @param[in]  mat_B  Row-major matrix to be factorized to identity
1379   @param[out] mat_X  Row-major orthogonal matrix
1380   @param[out] lambda Vector of length `n` of generalized eigenvalues
1381   @param[in]  n      Number of rows/columns
1382 
1383   @return An error code: 0 - success, otherwise - failure
1384 
1385   @ref Utility
1386 **/
1387 CeedPragmaOptimizeOff
1388 int CeedSimultaneousDiagonalization(Ceed ceed, CeedScalar *mat_A, CeedScalar *mat_B, CeedScalar *mat_X, CeedScalar *lambda, CeedInt n) {
1389   CeedScalar *mat_C, *mat_G, *vec_D;
1390 
1391   CeedCall(CeedCalloc(n * n, &mat_C));
1392   CeedCall(CeedCalloc(n * n, &mat_G));
1393   CeedCall(CeedCalloc(n, &vec_D));
1394 
1395   // Compute B = G D G^T
1396   memcpy(mat_G, mat_B, n * n * sizeof(mat_B[0]));
1397   CeedCall(CeedSymmetricSchurDecomposition(ceed, mat_G, vec_D, n));
1398 
1399   // Sort eigenvalues
1400   for (CeedInt i = n - 1; i >= 0; i--) {
1401     for (CeedInt j = 0; j < i; j++) {
1402       if (fabs(vec_D[j]) > fabs(vec_D[j + 1])) {
1403         CeedScalarSwap(vec_D[j], vec_D[j + 1]);
1404         for (CeedInt k = 0; k < n; k++) CeedScalarSwap(mat_G[k * n + j], mat_G[k * n + j + 1]);
1405       }
1406     }
1407   }
1408 
1409   // Compute C = (G D^1/2)^-1 A (G D^1/2)^-T
1410   //           = D^-1/2 G^T A G D^-1/2
1411   // -- D = D^-1/2
1412   for (CeedInt i = 0; i < n; i++) vec_D[i] = 1. / sqrt(vec_D[i]);
1413   // -- G = G D^-1/2
1414   // -- C = D^-1/2 G^T
1415   for (CeedInt i = 0; i < n; i++) {
1416     for (CeedInt j = 0; j < n; j++) {
1417       mat_G[i * n + j] *= vec_D[j];
1418       mat_C[j * n + i] = mat_G[i * n + j];
1419     }
1420   }
1421   // -- X = (D^-1/2 G^T) A
1422   CeedCall(CeedMatrixMatrixMultiply(ceed, (const CeedScalar *)mat_C, (const CeedScalar *)mat_A, mat_X, n, n, n));
1423   // -- C = (D^-1/2 G^T A) (G D^-1/2)
1424   CeedCall(CeedMatrixMatrixMultiply(ceed, (const CeedScalar *)mat_X, (const CeedScalar *)mat_G, mat_C, n, n, n));
1425 
1426   // Compute Q^T C Q = lambda
1427   CeedCall(CeedSymmetricSchurDecomposition(ceed, mat_C, lambda, n));
1428 
1429   // Sort eigenvalues
1430   for (CeedInt i = n - 1; i >= 0; i--) {
1431     for (CeedInt j = 0; j < i; j++) {
1432       if (fabs(lambda[j]) > fabs(lambda[j + 1])) {
1433         CeedScalarSwap(lambda[j], lambda[j + 1]);
1434         for (CeedInt k = 0; k < n; k++) CeedScalarSwap(mat_C[k * n + j], mat_C[k * n + j + 1]);
1435       }
1436     }
1437   }
1438 
1439   // Set X = (G D^1/2)^-T Q
1440   //       = G D^-1/2 Q
1441   CeedCall(CeedMatrixMatrixMultiply(ceed, (const CeedScalar *)mat_G, (const CeedScalar *)mat_C, mat_X, n, n, n));
1442 
1443   // Cleanup
1444   CeedCall(CeedFree(&mat_C));
1445   CeedCall(CeedFree(&mat_G));
1446   CeedCall(CeedFree(&vec_D));
1447   return CEED_ERROR_SUCCESS;
1448 }
1449 CeedPragmaOptimizeOn
1450 
1451 /// @}
1452 
1453 /// ----------------------------------------------------------------------------
1454 /// CeedBasis Public API
1455 /// ----------------------------------------------------------------------------
1456 /// @addtogroup CeedBasisUser
1457 /// @{
1458 
1459 /**
1460   @brief Create a tensor-product basis for \f$H^1\f$ discretizations
1461 
1462   @param[in]  ceed        `Ceed` object used to create the `CeedBasis`
1463   @param[in]  dim         Topological dimension
1464   @param[in]  num_comp    Number of field components (1 for scalar fields)
1465   @param[in]  P_1d        Number of nodes in one dimension
1466   @param[in]  Q_1d        Number of quadrature points in one dimension
1467   @param[in]  interp_1d   Row-major (`Q_1d * P_1d`) matrix expressing the values of nodal basis functions at quadrature points
1468   @param[in]  grad_1d     Row-major (`Q_1d * P_1d`) matrix expressing derivatives of nodal basis functions at quadrature points
1469   @param[in]  q_ref_1d    Array of length `Q_1d` holding the locations of quadrature points on the 1D reference element `[-1, 1]`
1470   @param[in]  q_weight_1d Array of length `Q_1d` holding the quadrature weights on the reference element
1471   @param[out] basis       Address of the variable where the newly created `CeedBasis` will be stored
1472 
1473   @return An error code: 0 - success, otherwise - failure
1474 
1475   @ref User
1476 **/
1477 int CeedBasisCreateTensorH1(Ceed ceed, CeedInt dim, CeedInt num_comp, CeedInt P_1d, CeedInt Q_1d, const CeedScalar *interp_1d,
1478                             const CeedScalar *grad_1d, const CeedScalar *q_ref_1d, const CeedScalar *q_weight_1d, CeedBasis *basis) {
1479   if (!ceed->BasisCreateTensorH1) {
1480     Ceed delegate;
1481 
1482     CeedCall(CeedGetObjectDelegate(ceed, &delegate, "Basis"));
1483     CeedCheck(delegate, ceed, CEED_ERROR_UNSUPPORTED, "Backend does not implement BasisCreateTensorH1");
1484     CeedCall(CeedBasisCreateTensorH1(delegate, dim, num_comp, P_1d, Q_1d, interp_1d, grad_1d, q_ref_1d, q_weight_1d, basis));
1485     CeedCall(CeedDestroy(&delegate));
1486     return CEED_ERROR_SUCCESS;
1487   }
1488 
1489   CeedCheck(dim > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis dimension must be a positive value");
1490   CeedCheck(num_comp > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 component");
1491   CeedCheck(P_1d > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 node");
1492   CeedCheck(Q_1d > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 quadrature point");
1493 
1494   CeedElemTopology topo = dim == 1 ? CEED_TOPOLOGY_LINE : dim == 2 ? CEED_TOPOLOGY_QUAD : CEED_TOPOLOGY_HEX;
1495 
1496   CeedCall(CeedCalloc(1, basis));
1497   CeedCall(CeedReferenceCopy(ceed, &(*basis)->ceed));
1498   (*basis)->ref_count       = 1;
1499   (*basis)->is_tensor_basis = true;
1500   (*basis)->dim             = dim;
1501   (*basis)->topo            = topo;
1502   (*basis)->num_comp        = num_comp;
1503   (*basis)->P_1d            = P_1d;
1504   (*basis)->Q_1d            = Q_1d;
1505   (*basis)->P               = CeedIntPow(P_1d, dim);
1506   (*basis)->Q               = CeedIntPow(Q_1d, dim);
1507   (*basis)->fe_space        = CEED_FE_SPACE_H1;
1508   CeedCall(CeedCalloc(Q_1d, &(*basis)->q_ref_1d));
1509   CeedCall(CeedCalloc(Q_1d, &(*basis)->q_weight_1d));
1510   if (q_ref_1d) memcpy((*basis)->q_ref_1d, q_ref_1d, Q_1d * sizeof(q_ref_1d[0]));
1511   if (q_weight_1d) memcpy((*basis)->q_weight_1d, q_weight_1d, Q_1d * sizeof(q_weight_1d[0]));
1512   CeedCall(CeedCalloc(Q_1d * P_1d, &(*basis)->interp_1d));
1513   CeedCall(CeedCalloc(Q_1d * P_1d, &(*basis)->grad_1d));
1514   if (interp_1d) memcpy((*basis)->interp_1d, interp_1d, Q_1d * P_1d * sizeof(interp_1d[0]));
1515   if (grad_1d) memcpy((*basis)->grad_1d, grad_1d, Q_1d * P_1d * sizeof(grad_1d[0]));
1516   CeedCall(ceed->BasisCreateTensorH1(dim, P_1d, Q_1d, interp_1d, grad_1d, q_ref_1d, q_weight_1d, *basis));
1517   return CEED_ERROR_SUCCESS;
1518 }
1519 
1520 /**
1521   @brief Create a tensor-product \f$H^1\f$ Lagrange basis
1522 
1523   @param[in]  ceed      `Ceed` object used to create the `CeedBasis`
1524   @param[in]  dim       Topological dimension of element
1525   @param[in]  num_comp  Number of field components (1 for scalar fields)
1526   @param[in]  P         Number of Gauss-Lobatto nodes in one dimension.
1527                           The polynomial degree of the resulting `Q_k` element is `k = P - 1`.
1528   @param[in]  Q         Number of quadrature points in one dimension.
1529   @param[in]  quad_mode Distribution of the `Q` quadrature points (affects order of accuracy for the quadrature)
1530   @param[out] basis     Address of the variable where the newly created `CeedBasis` will be stored
1531 
1532   @return An error code: 0 - success, otherwise - failure
1533 
1534   @ref User
1535 **/
1536 int CeedBasisCreateTensorH1Lagrange(Ceed ceed, CeedInt dim, CeedInt num_comp, CeedInt P, CeedInt Q, CeedQuadMode quad_mode, CeedBasis *basis) {
1537   // Allocate
1538   int        ierr = CEED_ERROR_SUCCESS;
1539   CeedScalar c1, c2, c3, c4, dx, *nodes, *interp_1d, *grad_1d, *q_ref_1d, *q_weight_1d;
1540 
1541   CeedCheck(dim > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis dimension must be a positive value");
1542   CeedCheck(num_comp > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 component");
1543   CeedCheck(P > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 node");
1544   CeedCheck(Q > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 quadrature point");
1545 
1546   // Get Nodes and Weights
1547   CeedCall(CeedCalloc(P * Q, &interp_1d));
1548   CeedCall(CeedCalloc(P * Q, &grad_1d));
1549   CeedCall(CeedCalloc(P, &nodes));
1550   CeedCall(CeedCalloc(Q, &q_ref_1d));
1551   CeedCall(CeedCalloc(Q, &q_weight_1d));
1552   if (CeedLobattoQuadrature(P, nodes, NULL) != CEED_ERROR_SUCCESS) goto cleanup;
1553   switch (quad_mode) {
1554     case CEED_GAUSS:
1555       ierr = CeedGaussQuadrature(Q, q_ref_1d, q_weight_1d);
1556       break;
1557     case CEED_GAUSS_LOBATTO:
1558       ierr = CeedLobattoQuadrature(Q, q_ref_1d, q_weight_1d);
1559       break;
1560   }
1561   if (ierr != CEED_ERROR_SUCCESS) goto cleanup;
1562 
1563   // Build B, D matrix
1564   // Fornberg, 1998
1565   for (CeedInt i = 0; i < Q; i++) {
1566     c1                   = 1.0;
1567     c3                   = nodes[0] - q_ref_1d[i];
1568     interp_1d[i * P + 0] = 1.0;
1569     for (CeedInt j = 1; j < P; j++) {
1570       c2 = 1.0;
1571       c4 = c3;
1572       c3 = nodes[j] - q_ref_1d[i];
1573       for (CeedInt k = 0; k < j; k++) {
1574         dx = nodes[j] - nodes[k];
1575         c2 *= dx;
1576         if (k == j - 1) {
1577           grad_1d[i * P + j]   = c1 * (interp_1d[i * P + k] - c4 * grad_1d[i * P + k]) / c2;
1578           interp_1d[i * P + j] = -c1 * c4 * interp_1d[i * P + k] / c2;
1579         }
1580         grad_1d[i * P + k]   = (c3 * grad_1d[i * P + k] - interp_1d[i * P + k]) / dx;
1581         interp_1d[i * P + k] = c3 * interp_1d[i * P + k] / dx;
1582       }
1583       c1 = c2;
1584     }
1585   }
1586   // Pass to CeedBasisCreateTensorH1
1587   CeedCall(CeedBasisCreateTensorH1(ceed, dim, num_comp, P, Q, interp_1d, grad_1d, q_ref_1d, q_weight_1d, basis));
1588 cleanup:
1589   CeedCall(CeedFree(&interp_1d));
1590   CeedCall(CeedFree(&grad_1d));
1591   CeedCall(CeedFree(&nodes));
1592   CeedCall(CeedFree(&q_ref_1d));
1593   CeedCall(CeedFree(&q_weight_1d));
1594   return CEED_ERROR_SUCCESS;
1595 }
1596 
1597 /**
1598   @brief Create a non tensor-product basis for \f$H^1\f$ discretizations
1599 
1600   @param[in]  ceed      `Ceed` object used to create the `CeedBasis`
1601   @param[in]  topo      Topology of element, e.g. hypercube, simplex, etc
1602   @param[in]  num_comp  Number of field components (1 for scalar fields)
1603   @param[in]  num_nodes Total number of nodes
1604   @param[in]  num_qpts  Total number of quadrature points
1605   @param[in]  interp    Row-major (`num_qpts * num_nodes`) matrix expressing the values of nodal basis functions at quadrature points
1606   @param[in]  grad      Row-major (`dim * num_qpts * num_nodes`) matrix expressing derivatives of nodal basis functions at quadrature points
1607   @param[in]  q_ref     Array of length `num_qpts * dim` holding the locations of quadrature points on the reference element
1608   @param[in]  q_weight  Array of length `num_qpts` holding the quadrature weights on the reference element
1609   @param[out] basis     Address of the variable where the newly created `CeedBasis` will be stored
1610 
1611   @return An error code: 0 - success, otherwise - failure
1612 
1613   @ref User
1614 **/
1615 int CeedBasisCreateH1(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt num_qpts, const CeedScalar *interp,
1616                       const CeedScalar *grad, const CeedScalar *q_ref, const CeedScalar *q_weight, CeedBasis *basis) {
1617   CeedInt P = num_nodes, Q = num_qpts, dim = 0;
1618 
1619   if (!ceed->BasisCreateH1) {
1620     Ceed delegate;
1621 
1622     CeedCall(CeedGetObjectDelegate(ceed, &delegate, "Basis"));
1623     CeedCheck(delegate, ceed, CEED_ERROR_UNSUPPORTED, "Backend does not implement BasisCreateH1");
1624     CeedCall(CeedBasisCreateH1(delegate, topo, num_comp, num_nodes, num_qpts, interp, grad, q_ref, q_weight, basis));
1625     CeedCall(CeedDestroy(&delegate));
1626     return CEED_ERROR_SUCCESS;
1627   }
1628 
1629   CeedCheck(num_comp > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 component");
1630   CeedCheck(num_nodes > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 node");
1631   CeedCheck(num_qpts > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 quadrature point");
1632 
1633   CeedCall(CeedBasisGetTopologyDimension(topo, &dim));
1634 
1635   CeedCall(CeedCalloc(1, basis));
1636   CeedCall(CeedReferenceCopy(ceed, &(*basis)->ceed));
1637   (*basis)->ref_count       = 1;
1638   (*basis)->is_tensor_basis = false;
1639   (*basis)->dim             = dim;
1640   (*basis)->topo            = topo;
1641   (*basis)->num_comp        = num_comp;
1642   (*basis)->P               = P;
1643   (*basis)->Q               = Q;
1644   (*basis)->fe_space        = CEED_FE_SPACE_H1;
1645   CeedCall(CeedCalloc(Q * dim, &(*basis)->q_ref_1d));
1646   CeedCall(CeedCalloc(Q, &(*basis)->q_weight_1d));
1647   if (q_ref) memcpy((*basis)->q_ref_1d, q_ref, Q * dim * sizeof(q_ref[0]));
1648   if (q_weight) memcpy((*basis)->q_weight_1d, q_weight, Q * sizeof(q_weight[0]));
1649   CeedCall(CeedCalloc(Q * P, &(*basis)->interp));
1650   CeedCall(CeedCalloc(dim * Q * P, &(*basis)->grad));
1651   if (interp) memcpy((*basis)->interp, interp, Q * P * sizeof(interp[0]));
1652   if (grad) memcpy((*basis)->grad, grad, dim * Q * P * sizeof(grad[0]));
1653   CeedCall(ceed->BasisCreateH1(topo, dim, P, Q, interp, grad, q_ref, q_weight, *basis));
1654   return CEED_ERROR_SUCCESS;
1655 }
1656 
1657 /**
1658   @brief Create a non tensor-product basis for \f$H(\mathrm{div})\f$ discretizations
1659 
1660   @param[in]  ceed      `Ceed` object used to create the `CeedBasis`
1661   @param[in]  topo      Topology of element (`CEED_TOPOLOGY_QUAD`, `CEED_TOPOLOGY_PRISM`, etc.), dimension of which is used in some array sizes below
1662   @param[in]  num_comp  Number of components (usually 1 for vectors in H(div) bases)
1663   @param[in]  num_nodes Total number of nodes (DoFs per element)
1664   @param[in]  num_qpts  Total number of quadrature points
1665   @param[in]  interp    Row-major (`dim * num_qpts * num_nodes`) matrix expressing the values of basis functions at quadrature points
1666   @param[in]  div       Row-major (`num_qpts * num_nodes`) matrix expressing divergence of basis functions at quadrature points
1667   @param[in]  q_ref     Array of length `num_qpts` * dim holding the locations of quadrature points on the reference element
1668   @param[in]  q_weight  Array of length `num_qpts` holding the quadrature weights on the reference element
1669   @param[out] basis     Address of the variable where the newly created `CeedBasis` will be stored
1670 
1671   @return An error code: 0 - success, otherwise - failure
1672 
1673   @ref User
1674 **/
1675 int CeedBasisCreateHdiv(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt num_qpts, const CeedScalar *interp,
1676                         const CeedScalar *div, const CeedScalar *q_ref, const CeedScalar *q_weight, CeedBasis *basis) {
1677   CeedInt Q = num_qpts, P = num_nodes, dim = 0;
1678 
1679   if (!ceed->BasisCreateHdiv) {
1680     Ceed delegate;
1681 
1682     CeedCall(CeedGetObjectDelegate(ceed, &delegate, "Basis"));
1683     CeedCheck(delegate, ceed, CEED_ERROR_UNSUPPORTED, "Backend does not implement BasisCreateHdiv");
1684     CeedCall(CeedBasisCreateHdiv(delegate, topo, num_comp, num_nodes, num_qpts, interp, div, q_ref, q_weight, basis));
1685     CeedCall(CeedDestroy(&delegate));
1686     return CEED_ERROR_SUCCESS;
1687   }
1688 
1689   CeedCheck(num_comp > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 component");
1690   CeedCheck(num_nodes > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 node");
1691   CeedCheck(num_qpts > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 quadrature point");
1692 
1693   CeedCall(CeedBasisGetTopologyDimension(topo, &dim));
1694 
1695   CeedCall(CeedCalloc(1, basis));
1696   CeedCall(CeedReferenceCopy(ceed, &(*basis)->ceed));
1697   (*basis)->ref_count       = 1;
1698   (*basis)->is_tensor_basis = false;
1699   (*basis)->dim             = dim;
1700   (*basis)->topo            = topo;
1701   (*basis)->num_comp        = num_comp;
1702   (*basis)->P               = P;
1703   (*basis)->Q               = Q;
1704   (*basis)->fe_space        = CEED_FE_SPACE_HDIV;
1705   CeedCall(CeedMalloc(Q * dim, &(*basis)->q_ref_1d));
1706   CeedCall(CeedMalloc(Q, &(*basis)->q_weight_1d));
1707   if (q_ref) memcpy((*basis)->q_ref_1d, q_ref, Q * dim * sizeof(q_ref[0]));
1708   if (q_weight) memcpy((*basis)->q_weight_1d, q_weight, Q * sizeof(q_weight[0]));
1709   CeedCall(CeedMalloc(dim * Q * P, &(*basis)->interp));
1710   CeedCall(CeedMalloc(Q * P, &(*basis)->div));
1711   if (interp) memcpy((*basis)->interp, interp, dim * Q * P * sizeof(interp[0]));
1712   if (div) memcpy((*basis)->div, div, Q * P * sizeof(div[0]));
1713   CeedCall(ceed->BasisCreateHdiv(topo, dim, P, Q, interp, div, q_ref, q_weight, *basis));
1714   return CEED_ERROR_SUCCESS;
1715 }
1716 
1717 /**
1718   @brief Create a non tensor-product basis for \f$H(\mathrm{curl})\f$ discretizations
1719 
1720   @param[in]  ceed      `Ceed` object used to create the `CeedBasis`
1721   @param[in]  topo      Topology of element (`CEED_TOPOLOGY_QUAD`, `CEED_TOPOLOGY_PRISM`, etc.), dimension of which is used in some array sizes below
1722   @param[in]  num_comp  Number of components (usually 1 for vectors in \f$H(\mathrm{curl})\f$ bases)
1723   @param[in]  num_nodes Total number of nodes (DoFs per element)
1724   @param[in]  num_qpts  Total number of quadrature points
1725   @param[in]  interp    Row-major (`dim * num_qpts * num_nodes`) matrix expressing the values of basis functions at quadrature points
1726   @param[in]  curl      Row-major (`curl_comp * num_qpts * num_nodes`, `curl_comp = 1` if `dim < 3` otherwise `curl_comp = dim`) matrix expressing curl of basis functions at quadrature points
1727   @param[in]  q_ref     Array of length `num_qpts * dim` holding the locations of quadrature points on the reference element
1728   @param[in]  q_weight  Array of length `num_qpts` holding the quadrature weights on the reference element
1729   @param[out] basis     Address of the variable where the newly created `CeedBasis` will be stored
1730 
1731   @return An error code: 0 - success, otherwise - failure
1732 
1733   @ref User
1734 **/
1735 int CeedBasisCreateHcurl(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt num_qpts, const CeedScalar *interp,
1736                          const CeedScalar *curl, const CeedScalar *q_ref, const CeedScalar *q_weight, CeedBasis *basis) {
1737   CeedInt Q = num_qpts, P = num_nodes, dim = 0, curl_comp = 0;
1738 
1739   if (!ceed->BasisCreateHcurl) {
1740     Ceed delegate;
1741 
1742     CeedCall(CeedGetObjectDelegate(ceed, &delegate, "Basis"));
1743     CeedCheck(delegate, ceed, CEED_ERROR_UNSUPPORTED, "Backend does not implement BasisCreateHcurl");
1744     CeedCall(CeedBasisCreateHcurl(delegate, topo, num_comp, num_nodes, num_qpts, interp, curl, q_ref, q_weight, basis));
1745     CeedCall(CeedDestroy(&delegate));
1746     return CEED_ERROR_SUCCESS;
1747   }
1748 
1749   CeedCheck(num_comp > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 component");
1750   CeedCheck(num_nodes > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 node");
1751   CeedCheck(num_qpts > 0, ceed, CEED_ERROR_DIMENSION, "CeedBasis must have at least 1 quadrature point");
1752 
1753   CeedCall(CeedBasisGetTopologyDimension(topo, &dim));
1754   curl_comp = (dim < 3) ? 1 : dim;
1755 
1756   CeedCall(CeedCalloc(1, basis));
1757   CeedCall(CeedReferenceCopy(ceed, &(*basis)->ceed));
1758   (*basis)->ref_count       = 1;
1759   (*basis)->is_tensor_basis = false;
1760   (*basis)->dim             = dim;
1761   (*basis)->topo            = topo;
1762   (*basis)->num_comp        = num_comp;
1763   (*basis)->P               = P;
1764   (*basis)->Q               = Q;
1765   (*basis)->fe_space        = CEED_FE_SPACE_HCURL;
1766   CeedCall(CeedMalloc(Q * dim, &(*basis)->q_ref_1d));
1767   CeedCall(CeedMalloc(Q, &(*basis)->q_weight_1d));
1768   if (q_ref) memcpy((*basis)->q_ref_1d, q_ref, Q * dim * sizeof(q_ref[0]));
1769   if (q_weight) memcpy((*basis)->q_weight_1d, q_weight, Q * sizeof(q_weight[0]));
1770   CeedCall(CeedMalloc(dim * Q * P, &(*basis)->interp));
1771   CeedCall(CeedMalloc(curl_comp * Q * P, &(*basis)->curl));
1772   if (interp) memcpy((*basis)->interp, interp, dim * Q * P * sizeof(interp[0]));
1773   if (curl) memcpy((*basis)->curl, curl, curl_comp * Q * P * sizeof(curl[0]));
1774   CeedCall(ceed->BasisCreateHcurl(topo, dim, P, Q, interp, curl, q_ref, q_weight, *basis));
1775   return CEED_ERROR_SUCCESS;
1776 }
1777 
1778 /**
1779   @brief Create a `CeedBasis` for projection from the nodes of `basis_from` to the nodes of `basis_to`.
1780 
1781   Only @ref CEED_EVAL_INTERP will be valid for the new basis, `basis_project`.
1782   For \f$H^1\f$ spaces, @ref CEED_EVAL_GRAD will also be valid.
1783   The interpolation is given by `interp_project = interp_to^+ * interp_from`, where the pseudoinverse `interp_to^+` is given by QR factorization.
1784   The gradient (for the \f$H^1\f$ case) is given by `grad_project = interp_to^+ * grad_from`.
1785 
1786   Note: `basis_from` and `basis_to` must have compatible quadrature spaces.
1787 
1788   Note: `basis_project` will have the same number of components as `basis_from`, regardless of the number of components that `basis_to` has.
1789         If `basis_from` has 3 components and `basis_to` has 5 components, then `basis_project` will have 3 components.
1790 
1791   Note: If either `basis_from` or `basis_to` are non-tensor, then `basis_project` will also be non-tensor
1792 
1793   @param[in]  basis_from    `CeedBasis` to prolong from
1794   @param[in]  basis_to      `CeedBasis` to prolong to
1795   @param[out] basis_project Address of the variable where the newly created `CeedBasis` will be stored
1796 
1797   @return An error code: 0 - success, otherwise - failure
1798 
1799   @ref User
1800 **/
1801 int CeedBasisCreateProjection(CeedBasis basis_from, CeedBasis basis_to, CeedBasis *basis_project) {
1802   Ceed        ceed;
1803   bool        create_tensor;
1804   CeedInt     dim, num_comp;
1805   CeedScalar *interp_project, *grad_project;
1806 
1807   CeedCall(CeedBasisGetCeed(basis_to, &ceed));
1808 
1809   // Create projection matrix
1810   CeedCall(CeedBasisCreateProjectionMatrices(basis_from, basis_to, &interp_project, &grad_project));
1811 
1812   // Build basis
1813   {
1814     bool is_tensor_to, is_tensor_from;
1815 
1816     CeedCall(CeedBasisIsTensor(basis_to, &is_tensor_to));
1817     CeedCall(CeedBasisIsTensor(basis_from, &is_tensor_from));
1818     create_tensor = is_tensor_from && is_tensor_to;
1819   }
1820   CeedCall(CeedBasisGetDimension(basis_to, &dim));
1821   CeedCall(CeedBasisGetNumComponents(basis_from, &num_comp));
1822   if (create_tensor) {
1823     CeedInt P_1d_to, P_1d_from;
1824 
1825     CeedCall(CeedBasisGetNumNodes1D(basis_from, &P_1d_from));
1826     CeedCall(CeedBasisGetNumNodes1D(basis_to, &P_1d_to));
1827     CeedCall(CeedBasisCreateTensorH1(ceed, dim, num_comp, P_1d_from, P_1d_to, interp_project, grad_project, NULL, NULL, basis_project));
1828   } else {
1829     // Even if basis_to and basis_from are not H1, the resulting basis is H1 for interpolation to work
1830     CeedInt          num_nodes_to, num_nodes_from;
1831     CeedElemTopology topo;
1832 
1833     CeedCall(CeedBasisGetTopology(basis_from, &topo));
1834     CeedCall(CeedBasisGetNumNodes(basis_from, &num_nodes_from));
1835     CeedCall(CeedBasisGetNumNodes(basis_to, &num_nodes_to));
1836     CeedCall(CeedBasisCreateH1(ceed, topo, num_comp, num_nodes_from, num_nodes_to, interp_project, grad_project, NULL, NULL, basis_project));
1837   }
1838 
1839   // Cleanup
1840   CeedCall(CeedFree(&interp_project));
1841   CeedCall(CeedFree(&grad_project));
1842   CeedCall(CeedDestroy(&ceed));
1843   return CEED_ERROR_SUCCESS;
1844 }
1845 
1846 /**
1847   @brief Copy the pointer to a `CeedBasis`.
1848 
1849   Note: If the value of `*basis_copy` passed into this function is non-`NULL`, then it is assumed that `*basis_copy` is a pointer to a `CeedBasis`.
1850         This `CeedBasis` will be destroyed if `*basis_copy` is the only reference to this `CeedBasis`.
1851 
1852   @param[in]     basis      `CeedBasis` to copy reference to
1853   @param[in,out] basis_copy Variable to store copied reference
1854 
1855   @return An error code: 0 - success, otherwise - failure
1856 
1857   @ref User
1858 **/
1859 int CeedBasisReferenceCopy(CeedBasis basis, CeedBasis *basis_copy) {
1860   if (basis != CEED_BASIS_NONE) CeedCall(CeedBasisReference(basis));
1861   CeedCall(CeedBasisDestroy(basis_copy));
1862   *basis_copy = basis;
1863   return CEED_ERROR_SUCCESS;
1864 }
1865 
1866 /**
1867   @brief View a `CeedBasis`
1868 
1869   @param[in] basis  `CeedBasis` to view
1870   @param[in] stream Stream to view to, e.g., `stdout`
1871 
1872   @return An error code: 0 - success, otherwise - failure
1873 
1874   @ref User
1875 **/
1876 int CeedBasisView(CeedBasis basis, FILE *stream) {
1877   bool             is_tensor_basis;
1878   CeedElemTopology topo;
1879   CeedFESpace      fe_space;
1880 
1881   // Basis data
1882   CeedCall(CeedBasisIsTensor(basis, &is_tensor_basis));
1883   CeedCall(CeedBasisGetTopology(basis, &topo));
1884   CeedCall(CeedBasisGetFESpace(basis, &fe_space));
1885 
1886   // Print FE space and element topology of the basis
1887   fprintf(stream, "CeedBasis in a %s on a %s element\n", CeedFESpaces[fe_space], CeedElemTopologies[topo]);
1888   if (is_tensor_basis) {
1889     fprintf(stream, "  P: %" CeedInt_FMT "\n  Q: %" CeedInt_FMT "\n", basis->P_1d, basis->Q_1d);
1890   } else {
1891     fprintf(stream, "  P: %" CeedInt_FMT "\n  Q: %" CeedInt_FMT "\n", basis->P, basis->Q);
1892   }
1893   fprintf(stream, "  dimension: %" CeedInt_FMT "\n  field components: %" CeedInt_FMT "\n", basis->dim, basis->num_comp);
1894   // Print quadrature data, interpolation/gradient/divergence/curl of the basis
1895   if (is_tensor_basis) {  // tensor basis
1896     CeedInt           P_1d, Q_1d;
1897     const CeedScalar *q_ref_1d, *q_weight_1d, *interp_1d, *grad_1d;
1898 
1899     CeedCall(CeedBasisGetNumNodes1D(basis, &P_1d));
1900     CeedCall(CeedBasisGetNumQuadraturePoints1D(basis, &Q_1d));
1901     CeedCall(CeedBasisGetQRef(basis, &q_ref_1d));
1902     CeedCall(CeedBasisGetQWeights(basis, &q_weight_1d));
1903     CeedCall(CeedBasisGetInterp1D(basis, &interp_1d));
1904     CeedCall(CeedBasisGetGrad1D(basis, &grad_1d));
1905 
1906     CeedCall(CeedScalarView("qref1d", "\t% 12.8f", 1, Q_1d, q_ref_1d, stream));
1907     CeedCall(CeedScalarView("qweight1d", "\t% 12.8f", 1, Q_1d, q_weight_1d, stream));
1908     CeedCall(CeedScalarView("interp1d", "\t% 12.8f", Q_1d, P_1d, interp_1d, stream));
1909     CeedCall(CeedScalarView("grad1d", "\t% 12.8f", Q_1d, P_1d, grad_1d, stream));
1910   } else {  // non-tensor basis
1911     CeedInt           P, Q, dim, q_comp;
1912     const CeedScalar *q_ref, *q_weight, *interp, *grad, *div, *curl;
1913 
1914     CeedCall(CeedBasisGetNumNodes(basis, &P));
1915     CeedCall(CeedBasisGetNumQuadraturePoints(basis, &Q));
1916     CeedCall(CeedBasisGetDimension(basis, &dim));
1917     CeedCall(CeedBasisGetQRef(basis, &q_ref));
1918     CeedCall(CeedBasisGetQWeights(basis, &q_weight));
1919     CeedCall(CeedBasisGetInterp(basis, &interp));
1920     CeedCall(CeedBasisGetGrad(basis, &grad));
1921     CeedCall(CeedBasisGetDiv(basis, &div));
1922     CeedCall(CeedBasisGetCurl(basis, &curl));
1923 
1924     CeedCall(CeedScalarView("qref", "\t% 12.8f", 1, Q * dim, q_ref, stream));
1925     CeedCall(CeedScalarView("qweight", "\t% 12.8f", 1, Q, q_weight, stream));
1926     CeedCall(CeedBasisGetNumQuadratureComponents(basis, CEED_EVAL_INTERP, &q_comp));
1927     CeedCall(CeedScalarView("interp", "\t% 12.8f", q_comp * Q, P, interp, stream));
1928     if (grad) {
1929       CeedCall(CeedBasisGetNumQuadratureComponents(basis, CEED_EVAL_GRAD, &q_comp));
1930       CeedCall(CeedScalarView("grad", "\t% 12.8f", q_comp * Q, P, grad, stream));
1931     }
1932     if (div) {
1933       CeedCall(CeedBasisGetNumQuadratureComponents(basis, CEED_EVAL_DIV, &q_comp));
1934       CeedCall(CeedScalarView("div", "\t% 12.8f", q_comp * Q, P, div, stream));
1935     }
1936     if (curl) {
1937       CeedCall(CeedBasisGetNumQuadratureComponents(basis, CEED_EVAL_CURL, &q_comp));
1938       CeedCall(CeedScalarView("curl", "\t% 12.8f", q_comp * Q, P, curl, stream));
1939     }
1940   }
1941   return CEED_ERROR_SUCCESS;
1942 }
1943 
1944 /**
1945   @brief Apply basis evaluation from nodes to quadrature points or vice versa
1946 
1947   @param[in]  basis     `CeedBasis` to evaluate
1948   @param[in]  num_elem  The number of elements to apply the basis evaluation to;
1949                           the backend will specify the ordering in @ref CeedElemRestrictionCreate()
1950   @param[in]  t_mode    @ref CEED_NOTRANSPOSE to evaluate from nodes to quadrature points;
1951                           @ref CEED_TRANSPOSE to apply the transpose, mapping from quadrature points to nodes
1952   @param[in]  eval_mode @ref CEED_EVAL_NONE to use values directly,
1953                           @ref CEED_EVAL_INTERP to use interpolated values,
1954                           @ref CEED_EVAL_GRAD to use gradients,
1955                           @ref CEED_EVAL_DIV to use divergence,
1956                           @ref CEED_EVAL_CURL to use curl,
1957                           @ref CEED_EVAL_WEIGHT to use quadrature weights
1958   @param[in]  u         Input `CeedVector`
1959   @param[out] v         Output `CeedVector`
1960 
1961   @return An error code: 0 - success, otherwise - failure
1962 
1963   @ref User
1964 **/
1965 int CeedBasisApply(CeedBasis basis, CeedInt num_elem, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedVector u, CeedVector v) {
1966   CeedCall(CeedBasisApplyCheckDims(basis, num_elem, t_mode, eval_mode, u, v));
1967   CeedCheck(basis->Apply, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED, "Backend does not support CeedBasisApply");
1968   CeedCall(basis->Apply(basis, num_elem, t_mode, eval_mode, u, v));
1969   return CEED_ERROR_SUCCESS;
1970 }
1971 
1972 /**
1973   @brief Apply basis evaluation from quadrature points to nodes and sum into target vector
1974 
1975   @param[in]  basis     `CeedBasis` to evaluate
1976   @param[in]  num_elem  The number of elements to apply the basis evaluation to;
1977                           the backend will specify the ordering in @ref CeedElemRestrictionCreate()
1978   @param[in]  t_mode    @ref CEED_TRANSPOSE to apply the transpose, mapping from quadrature points to nodes;
1979                            @ref CEED_NOTRANSPOSE is not valid for `CeedBasisApplyAdd()`
1980   @param[in]  eval_mode @ref CEED_EVAL_NONE to use values directly,
1981                           @ref CEED_EVAL_INTERP to use interpolated values,
1982                           @ref CEED_EVAL_GRAD to use gradients,
1983                           @ref CEED_EVAL_DIV to use divergence,
1984                           @ref CEED_EVAL_CURL to use curl,
1985                           @ref CEED_EVAL_WEIGHT to use quadrature weights
1986   @param[in]  u         Input `CeedVector`
1987   @param[out] v         Output `CeedVector` to sum into
1988 
1989   @return An error code: 0 - success, otherwise - failure
1990 
1991   @ref User
1992 **/
1993 int CeedBasisApplyAdd(CeedBasis basis, CeedInt num_elem, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedVector u, CeedVector v) {
1994   CeedCheck(t_mode == CEED_TRANSPOSE, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED, "CeedBasisApplyAdd only supports CEED_TRANSPOSE");
1995   CeedCall(CeedBasisApplyCheckDims(basis, num_elem, t_mode, eval_mode, u, v));
1996   CeedCheck(basis->ApplyAdd, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED, "Backend does not implement CeedBasisApplyAdd");
1997   CeedCall(basis->ApplyAdd(basis, num_elem, t_mode, eval_mode, u, v));
1998   return CEED_ERROR_SUCCESS;
1999 }
2000 
2001 /**
2002   @brief Apply basis evaluation from nodes to arbitrary points
2003 
2004   @param[in]  basis      `CeedBasis` to evaluate
2005   @param[in]  num_elem   The number of elements to apply the basis evaluation to;
2006                           the backend will specify the ordering in @ref CeedElemRestrictionCreate()
2007   @param[in]  num_points Array of the number of points to apply the basis evaluation to in each element, size `num_elem`
2008   @param[in]  t_mode     @ref CEED_NOTRANSPOSE to evaluate from nodes to points;
2009                            @ref CEED_TRANSPOSE to apply the transpose, mapping from points to nodes
2010   @param[in]  eval_mode  @ref CEED_EVAL_INTERP to use interpolated values,
2011                            @ref CEED_EVAL_GRAD to use gradients,
2012                            @ref CEED_EVAL_WEIGHT to use quadrature weights
2013   @param[in]  x_ref      `CeedVector` holding reference coordinates of each point
2014   @param[in]  u          Input `CeedVector`, of length `num_nodes * num_comp` for @ref CEED_NOTRANSPOSE
2015   @param[out] v          Output `CeedVector`, of length `num_points * num_q_comp` for @ref CEED_NOTRANSPOSE with @ref CEED_EVAL_INTERP
2016 
2017   @return An error code: 0 - success, otherwise - failure
2018 
2019   @ref User
2020 **/
2021 int CeedBasisApplyAtPoints(CeedBasis basis, CeedInt num_elem, const CeedInt *num_points, CeedTransposeMode t_mode, CeedEvalMode eval_mode,
2022                            CeedVector x_ref, CeedVector u, CeedVector v) {
2023   CeedCall(CeedBasisApplyAtPointsCheckDims(basis, num_elem, num_points, t_mode, eval_mode, x_ref, u, v));
2024   if (basis->ApplyAtPoints) {
2025     CeedCall(basis->ApplyAtPoints(basis, num_elem, num_points, t_mode, eval_mode, x_ref, u, v));
2026   } else {
2027     CeedCall(CeedBasisApplyAtPoints_Core(basis, false, num_elem, num_points, t_mode, eval_mode, x_ref, u, v));
2028   }
2029   return CEED_ERROR_SUCCESS;
2030 }
2031 
2032 /**
2033   @brief Apply basis evaluation from nodes to arbitrary points and sum into target vector
2034 
2035   @param[in]  basis      `CeedBasis` to evaluate
2036   @param[in]  num_elem   The number of elements to apply the basis evaluation to;
2037                           the backend will specify the ordering in @ref CeedElemRestrictionCreate()
2038   @param[in]  num_points Array of the number of points to apply the basis evaluation to in each element, size `num_elem`
2039   @param[in]  t_mode     @ref CEED_NOTRANSPOSE to evaluate from nodes to points;
2040                            @ref CEED_NOTRANSPOSE is not valid for `CeedBasisApplyAddAtPoints()`
2041   @param[in]  eval_mode  @ref CEED_EVAL_INTERP to use interpolated values,
2042                            @ref CEED_EVAL_GRAD to use gradients,
2043                            @ref CEED_EVAL_WEIGHT to use quadrature weights
2044   @param[in]  x_ref      `CeedVector` holding reference coordinates of each point
2045   @param[in]  u          Input `CeedVector`, of length `num_nodes * num_comp` for @ref CEED_NOTRANSPOSE
2046   @param[out] v          Output `CeedVector`, of length `num_points * num_q_comp` for @ref CEED_NOTRANSPOSE with @ref CEED_EVAL_INTERP
2047 
2048   @return An error code: 0 - success, otherwise - failure
2049 
2050   @ref User
2051 **/
2052 int CeedBasisApplyAddAtPoints(CeedBasis basis, CeedInt num_elem, const CeedInt *num_points, CeedTransposeMode t_mode, CeedEvalMode eval_mode,
2053                               CeedVector x_ref, CeedVector u, CeedVector v) {
2054   CeedCheck(t_mode == CEED_TRANSPOSE, CeedBasisReturnCeed(basis), CEED_ERROR_UNSUPPORTED, "CeedBasisApplyAddAtPoints only supports CEED_TRANSPOSE");
2055   CeedCall(CeedBasisApplyAtPointsCheckDims(basis, num_elem, num_points, t_mode, eval_mode, x_ref, u, v));
2056   if (basis->ApplyAddAtPoints) {
2057     CeedCall(basis->ApplyAddAtPoints(basis, num_elem, num_points, t_mode, eval_mode, x_ref, u, v));
2058   } else {
2059     CeedCall(CeedBasisApplyAtPoints_Core(basis, true, num_elem, num_points, t_mode, eval_mode, x_ref, u, v));
2060   }
2061   return CEED_ERROR_SUCCESS;
2062 }
2063 
2064 /**
2065   @brief Get the `Ceed` associated with a `CeedBasis`
2066 
2067   @param[in]  basis `CeedBasis`
2068   @param[out] ceed  Variable to store `Ceed`
2069 
2070   @return An error code: 0 - success, otherwise - failure
2071 
2072   @ref Advanced
2073 **/
2074 int CeedBasisGetCeed(CeedBasis basis, Ceed *ceed) {
2075   *ceed = NULL;
2076   CeedCall(CeedReferenceCopy(CeedBasisReturnCeed(basis), ceed));
2077   return CEED_ERROR_SUCCESS;
2078 }
2079 
2080 /**
2081   @brief Return the `Ceed` associated with a `CeedBasis`
2082 
2083   @param[in]  basis `CeedBasis`
2084 
2085   @return `Ceed` associated with the `basis`
2086 
2087   @ref Advanced
2088 **/
2089 Ceed CeedBasisReturnCeed(CeedBasis basis) { return basis->ceed; }
2090 
2091 /**
2092   @brief Get dimension for given `CeedBasis`
2093 
2094   @param[in]  basis `CeedBasis`
2095   @param[out] dim   Variable to store dimension of basis
2096 
2097   @return An error code: 0 - success, otherwise - failure
2098 
2099   @ref Advanced
2100 **/
2101 int CeedBasisGetDimension(CeedBasis basis, CeedInt *dim) {
2102   *dim = basis->dim;
2103   return CEED_ERROR_SUCCESS;
2104 }
2105 
2106 /**
2107   @brief Get topology for given `CeedBasis`
2108 
2109   @param[in]  basis `CeedBasis`
2110   @param[out] topo  Variable to store topology of basis
2111 
2112   @return An error code: 0 - success, otherwise - failure
2113 
2114   @ref Advanced
2115 **/
2116 int CeedBasisGetTopology(CeedBasis basis, CeedElemTopology *topo) {
2117   *topo = basis->topo;
2118   return CEED_ERROR_SUCCESS;
2119 }
2120 
2121 /**
2122   @brief Get number of components for given `CeedBasis`
2123 
2124   @param[in]  basis    `CeedBasis`
2125   @param[out] num_comp Variable to store number of components
2126 
2127   @return An error code: 0 - success, otherwise - failure
2128 
2129   @ref Advanced
2130 **/
2131 int CeedBasisGetNumComponents(CeedBasis basis, CeedInt *num_comp) {
2132   *num_comp = basis->num_comp;
2133   return CEED_ERROR_SUCCESS;
2134 }
2135 
2136 /**
2137   @brief Get total number of nodes (in `dim` dimensions) of a `CeedBasis`
2138 
2139   @param[in]  basis `CeedBasis`
2140   @param[out] P     Variable to store number of nodes
2141 
2142   @return An error code: 0 - success, otherwise - failure
2143 
2144   @ref Utility
2145 **/
2146 int CeedBasisGetNumNodes(CeedBasis basis, CeedInt *P) {
2147   *P = basis->P;
2148   return CEED_ERROR_SUCCESS;
2149 }
2150 
2151 /**
2152   @brief Get total number of nodes (in 1 dimension) of a `CeedBasis`
2153 
2154   @param[in]  basis `CeedBasis`
2155   @param[out] P_1d  Variable to store number of nodes
2156 
2157   @return An error code: 0 - success, otherwise - failure
2158 
2159   @ref Advanced
2160 **/
2161 int CeedBasisGetNumNodes1D(CeedBasis basis, CeedInt *P_1d) {
2162   CeedCheck(basis->is_tensor_basis, CeedBasisReturnCeed(basis), CEED_ERROR_MINOR, "Cannot supply P_1d for non-tensor CeedBasis");
2163   *P_1d = basis->P_1d;
2164   return CEED_ERROR_SUCCESS;
2165 }
2166 
2167 /**
2168   @brief Get total number of quadrature points (in `dim` dimensions) of a `CeedBasis`
2169 
2170   @param[in]  basis `CeedBasis`
2171   @param[out] Q     Variable to store number of quadrature points
2172 
2173   @return An error code: 0 - success, otherwise - failure
2174 
2175   @ref Utility
2176 **/
2177 int CeedBasisGetNumQuadraturePoints(CeedBasis basis, CeedInt *Q) {
2178   *Q = basis->Q;
2179   return CEED_ERROR_SUCCESS;
2180 }
2181 
2182 /**
2183   @brief Get total number of quadrature points (in 1 dimension) of a `CeedBasis`
2184 
2185   @param[in]  basis `CeedBasis`
2186   @param[out] Q_1d  Variable to store number of quadrature points
2187 
2188   @return An error code: 0 - success, otherwise - failure
2189 
2190   @ref Advanced
2191 **/
2192 int CeedBasisGetNumQuadraturePoints1D(CeedBasis basis, CeedInt *Q_1d) {
2193   CeedCheck(basis->is_tensor_basis, CeedBasisReturnCeed(basis), CEED_ERROR_MINOR, "Cannot supply Q_1d for non-tensor CeedBasis");
2194   *Q_1d = basis->Q_1d;
2195   return CEED_ERROR_SUCCESS;
2196 }
2197 
2198 /**
2199   @brief Get reference coordinates of quadrature points (in `dim` dimensions) of a `CeedBasis`
2200 
2201   @param[in]  basis `CeedBasis`
2202   @param[out] q_ref Variable to store reference coordinates of quadrature points
2203 
2204   @return An error code: 0 - success, otherwise - failure
2205 
2206   @ref Advanced
2207 **/
2208 int CeedBasisGetQRef(CeedBasis basis, const CeedScalar **q_ref) {
2209   *q_ref = basis->q_ref_1d;
2210   return CEED_ERROR_SUCCESS;
2211 }
2212 
2213 /**
2214   @brief Get quadrature weights of quadrature points (in `dim` dimensions) of a `CeedBasis`
2215 
2216   @param[in]  basis    `CeedBasis`
2217   @param[out] q_weight Variable to store quadrature weights
2218 
2219   @return An error code: 0 - success, otherwise - failure
2220 
2221   @ref Advanced
2222 **/
2223 int CeedBasisGetQWeights(CeedBasis basis, const CeedScalar **q_weight) {
2224   *q_weight = basis->q_weight_1d;
2225   return CEED_ERROR_SUCCESS;
2226 }
2227 
2228 /**
2229   @brief Get interpolation matrix of a `CeedBasis`
2230 
2231   @param[in]  basis  `CeedBasis`
2232   @param[out] interp Variable to store interpolation matrix
2233 
2234   @return An error code: 0 - success, otherwise - failure
2235 
2236   @ref Advanced
2237 **/
2238 int CeedBasisGetInterp(CeedBasis basis, const CeedScalar **interp) {
2239   if (!basis->interp && basis->is_tensor_basis) {
2240     // Allocate
2241     CeedCall(CeedMalloc(basis->Q * basis->P, &basis->interp));
2242 
2243     // Initialize
2244     for (CeedInt i = 0; i < basis->Q * basis->P; i++) basis->interp[i] = 1.0;
2245 
2246     // Calculate
2247     for (CeedInt d = 0; d < basis->dim; d++) {
2248       for (CeedInt qpt = 0; qpt < basis->Q; qpt++) {
2249         for (CeedInt node = 0; node < basis->P; node++) {
2250           CeedInt p = (node / CeedIntPow(basis->P_1d, d)) % basis->P_1d;
2251           CeedInt q = (qpt / CeedIntPow(basis->Q_1d, d)) % basis->Q_1d;
2252 
2253           basis->interp[qpt * (basis->P) + node] *= basis->interp_1d[q * basis->P_1d + p];
2254         }
2255       }
2256     }
2257   }
2258   *interp = basis->interp;
2259   return CEED_ERROR_SUCCESS;
2260 }
2261 
2262 /**
2263   @brief Get 1D interpolation matrix of a tensor product `CeedBasis`
2264 
2265   @param[in]  basis     `CeedBasis`
2266   @param[out] interp_1d Variable to store interpolation matrix
2267 
2268   @return An error code: 0 - success, otherwise - failure
2269 
2270   @ref Backend
2271 **/
2272 int CeedBasisGetInterp1D(CeedBasis basis, const CeedScalar **interp_1d) {
2273   bool is_tensor_basis;
2274 
2275   CeedCall(CeedBasisIsTensor(basis, &is_tensor_basis));
2276   CeedCheck(is_tensor_basis, CeedBasisReturnCeed(basis), CEED_ERROR_MINOR, "CeedBasis is not a tensor product CeedBasis");
2277   *interp_1d = basis->interp_1d;
2278   return CEED_ERROR_SUCCESS;
2279 }
2280 
2281 /**
2282   @brief Get gradient matrix of a `CeedBasis`
2283 
2284   @param[in]  basis `CeedBasis`
2285   @param[out] grad  Variable to store gradient matrix
2286 
2287   @return An error code: 0 - success, otherwise - failure
2288 
2289   @ref Advanced
2290 **/
2291 int CeedBasisGetGrad(CeedBasis basis, const CeedScalar **grad) {
2292   if (!basis->grad && basis->is_tensor_basis) {
2293     // Allocate
2294     CeedCall(CeedMalloc(basis->dim * basis->Q * basis->P, &basis->grad));
2295 
2296     // Initialize
2297     for (CeedInt i = 0; i < basis->dim * basis->Q * basis->P; i++) basis->grad[i] = 1.0;
2298 
2299     // Calculate
2300     for (CeedInt d = 0; d < basis->dim; d++) {
2301       for (CeedInt i = 0; i < basis->dim; i++) {
2302         for (CeedInt qpt = 0; qpt < basis->Q; qpt++) {
2303           for (CeedInt node = 0; node < basis->P; node++) {
2304             CeedInt p = (node / CeedIntPow(basis->P_1d, d)) % basis->P_1d;
2305             CeedInt q = (qpt / CeedIntPow(basis->Q_1d, d)) % basis->Q_1d;
2306 
2307             if (i == d) basis->grad[(i * basis->Q + qpt) * (basis->P) + node] *= basis->grad_1d[q * basis->P_1d + p];
2308             else basis->grad[(i * basis->Q + qpt) * (basis->P) + node] *= basis->interp_1d[q * basis->P_1d + p];
2309           }
2310         }
2311       }
2312     }
2313   }
2314   *grad = basis->grad;
2315   return CEED_ERROR_SUCCESS;
2316 }
2317 
2318 /**
2319   @brief Get 1D gradient matrix of a tensor product `CeedBasis`
2320 
2321   @param[in]  basis   `CeedBasis`
2322   @param[out] grad_1d Variable to store gradient matrix
2323 
2324   @return An error code: 0 - success, otherwise - failure
2325 
2326   @ref Advanced
2327 **/
2328 int CeedBasisGetGrad1D(CeedBasis basis, const CeedScalar **grad_1d) {
2329   bool is_tensor_basis;
2330 
2331   CeedCall(CeedBasisIsTensor(basis, &is_tensor_basis));
2332   CeedCheck(is_tensor_basis, CeedBasisReturnCeed(basis), CEED_ERROR_MINOR, "CeedBasis is not a tensor product CeedBasis");
2333   *grad_1d = basis->grad_1d;
2334   return CEED_ERROR_SUCCESS;
2335 }
2336 
2337 /**
2338   @brief Get divergence matrix of a `CeedBasis`
2339 
2340   @param[in]  basis `CeedBasis`
2341   @param[out] div   Variable to store divergence matrix
2342 
2343   @return An error code: 0 - success, otherwise - failure
2344 
2345   @ref Advanced
2346 **/
2347 int CeedBasisGetDiv(CeedBasis basis, const CeedScalar **div) {
2348   *div = basis->div;
2349   return CEED_ERROR_SUCCESS;
2350 }
2351 
2352 /**
2353   @brief Get curl matrix of a `CeedBasis`
2354 
2355   @param[in]  basis `CeedBasis`
2356   @param[out] curl  Variable to store curl matrix
2357 
2358   @return An error code: 0 - success, otherwise - failure
2359 
2360   @ref Advanced
2361 **/
2362 int CeedBasisGetCurl(CeedBasis basis, const CeedScalar **curl) {
2363   *curl = basis->curl;
2364   return CEED_ERROR_SUCCESS;
2365 }
2366 
2367 /**
2368   @brief Destroy a @ref  CeedBasis
2369 
2370   @param[in,out] basis `CeedBasis` to destroy
2371 
2372   @return An error code: 0 - success, otherwise - failure
2373 
2374   @ref User
2375 **/
2376 int CeedBasisDestroy(CeedBasis *basis) {
2377   if (!*basis || *basis == CEED_BASIS_NONE || --(*basis)->ref_count > 0) {
2378     *basis = NULL;
2379     return CEED_ERROR_SUCCESS;
2380   }
2381   if ((*basis)->Destroy) CeedCall((*basis)->Destroy(*basis));
2382   CeedCall(CeedTensorContractDestroy(&(*basis)->contract));
2383   CeedCall(CeedFree(&(*basis)->q_ref_1d));
2384   CeedCall(CeedFree(&(*basis)->q_weight_1d));
2385   CeedCall(CeedFree(&(*basis)->interp));
2386   CeedCall(CeedFree(&(*basis)->interp_1d));
2387   CeedCall(CeedFree(&(*basis)->grad));
2388   CeedCall(CeedFree(&(*basis)->grad_1d));
2389   CeedCall(CeedFree(&(*basis)->div));
2390   CeedCall(CeedFree(&(*basis)->curl));
2391   CeedCall(CeedVectorDestroy(&(*basis)->vec_chebyshev));
2392   CeedCall(CeedBasisDestroy(&(*basis)->basis_chebyshev));
2393   CeedCall(CeedDestroy(&(*basis)->ceed));
2394   CeedCall(CeedFree(basis));
2395   return CEED_ERROR_SUCCESS;
2396 }
2397 
2398 /**
2399   @brief Construct a Gauss-Legendre quadrature
2400 
2401   @param[in]  Q           Number of quadrature points (integrates polynomials of degree `2*Q-1` exactly)
2402   @param[out] q_ref_1d    Array of length `Q` to hold the abscissa on `[-1, 1]`
2403   @param[out] q_weight_1d Array of length `Q` to hold the weights
2404 
2405   @return An error code: 0 - success, otherwise - failure
2406 
2407   @ref Utility
2408 **/
2409 int CeedGaussQuadrature(CeedInt Q, CeedScalar *q_ref_1d, CeedScalar *q_weight_1d) {
2410   CeedScalar P0, P1, P2, dP2, xi, wi, PI = 4.0 * atan(1.0);
2411 
2412   // Build q_ref_1d, q_weight_1d
2413   for (CeedInt i = 0; i <= Q / 2; i++) {
2414     // Guess
2415     xi = cos(PI * (CeedScalar)(2 * i + 1) / ((CeedScalar)(2 * Q)));
2416     // Pn(xi)
2417     P0 = 1.0;
2418     P1 = xi;
2419     P2 = 0.0;
2420     for (CeedInt j = 2; j <= Q; j++) {
2421       P2 = (((CeedScalar)(2 * j - 1)) * xi * P1 - ((CeedScalar)(j - 1)) * P0) / ((CeedScalar)(j));
2422       P0 = P1;
2423       P1 = P2;
2424     }
2425     // First Newton Step
2426     dP2 = (xi * P2 - P0) * (CeedScalar)Q / (xi * xi - 1.0);
2427     xi  = xi - P2 / dP2;
2428     // Newton to convergence
2429     for (CeedInt k = 0; k < 100 && fabs(P2) > 10 * CEED_EPSILON; k++) {
2430       P0 = 1.0;
2431       P1 = xi;
2432       for (CeedInt j = 2; j <= Q; j++) {
2433         P2 = (((CeedScalar)(2 * j - 1)) * xi * P1 - ((CeedScalar)(j - 1)) * P0) / ((CeedScalar)(j));
2434         P0 = P1;
2435         P1 = P2;
2436       }
2437       dP2 = (xi * P2 - P0) * (CeedScalar)Q / (xi * xi - 1.0);
2438       xi  = xi - P2 / dP2;
2439     }
2440     // Save xi, wi
2441     wi                     = 2.0 / ((1.0 - xi * xi) * dP2 * dP2);
2442     q_weight_1d[i]         = wi;
2443     q_weight_1d[Q - 1 - i] = wi;
2444     q_ref_1d[i]            = -xi;
2445     q_ref_1d[Q - 1 - i]    = xi;
2446   }
2447   return CEED_ERROR_SUCCESS;
2448 }
2449 
2450 /**
2451   @brief Construct a Gauss-Legendre-Lobatto quadrature
2452 
2453   @param[in]  Q           Number of quadrature points (integrates polynomials of degree `2*Q-3` exactly)
2454   @param[out] q_ref_1d    Array of length `Q` to hold the abscissa on `[-1, 1]`
2455   @param[out] q_weight_1d Array of length `Q` to hold the weights
2456 
2457   @return An error code: 0 - success, otherwise - failure
2458 
2459   @ref Utility
2460 **/
2461 int CeedLobattoQuadrature(CeedInt Q, CeedScalar *q_ref_1d, CeedScalar *q_weight_1d) {
2462   CeedScalar P0, P1, P2, dP2, d2P2, xi, wi, PI = 4.0 * atan(1.0);
2463 
2464   // Build q_ref_1d, q_weight_1d
2465   // Set endpoints
2466   CeedCheck(Q > 1, NULL, CEED_ERROR_DIMENSION, "Cannot create Lobatto quadrature with Q=%" CeedInt_FMT " < 2 points", Q);
2467   wi = 2.0 / ((CeedScalar)(Q * (Q - 1)));
2468   if (q_weight_1d) {
2469     q_weight_1d[0]     = wi;
2470     q_weight_1d[Q - 1] = wi;
2471   }
2472   q_ref_1d[0]     = -1.0;
2473   q_ref_1d[Q - 1] = 1.0;
2474   // Interior
2475   for (CeedInt i = 1; i <= (Q - 1) / 2; i++) {
2476     // Guess
2477     xi = cos(PI * (CeedScalar)(i) / (CeedScalar)(Q - 1));
2478     // Pn(xi)
2479     P0 = 1.0;
2480     P1 = xi;
2481     P2 = 0.0;
2482     for (CeedInt j = 2; j < Q; j++) {
2483       P2 = (((CeedScalar)(2 * j - 1)) * xi * P1 - ((CeedScalar)(j - 1)) * P0) / ((CeedScalar)(j));
2484       P0 = P1;
2485       P1 = P2;
2486     }
2487     // First Newton step
2488     dP2  = (xi * P2 - P0) * (CeedScalar)Q / (xi * xi - 1.0);
2489     d2P2 = (2 * xi * dP2 - (CeedScalar)(Q * (Q - 1)) * P2) / (1.0 - xi * xi);
2490     xi   = xi - dP2 / d2P2;
2491     // Newton to convergence
2492     for (CeedInt k = 0; k < 100 && fabs(dP2) > 10 * CEED_EPSILON; k++) {
2493       P0 = 1.0;
2494       P1 = xi;
2495       for (CeedInt j = 2; j < Q; j++) {
2496         P2 = (((CeedScalar)(2 * j - 1)) * xi * P1 - ((CeedScalar)(j - 1)) * P0) / ((CeedScalar)(j));
2497         P0 = P1;
2498         P1 = P2;
2499       }
2500       dP2  = (xi * P2 - P0) * (CeedScalar)Q / (xi * xi - 1.0);
2501       d2P2 = (2 * xi * dP2 - (CeedScalar)(Q * (Q - 1)) * P2) / (1.0 - xi * xi);
2502       xi   = xi - dP2 / d2P2;
2503     }
2504     // Save xi, wi
2505     wi = 2.0 / (((CeedScalar)(Q * (Q - 1))) * P2 * P2);
2506     if (q_weight_1d) {
2507       q_weight_1d[i]         = wi;
2508       q_weight_1d[Q - 1 - i] = wi;
2509     }
2510     q_ref_1d[i]         = -xi;
2511     q_ref_1d[Q - 1 - i] = xi;
2512   }
2513   return CEED_ERROR_SUCCESS;
2514 }
2515 
2516 /// @}
2517