CeedBasis

int CeedBasisCreateH1Fallback(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)

Fallback to a reference implementation for a non tensor-product basis for \(H^1\) discretizations.

This function may only be called inside of a backend BasisCreateH1 function. This is used by a backend when the specific parameters for a CeedBasis exceed the backend’s support, such as when a interp and grad matrices require too many bytes to fit into shared memory on a GPU.

User Functions

Parameters:

  • ceed – [in] Ceed object used to create the CeedBasis

  • topo – [in] Topology of element, e.g. hypercube, simplex, etc

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

  • num_nodes – [in] Total number of nodes

  • num_qpts – [in] Total number of quadrature points

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

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

  • q_ref – [in] Array of length num_qpts * dim holding the locations of quadrature points on the reference element

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

  • basis – [out] Newly created CeedBasis

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisGetCollocatedGrad(CeedBasis basis, CeedScalar *collo_grad_1d)

Return collocated gradient matrix.

Backend Developer Functions

Parameters:

  • basis – [in] CeedBasis

  • collo_grad_1d – [out] Row-major (Q_1d * Q_1d) matrix expressing derivatives of basis functions at quadrature points

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisGetChebyshevInterp1D(CeedBasis basis, CeedScalar *chebyshev_interp_1d)

Return 1D interpolation matrix to Chebyshev polynomial coefficients on quadrature space.

Backend Developer Functions

Parameters:

  • basis – [in] CeedBasis

  • chebyshev_interp_1d – [out] Row-major (P_1d * Q_1d) matrix interpolating from basis nodes to Chebyshev polynomial coefficients

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisIsTensor(CeedBasis basis, bool *is_tensor)

Get tensor status for given CeedBasis

Backend Developer Functions

Parameters:

  • basis – [in] CeedBasis

  • is_tensor – [out] Variable to store tensor status

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisIsCollocated(CeedBasis basis, bool *is_collocated)

Determine if given CeedBasis has nodes collocated with quadrature points.

Backend Developer Functions

Parameters:

  • basis – [in] CeedBasis

  • is_collocated – [out] Variable to store collocated status

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisGetData(CeedBasis basis, void *data)

Get backend data of a CeedBasis

Backend Developer Functions

Parameters:

  • basis – [in] CeedBasis

  • data – [out] Variable to store data

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisSetData(CeedBasis basis, void *data)

Set backend data of a CeedBasis

Backend Developer Functions

Parameters:

  • basis – [inout] CeedBasis

  • data – [in] Data to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisReference(CeedBasis basis)

Increment the reference counter for a CeedBasis

Backend Developer Functions

Parameters:

  • basis – [inout] CeedBasis to increment the reference counter

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisGetNumQuadratureComponents(CeedBasis basis, CeedEvalMode eval_mode, CeedInt *q_comp)

Get number of Q-vector components for given CeedBasis

Backend Developer Functions

Parameters:
Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisGetFlopsEstimate(CeedBasis basis, CeedTransposeMode t_mode, CeedEvalMode eval_mode, bool is_at_points, CeedInt num_points, CeedSize *flops)

Estimate number of FLOPs required to apply CeedBasis in t_mode and eval_mode

Backend Developer Functions

Parameters:

  • basis – [in] CeedBasis to estimate FLOPs for

  • t_mode – [in] Apply basis or transpose

  • eval_mode – [in] CeedEvalMode

  • is_at_points – [in] Evaluate the basis at points or quadrature points

  • num_points – [in] Number of points basis is evaluated at

  • flops – [out] Address of variable to hold FLOPs estimate

int CeedBasisGetFESpace(CeedBasis basis, CeedFESpace *fe_space)

Get CeedFESpace for a CeedBasis

Backend Developer Functions

Parameters:

  • basis – [in] CeedBasis

  • fe_space – [out] Variable to store CeedFESpace

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisGetTopologyDimension(CeedElemTopology topo, CeedInt *dim)

Get dimension for given CeedElemTopology

Backend Developer Functions

Parameters:

  • topo – [in] CeedElemTopology

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

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisGetTensorContract(CeedBasis basis, CeedTensorContract *contract)

Get CeedTensorContract of a CeedBasis

Backend Developer Functions

Parameters:

  • basis – [in] CeedBasis

  • contract – [out] Variable to store CeedTensorContract

Returns:

An error code: 0 - success, otherwise - failure

int CeedBasisSetTensorContract(CeedBasis basis, CeedTensorContract contract)

Set CeedTensorContract of a CeedBasis

Backend Developer Functions

Parameters:

  • basis – [inout] CeedBasis

  • contract – [in] CeedTensorContract to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedMatrixMatrixMultiply(Ceed ceed, const CeedScalar *mat_A, const CeedScalar *mat_B, CeedScalar *mat_C, CeedInt m, CeedInt n, CeedInt kk)

Return a reference implementation of matrix multiplication \(C = A B\).

Note: This is a reference implementation for CPU CeedScalar pointers that is not intended for high performance.

Utility Functions

Parameters:

  • ceed – [in] Ceed context for error handling

  • mat_A – [in] Row-major matrix A

  • mat_B – [in] Row-major matrix B

  • mat_C – [out] Row-major output matrix C

  • m – [in] Number of rows of C

  • n – [in] Number of columns of C

  • kk – [in] Number of columns of A/rows of B

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 – [in] 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 – [in] Number of rows

  • n – [in] Number of columns

Returns:

An error code: 0 - success, otherwise - failure

int CeedHouseholderApplyQ(CeedScalar *mat_A, const CeedScalar *mat_Q, const CeedScalar *tau, CeedTransposeMode t_mode, CeedInt m, CeedInt n, CeedInt k, CeedInt row, CeedInt col)

Apply Householder Q matrix.

Compute mat_A = mat_Q mat_A, where mat_Q is \(m \times m\) and mat_A is \(m \times n\).

Utility Functions

Parameters:

  • mat_A – [inout] Matrix to apply Householder Q to, in place

  • mat_Q – [in] Householder Q matrix

  • tau – [in] Householder scaling factors

  • t_mode – [in] Transpose mode for application

  • m – [in] Number of rows in A

  • n – [in] Number of columns in A

  • k – [in] Number of elementary reflectors in Q, k < m

  • row – [in] Row stride in A

  • col – [in] Col stride in A

Returns:

An error code: 0 - success, otherwise - failure

int CeedMatrixPseudoinverse(Ceed ceed, const CeedScalar *mat, CeedInt m, CeedInt n, CeedScalar *mat_pinv)

Return pseudoinverse of a matrix.

Utility Functions

Parameters:

  • ceed – [in] Ceed context for error handling

  • mat – [in] Row-major matrix to compute pseudoinverse of

  • m – [in] Number of rows

  • n – [in] Number of columns

  • mat_pinv – [out] Row-major pseudoinverse matrix

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 – [in] Ceed context for error handling

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

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

  • n – [in] 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 – [in] 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 – [in] Number of rows/columns

Returns:

An error code: 0 - success, otherwise - failure

int CeedTensorContractCreate(Ceed ceed, CeedTensorContract *contract)

Create a CeedTensorContract object for a CeedBasis

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed object used to create the CeedTensorContract

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

Returns:

An error code: 0 - success, otherwise - failure

int CeedTensorContractApply(CeedTensorContract contract, CeedInt A, CeedInt B, CeedInt C, CeedInt J, const CeedScalar *restrict t, CeedTransposeMode t_mode, const CeedInt add, const CeedScalar *restrict u, CeedScalar *restrict v)

Apply tensor contraction.

Contracts on the middle index NOTRANSPOSE: v_ajc = t_jb u_abc TRANSPOSE: v_ajc = t_bj u_abc If add != 0, = is replaced by +=

Backend Developer Functions

Parameters:

  • contract – [in] CeedTensorContract to use

  • A – [in] First index of u, v

  • B – [in] Middle index of u, one index of t

  • C – [in] Last index of u, v

  • J – [in] Middle index of v, one index of t

  • t – [in] Tensor array to contract against

  • t_mode – [in] Transpose mode for t, CEED_NOTRANSPOSE for t_jb CEED_TRANSPOSE for t_bj

  • add – [in] Add mode

  • u – [in] Input array

  • v – [out] Output array

Returns:

An error code: 0 - success, otherwise - failure

int CeedTensorContractStridedApply(CeedTensorContract contract, CeedInt A, CeedInt B, CeedInt C, CeedInt D, CeedInt J, const CeedScalar *restrict t, CeedTransposeMode t_mode, const CeedInt add, const CeedScalar *restrict u, CeedScalar *restrict v)

Apply tensor contraction.

Contracts on the middle index NOTRANSPOSE: v_dajc = t_djb u_abc TRANSPOSE: v_ajc = t_dbj u_dabc If add != 0, = is replaced by +=

Backend Developer Functions

Parameters:

  • contract – [in] CeedTensorContract to use

  • A – [in] First index of u, second index of v

  • B – [in] Middle index of u, one of last two indices of t

  • C – [in] Last index of u, v

  • D – [in] First index of v, first index of t

  • J – [in] Third index of v, one of last two indices of t

  • t – [in] Tensor array to contract against

  • t_mode – [in] Transpose mode for t, CEED_NOTRANSPOSE for t_djb CEED_TRANSPOSE for t_dbj

  • add – [in] Add mode

  • u – [in] Input array

  • v – [out] Output array

Returns:

An error code: 0 - success, otherwise - failure

int CeedTensorContractGetCeed(CeedTensorContract contract, Ceed *ceed)

Get the Ceed associated with a CeedTensorContract

Backend Developer Functions

Parameters:

  • contract – [in] CeedTensorContract

  • ceed – [out] Variable to store Ceed

Returns:

An error code: 0 - success, otherwise - failure

Ceed CeedTensorContractReturnCeed(CeedTensorContract contract)

Return the Ceed associated with a CeedTensorContract

Backend Developer Functions

Parameters:

  • contract – [in] CeedTensorContract

Returns:

Ceed associated with contract

int CeedTensorContractGetData(CeedTensorContract contract, void *data)

Get backend data of a CeedTensorContract

Backend Developer Functions

Parameters:

  • contract – [in] CeedTensorContract

  • data – [out] Variable to store data

Returns:

An error code: 0 - success, otherwise - failure

int CeedTensorContractSetData(CeedTensorContract contract, void *data)

Set backend data of a CeedTensorContract

Backend Developer Functions

Parameters:

  • contract – [inout] CeedTensorContract

  • data – [in] Data to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedTensorContractReference(CeedTensorContract contract)

Increment the reference counter for a CeedTensorContract

Backend Developer Functions

Parameters:

  • contract – [inout] CeedTensorContract to increment the reference counter

Returns:

An error code: 0 - success, otherwise - failure

int CeedTensorContractReferenceCopy(CeedTensorContract tensor, CeedTensorContract *tensor_copy)

Copy the pointer to a CeedTensorContract.

Both pointers should be destroyed with CeedTensorContractDestroy().

Note: If the value of *tensor_copy passed to this function is non-NULL, then it is assumed that *tensor_copy is a pointer to a CeedTensorContract. This CeedTensorContract will be destroyed if *tensor_copy is the only reference to this CeedTensorContract.

User Functions

Parameters:

  • tensor – [in] CeedTensorContract to copy reference to

  • tensor_copy – [inout] Variable to store copied reference

Returns:

An error code: 0 - success, otherwise - failure

int CeedTensorContractDestroy(CeedTensorContract *contract)

Destroy a CeedTensorContract

Backend Developer Functions

Parameters:

  • contract – [inout] CeedTensorContract to destroy

Returns:

An error code: 0 - success, otherwise - failure