CeedOperator¶
A CeedOperator defines the finite/spectral element operator associated to a CeedQFunction. A CeedOperator connects objects of the type CeedElemRestriction, CeedBasis, and CeedQFunction.
Discrete operators on user vectors¶
-
typedef struct CeedOperator_private *
CeedOperator
¶ Handle for object describing FE-type operators acting on vectors.
Given an element restriction \(E\), basis evaluator \(B\), and quadrature function \(f\), a CeedOperator expresses operations of the form $$ E^T B^T f(B E u) $$ acting on the vector \(u\).
-
int
CeedOperatorCreate
(Ceed ceed, CeedQFunction qf, CeedQFunction dqf, CeedQFunction dqfT, CeedOperator *op)¶ Create a CeedOperator and associate a CeedQFunction.
A CeedBasis and CeedElemRestriction can be associated with CeedQFunction fields with CeedOperatorSetField.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ceed
: A Ceed object where the CeedOperator will be createdqf
: QFunction defining the action of the operator at quadrature pointsdqf
: QFunction defining the action of the Jacobian of qf (or CEED_QFUNCTION_NONE)dqfT
: QFunction defining the action of the transpose of the Jacobian of qf (or CEED_QFUNCTION_NONE)[out] op
: Address of the variable where the newly created CeedOperator will be stored
-
int
CeedCompositeOperatorCreate
(Ceed ceed, CeedOperator *op)¶ Create an operator that composes the action of several operators.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ceed
: A Ceed object where the CeedOperator will be created[out] op
: Address of the variable where the newly created Composite CeedOperator will be stored
-
int
CeedOperatorSetField
(CeedOperator op, const char *fieldname, CeedElemRestriction r, CeedBasis b, CeedVector v)¶ Provide a field to a CeedOperator for use by its CeedQFunction.
This function is used to specify both active and passive fields to a CeedOperator. For passive fields, a vector
v must be provided. Passive fields can inputs or outputs (updated in-place when operator is applied).
Active fields must be specified using this function, but their data (in a CeedVector) is passed in
CeedOperatorApply(). There can be at most one active input and at most one active output.User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator on which to provide the fieldfieldname
: Name of the field (to be matched with the name used by CeedQFunction)r
: CeedElemRestrictionb
: CeedBasis in which the field resides or CEED_BASIS_COLLOCATED if collocated with quadrature pointsv
: CeedVector to be used by CeedOperator or CEED_VECTOR_ACTIVE if field is active or CEED_VECTOR_NONE if using CEED_EVAL_WEIGHT in the QFunction
-
int
CeedCompositeOperatorAddSub
(CeedOperator compositeop, CeedOperator subop)¶ Add a sub-operator to a composite CeedOperator.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
[out] compositeop
: Composite CeedOperatorsubop
: Sub-operator CeedOperator
-
int
CeedOperatorLinearAssembleQFunction
(CeedOperator op, CeedVector *assembled, CeedElemRestriction *rstr, CeedRequest *request)¶ Assemble a linear CeedQFunction associated with a CeedOperator.
This returns a CeedVector containing a matrix at each quadrature point providing the action of the CeedQFunction associated with the CeedOperator. The vector ‘assembled’ is of shape [num_elements, num_input_fields, num_output_fields, num_quad_points] and contains column-major matrices representing the action of the CeedQFunction for a corresponding quadrature point on an element. Inputs and outputs are in the order provided by the user when adding CeedOperator fields. For example, a CeedQFunction with inputs ‘u’ and ‘gradu’ and outputs ‘gradv’ and ‘v’, provided in that order, would result in an assembled QFunction that consists of (1 + dim) x (dim + 1) matrices at each quadrature point acting on the input [u, du_0, du_1] and producing the output [dv_0, dv_1, v].
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to assemble CeedQFunction[out] assembled
: CeedVector to store assembled CeedQFunction at quadrature points[out] rstr
: CeedElemRestriction for CeedVector containing assembled CeedQFunctionrequest
: Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE
-
int
CeedOperatorLinearAssembleDiagonal
(CeedOperator op, CeedVector assembled, CeedRequest *request)¶ Assemble the diagonal of a square linear CeedOperator.
This overwrites a CeedVector with the diagonal of a linear CeedOperator.
Note: Currently only non-composite CeedOperators with a single field and composite CeedOperators with single field sub-operators are supported.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to assemble CeedQFunction[out] assembled
: CeedVector to store assembled CeedOperator diagonalrequest
: Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE
-
int
CeedOperatorLinearAssembleAddDiagonal
(CeedOperator op, CeedVector assembled, CeedRequest *request)¶ Assemble the diagonal of a square linear CeedOperator.
This sums into a CeedVector the diagonal of a linear CeedOperator.
Note: Currently only non-composite CeedOperators with a single field and composite CeedOperators with single field sub-operators are supported.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to assemble CeedQFunction[out] assembled
: CeedVector to store assembled CeedOperator diagonalrequest
: Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE
-
int
CeedOperatorLinearAssemblePointBlockDiagonal
(CeedOperator op, CeedVector assembled, CeedRequest *request)¶ Assemble the point block diagonal of a square linear CeedOperator.
This overwrites a CeedVector with the point block diagonal of a linear CeedOperator.
Note: Currently only non-composite CeedOperators with a single field and composite CeedOperators with single field sub-operators are supported.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to assemble CeedQFunction[out] assembled
: CeedVector to store assembled CeedOperator point block diagonal, provided in row-major form with an ncomp * ncomp block at each node. The dimensions of this vector are derived from the active vector for the CeedOperator. The array has shape [nodes, component out, component in].request
: Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE
-
int
CeedOperatorLinearAssembleAddPointBlockDiagonal
(CeedOperator op, CeedVector assembled, CeedRequest *request)¶ Assemble the point block diagonal of a square linear CeedOperator.
This sums into a CeedVector with the point block diagonal of a linear CeedOperator.
Note: Currently only non-composite CeedOperators with a single field and composite CeedOperators with single field sub-operators are supported.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to assemble CeedQFunction[out] assembled
: CeedVector to store assembled CeedOperator point block diagonal, provided in row-major form with an ncomp * ncomp block at each node. The dimensions of this vector are derived from the active vector for the CeedOperator. The array has shape [nodes, component out, component in].request
: Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE
-
int
CeedOperatorMultigridLevelCreate
(CeedOperator opFine, CeedVector PMultFine, CeedElemRestriction rstrCoarse, CeedBasis basisCoarse, CeedOperator *opCoarse, CeedOperator *opProlong, CeedOperator *opRestrict)¶ Create a multigrid coarse operator and level transfer operators for a CeedOperator, creating the prolongation basis from the fine and coarse grid interpolation.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
[in] opFine
: Fine grid operator[in] PMultFine
: L-vector multiplicity in parallel gather/scatter[in] rstrCoarse
: Coarse grid restriction[in] basisCoarse
: Coarse grid active vector basis[out] opCoarse
: Coarse grid operator[out] opProlong
: Coarse to fine operator[out] opRestrict
: Fine to coarse operator
-
int
CeedOperatorMultigridLevelCreateTensorH1
(CeedOperator opFine, CeedVector PMultFine, CeedElemRestriction rstrCoarse, CeedBasis basisCoarse, const CeedScalar *interpCtoF, CeedOperator *opCoarse, CeedOperator *opProlong, CeedOperator *opRestrict)¶ Create a multigrid coarse operator and level transfer operators for a CeedOperator with a tensor basis for the active basis.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
[in] opFine
: Fine grid operator[in] PMultFine
: L-vector multiplicity in parallel gather/scatter[in] rstrCoarse
: Coarse grid restriction[in] basisCoarse
: Coarse grid active vector basis[in] interpCtoF
: Matrix for coarse to fine interpolation[out] opCoarse
: Coarse grid operator[out] opProlong
: Coarse to fine operator[out] opRestrict
: Fine to coarse operator
-
int
CeedOperatorMultigridLevelCreateH1
(CeedOperator opFine, CeedVector PMultFine, CeedElemRestriction rstrCoarse, CeedBasis basisCoarse, const CeedScalar *interpCtoF, CeedOperator *opCoarse, CeedOperator *opProlong, CeedOperator *opRestrict)¶ Create a multigrid coarse operator and level transfer operators for a CeedOperator with a non-tensor basis for the active vector.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
[in] opFine
: Fine grid operator[in] PMultFine
: L-vector multiplicity in parallel gather/scatter[in] rstrCoarse
: Coarse grid restriction[in] basisCoarse
: Coarse grid active vector basis[in] interpCtoF
: Matrix for coarse to fine interpolation[out] opCoarse
: Coarse grid operator[out] opProlong
: Coarse to fine operator[out] opRestrict
: Fine to coarse operator
-
int
CeedOperatorCreateFDMElementInverse
(CeedOperator op, CeedOperator *fdminv, CeedRequest *request)¶ Build a FDM based approximate inverse for each element for a CeedOperator.
This returns a CeedOperator and CeedVector to apply a Fast Diagonalization Method based approximate inverse. This function obtains the simultaneous diagonalization for the 1D mass and Laplacian operators, M = V^T V, K = V^T S V. The assembled QFunction is used to modify the eigenvalues from simultaneous diagonalization and obtain an approximate inverse of the form V^T S^hat V. The CeedOperator must be linear and non-composite. The associated CeedQFunction must therefore also be linear.
Backend Developer Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to create element inverses[out] fdminv
: CeedOperator to apply the action of a FDM based inverse for each elementrequest
: Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE
-
int
CeedOperatorView
(CeedOperator op, FILE *stream)¶ View a CeedOperator.
User Functions
- Return
Error code: 0 - success, otherwise - failure
- Parameters
[in] op
: CeedOperator to view[in] stream
: Stream to write; typically stdout/stderr or a file
-
int
CeedOperatorApply
(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request)¶ Apply CeedOperator to a vector.
This computes the action of the operator on the specified (active) input, yielding its (active) output. All inputs and outputs must be specified using CeedOperatorSetField().
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to apply[in] in
: CeedVector containing input state or CEED_VECTOR_NONE if there are no active inputs[out] out
: CeedVector to store result of applying operator (must be distinct from in) or CEED_VECTOR_NONE if there are no active outputsrequest
: Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE
-
int
CeedOperatorApplyAdd
(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request)¶ Apply CeedOperator to a vector and add result to output vector.
This computes the action of the operator on the specified (active) input, yielding its (active) output. All inputs and outputs must be specified using CeedOperatorSetField().
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to apply[in] in
: CeedVector containing input state or NULL if there are no active inputs[out] out
: CeedVector to sum in result of applying operator (must be distinct from in) or NULL if there are no active outputsrequest
: Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE
-
int
CeedOperatorDestroy
(CeedOperator *op)¶ Destroy a CeedOperator.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
op
: CeedOperator to destroy