CeedBasis

A CeedBasis defines the discrete finite element basis and associated quadrature rule.

Discrete element bases and quadrature

typedef struct CeedBasis_private *CeedBasis

Handle for object describing discrete finite element evaluations.

const CeedBasis CEED_BASIS_COLLOCATED = &ceed_basis_collocated

Indicate that the quadrature points are collocated with the nodes.

int CeedBasisCreateTensorH1(Ceed ceed, CeedInt dim, CeedInt num_comp, CeedInt P_1d, CeedInt Q_1d, const CeedScalar *interp_1d, const CeedScalar *grad_1d, const CeedScalar *q_ref_1d, const CeedScalar *q_weight_1d, CeedBasis *basis)

Create a tensor-product basis for H^1 discretizations.

User Functions

Parameters

  • ceed – A Ceed object where the CeedBasis will be created

  • dim – Topological dimension

  • num_comp – Number of field components (1 for scalar fields)

  • P_1d – Number of nodes in one dimension

  • Q_1d – Number of quadrature points in one dimension

  • interp_1d – Row-major (Q_1d * P_1d) matrix expressing the values of nodal basis functions at quadrature points

  • grad_1d – Row-major (Q_1d * P_1d) matrix expressing derivatives of nodal basis functions at quadrature points

  • q_ref_1d – Array of length Q_1d holding the locations of quadrature points on the 1D reference element [-1, 1]

  • q_weight_1d – Array of length Q_1d holding the quadrature weights on the reference element

  • basis – [out] Address of the variable where the newly created CeedBasis will be stored.

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisCreateTensorH1Lagrange(Ceed ceed, CeedInt dim, CeedInt num_comp, CeedInt P, CeedInt Q, CeedQuadMode quad_mode, CeedBasis *basis)

Create a tensor-product Lagrange basis.

User Functions

Parameters

  • ceed – A Ceed object where the CeedBasis will be created

  • dim – Topological dimension of element

  • num_comp – Number of field components (1 for scalar fields)

  • P – Number of Gauss-Lobatto nodes in one dimension. The polynomial degree of the resulting Q_k element is k=P-1.

  • Q – Number of quadrature points in one dimension.

  • quad_mode – Distribution of the Q quadrature points (affects order of accuracy for the quadrature)

  • basis – [out] Address of the variable where the newly created CeedBasis will be stored.

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisCreateH1(Ceed ceed, CeedElemTopology topo, CeedInt num_comp, CeedInt num_nodes, CeedInt num_qpts, const CeedScalar *interp, const CeedScalar *grad, const CeedScalar *q_ref, const CeedScalar *q_weight, CeedBasis *basis)

Create a non tensor-product basis for H^1 discretizations.

User Functions

Parameters

  • ceed – A Ceed object where the CeedBasis will be created

  • topo – Topology of element, e.g. hypercube, simplex, ect

  • num_comp – Number of field components (1 for scalar fields)

  • num_nodes – Total number of nodes

  • num_qpts – Total number of quadrature points

  • interp – Row-major (num_qpts * num_nodes) matrix expressing the values of nodal basis functions at quadrature points

  • grad – Row-major (num_qpts * dim * num_nodes) matrix expressing derivatives of nodal basis functions at quadrature points

  • q_ref – Array of length num_qpts holding the locations of quadrature points on the reference element [-1, 1]

  • q_weight – Array of length num_qpts holding the quadrature weights on the reference element

  • basis – [out] Address of the variable where the newly created CeedBasis will be stored.

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisReferenceCopy(CeedBasis basis, CeedBasis *basis_copy)

Copy the pointer to a CeedBasis.

Both pointers should be destroyed with CeedBasisDestroy(); Note: If *basis_copy is non-NULL, then it is assumed that *basis_copy is a pointer to a CeedBasis. This CeedBasis will be destroyed if *basis_copy is the only reference to this CeedBasis.

User Functions

Parameters

  • basis – CeedBasis to copy reference to

  • basis_copy – [out] Variable to store copied reference

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisView(CeedBasis basis, FILE *stream)

View a CeedBasis.

User Functions

Parameters

  • basis – CeedBasis to view

  • stream – Stream to view to, e.g., stdout

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisApply(CeedBasis basis, CeedInt num_elem, CeedTransposeMode t_mode, CeedEvalMode eval_mode, CeedVector u, CeedVector v)

Apply basis evaluation from nodes to quadrature points or vice versa.

User Functions

Parameters
Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetCeed(CeedBasis basis, Ceed *ceed)

Get Ceed associated with a CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • ceed – [out] Variable to store Ceed

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetDimension(CeedBasis basis, CeedInt *dim)

Get dimension for given CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • dim – [out] Variable to store dimension of basis

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetTopology(CeedBasis basis, CeedElemTopology *topo)

Get topology for given CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • topo – [out] Variable to store topology of basis

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetNumComponents(CeedBasis basis, CeedInt *num_comp)

Get number of components for given CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • num_comp – [out] Variable to store number of components of basis

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetNumNodes(CeedBasis basis, CeedInt *P)

Get total number of nodes (in dim dimensions) of a CeedBasis.

Utility Functions

Parameters

  • basis – CeedBasis

  • P – [out] Variable to store number of nodes

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetNumNodes1D(CeedBasis basis, CeedInt *P_1d)

Get total number of nodes (in 1 dimension) of a CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • P_1d – [out] Variable to store number of nodes

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetNumQuadraturePoints(CeedBasis basis, CeedInt *Q)

Get total number of quadrature points (in dim dimensions) of a CeedBasis.

Utility Functions

Parameters

  • basis – CeedBasis

  • Q – [out] Variable to store number of quadrature points

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetNumQuadraturePoints1D(CeedBasis basis, CeedInt *Q_1d)

Get total number of quadrature points (in 1 dimension) of a CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • Q_1d – [out] Variable to store number of quadrature points

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetQRef(CeedBasis basis, const CeedScalar **q_ref)

Get reference coordinates of quadrature points (in dim dimensions) of a CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • q_ref – [out] Variable to store reference coordinates of quadrature points

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetQWeights(CeedBasis basis, const CeedScalar **q_weight)

Get quadrature weights of quadrature points (in dim dimensions) of a CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • q_weight – [out] Variable to store quadrature weights

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetInterp(CeedBasis basis, const CeedScalar **interp)

Get interpolation matrix of a CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • interp – [out] Variable to store interpolation matrix

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetInterp1D(CeedBasis basis, const CeedScalar **interp_1d)

Get 1D interpolation matrix of a tensor product CeedBasis.

Backend Developer Functions

Parameters

  • basis – CeedBasis

  • interp_1d – [out] Variable to store interpolation matrix

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetGrad(CeedBasis basis, const CeedScalar **grad)

Get gradient matrix of a CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • grad – [out] Variable to store gradient matrix

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisGetGrad1D(CeedBasis basis, const CeedScalar **grad_1d)

Get 1D gradient matrix of a tensor product CeedBasis.

Advanced Functions

Parameters

  • basis – CeedBasis

  • grad_1d – [out] Variable to store gradient matrix

Returns

An error code: 0 - success, otherwise - failure

int CeedBasisDestroy(CeedBasis *basis)

Destroy a CeedBasis.

User Functions

Parameters

  • basis – CeedBasis to destroy

Returns

An error code: 0 - success, otherwise - failure

int CeedGaussQuadrature(CeedInt Q, CeedScalar *q_ref_1d, CeedScalar *q_weight_1d)

Construct a Gauss-Legendre quadrature.

Utility Functions

Parameters

  • Q – Number of quadrature points (integrates polynomials of degree 2*Q-1 exactly)

  • q_ref_1d – [out] Array of length Q to hold the abscissa on [-1, 1]

  • q_weight_1d – [out] Array of length Q to hold the weights

Returns

An error code: 0 - success, otherwise - failure

int CeedLobattoQuadrature(CeedInt Q, CeedScalar *q_ref_1d, CeedScalar *q_weight_1d)

Construct a Gauss-Legendre-Lobatto quadrature.

Utility Functions

Parameters

  • Q – Number of quadrature points (integrates polynomials of degree 2*Q-3 exactly)

  • q_ref_1d – [out] Array of length Q to hold the abscissa on [-1, 1]

  • q_weight_1d – [out] Array of length Q to hold the weights

Returns

An error code: 0 - success, otherwise - failure

int CeedQRFactorization(Ceed ceed, CeedScalar *mat, CeedScalar *tau, CeedInt m, CeedInt n)

Return QR Factorization of a matrix.

Utility Functions

Parameters

  • ceed – A Ceed context for error handling

  • mat – [inout] Row-major matrix to be factorized in place

  • tau – [inout] Vector of length m of scaling factors

  • m – Number of rows

  • n – Number of columns

Returns

An error code: 0 - success, otherwise - failure

int CeedSymmetricSchurDecomposition(Ceed ceed, CeedScalar *mat, CeedScalar *lambda, CeedInt n)

Return symmetric Schur decomposition of the symmetric matrix mat via symmetric QR factorization.

Utility Functions

Parameters

  • ceed – A Ceed context for error handling

  • mat – [inout] Row-major matrix to be factorized in place

  • lambda – [out] Vector of length n of eigenvalues

  • n – Number of rows/columns

Returns

An error code: 0 - success, otherwise - failure

int CeedSimultaneousDiagonalization(Ceed ceed, CeedScalar *mat_A, CeedScalar *mat_B, CeedScalar *mat_X, CeedScalar *lambda, CeedInt n)

Return Simultaneous Diagonalization of two matrices.

This solves the generalized eigenvalue problem A x = lambda B x, where A and B are symmetric and B is positive definite. We generate the matrix X and vector Lambda such that X^T A X = Lambda and X^T B X = I. This is equivalent to the LAPACK routine ‘sygv’ with TYPE = 1.

Utility Functions

Parameters

  • ceed – A Ceed context for error handling

  • mat_A – [in] Row-major matrix to be factorized with eigenvalues

  • mat_B – [in] Row-major matrix to be factorized to identity

  • mat_X – [out] Row-major orthogonal matrix

  • lambda – [out] Vector of length n of generalized eigenvalues

  • n – Number of rows/columns

Returns

An error code: 0 - success, otherwise - failure

Typedefs and Enumerations

enum CeedTransposeMode

Denotes whether a linear transformation or its transpose should be applied.

Values:

enumerator CEED_NOTRANSPOSE

Apply the linear transformation.

enumerator CEED_TRANSPOSE

Apply the transpose.

enum CeedEvalMode

Basis evaluation mode.

Modes can be bitwise ORed when passing to most functions.

Values:

enumerator CEED_EVAL_NONE

Perform no evaluation (either because there is no data or it is already at quadrature points)

enumerator CEED_EVAL_INTERP

Interpolate from nodes to quadrature points.

enumerator CEED_EVAL_GRAD

Evaluate gradients at quadrature points from input in a nodal basis.

enumerator CEED_EVAL_DIV

Evaluate divergence at quadrature points from input in a nodal basis.

enumerator CEED_EVAL_CURL

Evaluate curl at quadrature points from input in a nodal basis.

enumerator CEED_EVAL_WEIGHT

Using no input, evaluate quadrature weights on the reference element.

enum CeedQuadMode

Type of quadrature; also used for location of nodes.

Values:

enumerator CEED_GAUSS

Gauss-Legendre quadrature.

enumerator CEED_GAUSS_LOBATTO

Gauss-Legendre-Lobatto quadrature.

enum CeedElemTopology

Type of basis shape to create non-tensor H1 element basis.

Dimension can be extracted with bitwise AND (CeedElemTopology & 2**(dim + 2)) == TRUE

Values:

enumerator CEED_LINE

Line.

enumerator CEED_TRIANGLE

Triangle - 2D shape.

enumerator CEED_QUAD

Quadralateral - 2D shape.

enumerator CEED_TET

Tetrahedron - 3D shape.

enumerator CEED_PYRAMID

Pyramid - 3D shape.

enumerator CEED_PRISM

Prism - 3D shape.

enumerator CEED_HEX

Hexehedron - 3D shape.