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

Parameters:

ceed – [in] Ceed object used to create the CeedOperator
qf – [in] CeedQFunction defining the action of the operator at quadrature points
dqf – [in] CeedQFunction defining the action of the Jacobian of qf (or CEED_QFUNCTION_NONE)
dqfT – [in] CeedQFunction defining the action of the transpose of the Jacobian of qf (or CEED_QFUNCTION_NONE)
op – [out] Address of the variable where the newly created CeedOperator will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCreateAtPoints(Ceed ceed, CeedQFunction qf, CeedQFunction dqf, CeedQFunction dqfT, CeedOperator *op)

Create a CeedOperator for evaluation at evaluation at arbitrary points in each element.

A CeedBasis and CeedElemRestriction can be associated with CeedQFunction fields with CeedOperator SetField. The locations of each point are set with CeedOperatorAtPointsSetPoints().

User Functions

Parameters:

ceed – [in] Ceed object used to create the CeedOperator
qf – [in] CeedQFunction defining the action of the operator at quadrature points
dqf – [in] CeedQFunction defining the action of the Jacobian of qf (or CEED_QFUNCTION_NONE)
dqfT – [in] CeedQFunction defining the action of the transpose of the Jacobian of qf (or CEED_QFUNCTION_NONE)
op – [out] Address of the variable where the newly created CeedOperator will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCreateComposite(Ceed ceed, CeedOperator *op)

Create a composite CeedOperator that composes the action of several CeedOperator

User Functions

Parameters:

ceed – [in] Ceed object used to create the CeedOperator
op – [out] Address of the variable where the newly created composite CeedOperator will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorReferenceCopy(CeedOperator op, CeedOperator *op_copy)

Copy the pointer to a CeedOperator.

Both pointers should be destroyed with CeedOperatorDestroy().

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

User Functions

Parameters:

op – [in] CeedOperator to copy reference to
op_copy – [inout] Variable to store copied reference

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorSetField(CeedOperator op, const char *field_name, CeedElemRestriction rstr, CeedBasis basis, CeedVector vec)

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 CeedVector vec 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 CeedVector and at most one active outputCeedVector: storing and manipulating vectors passed to CeedOperatorApply().

The number of quadrature points must agree across all points. When using CEED_BASIS_NONE, the number of quadrature points is determined by the element size of rstr.

User Functions

Parameters:

op – [inout] CeedOperator on which to provide the field
field_name – [in] Name of the field (to be matched with the name used by CeedQFunction)
rstr – [in] CeedElemRestriction
basis – [in] CeedBasis in which the field resides or CEED_BASIS_NONE if collocated with quadrature points
vec – [in] 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 CeedQFunction

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetFields(CeedOperator op, CeedInt *num_input_fields, CeedOperatorField **input_fields, CeedInt *num_output_fields, CeedOperatorField **output_fields)

Get the CeedOperator Field of a CeedOperator.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

Advanced Functions

Parameters:

op – [in] CeedOperator
num_input_fields – [out] Variable to store number of input fields
input_fields – [out] Variable to store input fields
num_output_fields – [out] Variable to store number of output fields
output_fields – [out] Variable to store output fields

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorAtPointsSetPoints(CeedOperator op, CeedElemRestriction rstr_points, CeedVector point_coords)

Set the arbitrary points in each element for a CeedOperator at points.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

Advanced Functions

Parameters:

op – [inout] CeedOperator at points
rstr_points – [in] CeedElemRestriction for the coordinates of each point by element
point_coords – [in] CeedVector holding coordinates of each point

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorIsAtPoints(CeedOperator op, bool *is_at_points)

Get a boolean value indicating if the CeedOperator was created with CeedOperatorCreateAtPoints

User Functions

Parameters:

op – [in] CeedOperator
is_at_points – [out] Variable to store at points status

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorAtPointsGetPoints(CeedOperator op, CeedElemRestriction *rstr_points, CeedVector *point_coords)

Get the arbitrary points in each element for a CeedOperator at points.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

Advanced Functions

Parameters:

op – [in] CeedOperator at points
rstr_points – [out] Variable to hold CeedElemRestriction for the coordinates of each point by element
point_coords – [out] Variable to hold CeedVector holding coordinates of each point

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetFieldByName(CeedOperator op, const char *field_name, CeedOperatorField *op_field)

Get a CeedOperator Field of a CeedOperator from its name.

op_field is set to NULL if the field is not found.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

Advanced Functions

Parameters:

op – [in] CeedOperator
field_name – [in] Name of desired CeedOperator Field
op_field – [out] CeedOperator Field corresponding to the name

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorFieldGetName(CeedOperatorField op_field, const char **field_name)

Get the name of a CeedOperator Field.

Advanced Functions

Parameters:

op_field – [in] CeedOperator Field
field_name – [out] Variable to store the field name

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorFieldGetElemRestriction(CeedOperatorField op_field, CeedElemRestriction *rstr)

Get the CeedElemRestriction of a CeedOperator Field.

Note: Caller is responsible for destroying the rstr with CeedElemRestrictionDestroy().

Advanced Functions

Parameters:

op_field – [in] CeedOperator Field
rstr – [out] Variable to store CeedElemRestriction

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorFieldGetBasis(CeedOperatorField op_field, CeedBasis *basis)

Get the CeedBasis of a CeedOperator Field.

Note: Caller is responsible for destroying the basis with CeedBasisDestroy().

Advanced Functions

Parameters:

op_field – [in] CeedOperator Field
basis – [out] Variable to store CeedBasis

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorFieldGetVector(CeedOperatorField op_field, CeedVector *vec)

Get the CeedVector of a CeedOperator Field.

Note: Caller is responsible for destroying the vec with CeedVectorDestroy().

Advanced Functions

Parameters:

op_field – [in] CeedOperator Field
vec – [out] Variable to store CeedVector

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorFieldGetData(CeedOperatorField op_field, const char **field_name, CeedElemRestriction *rstr, CeedBasis *basis, CeedVector *vec)

Get the data of a CeedOperator Field.

Any arguments set as NULL are ignored..

Note: Caller is responsible for destroying the rstr, basis, and vec.

Advanced Functions

Parameters:

op_field – [in] CeedOperator Field
field_name – [out] Variable to store the field name
rstr – [out] Variable to store CeedElemRestriction
basis – [out] Variable to store CeedBasis
vec – [out] Variable to store CeedVector

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCompositeAddSub(CeedOperator composite_op, CeedOperator sub_op)

Add a sub-operator to a composite CeedOperator

User Functions

Parameters:

composite_op – [inout] Composite CeedOperator
sub_op – [in] Sub-operator CeedOperator

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCompositeGetNumSub(CeedOperator op, CeedInt *num_suboperators)

Get the number of sub-operators associated with a CeedOperator

Backend Developer Functions

Parameters:

op – [in] CeedOperator
num_suboperators – [out] Variable to store number of sub-operators

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCompositeGetSubList(CeedOperator op, CeedOperator **sub_operators)

Get the list of sub-operators associated with a CeedOperator

Backend Developer Functions

Parameters:

op – [in] CeedOperator
sub_operators – [out] Variable to store list of sub-operators

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCompositeGetSubByName(CeedOperator op, const char *op_name, CeedOperator *sub_op)

Get a sub CeedOperator of a composite CeedOperator from its name.

sub_op is set to NULL if the sub operator is not found.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

Advanced Functions

Parameters:

op – [in] Composite CeedOperator
op_name – [in] Name of desired sub CeedOperator
sub_op – [out] Sub CeedOperator corresponding to the name

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCompositeSetSequential(CeedOperator op, bool is_sequential)

Set whether the sub-operators of the composite CeedOperator must be run sequentially.

Note: This value currently only affects the GPU /gpu/cuda/gen and /gpu/hip/gen backends.

Advanced Functions

Parameters:

op – [in] Composite CeedOperator
is_sequential – [in] Flag value to set, if true, forces the composite CeedOperator to execute sequentially

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCompositeIsSequential(CeedOperator op, bool *is_sequential)

Get whether the sub-operators of the composite CeedOperator must be run sequentially.

Note: This value currently only affects the GPU /gpu/cuda/gen and /gpu/hip/gen backends.

Advanced Functions

Parameters:

op – [in] Composite CeedOperator
is_sequential – [out] Variable to store sequential status

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCheckReady(CeedOperator op)

Check if a CeedOperator is ready to be used.

User Functions

Parameters:

op – [in] CeedOperator to check

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetActiveVectorLengths(CeedOperator op, CeedSize *input_size, CeedSize *output_size)

Get vector lengths for the active input and/or output CeedVector of a CeedOperator.

Note: Lengths of -1 indicate that the CeedOperator does not have an active input and/or output.

User Functions

Parameters:

op – [in] CeedOperator
input_size – [out] Variable to store active input vector length, or NULL
output_size – [out] Variable to store active output vector length, or NULL

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorSetQFunctionAssemblyReuse(CeedOperator op, bool reuse_assembly_data)

Set reuse of CeedQFunction data in CeedOperatorLinearAssemble*() functions.

When reuse_assembly_data = false (default), the CeedQFunction associated with this CeedOperator is re-assembled every time a CeedOperatorLinearAssemble*() function is called. When reuse_assembly_data = true, the CeedQFunction associated with this CeedOperator is reused between calls to CeedOperatorSetQFunctionAssemblyDataUpdateNeeded().

Advanced Functions

Parameters:

op – [in] CeedOperator
reuse_assembly_data – [in] Boolean flag setting assembly data reuse

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorSetQFunctionAssemblyDataUpdateNeeded(CeedOperator op, bool needs_data_update)

Mark CeedQFunction data as updated and the CeedQFunction as requiring re-assembly.

Advanced Functions

Parameters:

op – [in] CeedOperator
needs_data_update – [in] Boolean flag setting assembly data reuse

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorSetName(CeedOperator op, const char *name)

Set name of CeedOperator for CeedOperatorView() output.

User Functions

Parameters:

op – [inout] CeedOperator
name – [in] Name to set, or NULL to remove previously set name

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetName(CeedOperator op, const char **name)

Get name of CeedOperator

User Functions

Parameters:

op – [in] CeedOperator
name – [inout] Address of variable to hold currently set name

Returns:

An error code: 0 - success, otherwise - failure

static int CeedOperatorView_Core(CeedOperator op, FILE *stream, bool is_full)

Core logic for viewing a CeedOperator

Library Developer Functions

Parameters:

op – [in] CeedOperator to view brief summary
stream – [in] Stream to write; typically stdout or a file
is_full – [in] Whether to write full operator view or terse

Returns:

Error code: 0 - success, otherwise - failure

int CeedOperatorSetNumViewTabs(CeedOperator op, CeedInt num_tabs)

Set the number of tabs to indent for CeedOperatorView() output.

User Functions

Parameters:

op – [in] CeedOperator to set the number of view tabs
num_tabs – [in] Number of view tabs to set

Returns:

Error code: 0 - success, otherwise - failure

int CeedOperatorGetNumViewTabs(CeedOperator op, CeedInt *num_tabs)

Get the number of tabs to indent for CeedOperatorView() output.

User Functions

Parameters:

op – [in] CeedOperator to get the number of view tabs
num_tabs – [out] Number of view tabs

Returns:

Error code: 0 - success, otherwise - failure

int CeedOperatorView(CeedOperator op, FILE *stream)

View a CeedOperator

User Functions

Parameters:

op – [in] CeedOperator to view
stream – [in] Stream to write; typically stdout or a file

Returns:

Error code: 0 - success, otherwise - failure

int CeedOperatorViewTerse(CeedOperator op, FILE *stream)

View a brief summary CeedOperator

User Functions

Parameters:

op – [in] CeedOperator to view brief summary
stream – [in] Stream to write; typically stdout or a file

Returns:

Error code: 0 - success, otherwise - failure

int CeedOperatorGetCeed(CeedOperator op, Ceed *ceed)

Get the Ceed associated with a CeedOperator

Advanced Functions

Parameters:

op – [in] CeedOperator
ceed – [out] Variable to store Ceed

Returns:

An error code: 0 - success, otherwise - failure

Ceed CeedOperatorReturnCeed(CeedOperator op)

Return the Ceed associated with a CeedOperator

Advanced Functions

Parameters:

op – [in] CeedOperator

Returns:

Ceed associated with the op

int CeedOperatorGetNumElements(CeedOperator op, CeedInt *num_elem)

Get the number of elements associated with a CeedOperator

Advanced Functions

Parameters:

op – [in] CeedOperator
num_elem – [out] Variable to store number of elements

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetNumQuadraturePoints(CeedOperator op, CeedInt *num_qpts)

Get the number of quadrature points associated with a CeedOperator

Advanced Functions

Parameters:

op – [in] CeedOperator
num_qpts – [out] Variable to store vector number of quadrature points

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetFlopsEstimate(CeedOperator op, CeedSize *flops)

Estimate number of FLOPs required to apply CeedOperator on the active CeedVector

Backend Developer Functions

Parameters:

op – [in] CeedOperator to estimate FLOPs for
flops – [out] Address of variable to hold FLOPs estimate

int CeedOperatorGetContext(CeedOperator op, CeedQFunctionContext *ctx)

Get CeedQFunction global context for a CeedOperator.

The caller is responsible for destroying ctx returned from this function via CeedQFunctionContextDestroy().

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

Advanced Functions

Parameters:

op – [in] CeedOperator
ctx – [out] Variable to store CeedQFunctionContext

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetContextFieldLabel(CeedOperator op, const char *field_name, CeedContextFieldLabel *field_label)

Get label for a registered CeedQFunctionContext field, or NULL if no field has been registered with this field_name.

Fields are registered via CeedQFunctionContextRegister*() functions (eg. CeedQFunctionContextRegisterDouble()).

User Functions

Parameters:

op – [in] CeedOperator
field_name – [in] Name of field to retrieve label
field_label – [out] Variable to field label

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorSetContextDouble(CeedOperator op, CeedContextFieldLabel field_label, double *values)

Set CeedQFunctionContext field holding double precision values.

For composite operators, the values are set in all sub-operator CeedQFunctionContext that have a matching field_name.

User Functions

Parameters:

op – [inout] CeedOperator
field_label – [in] Label of field to set
values – [in] Values to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetContextDoubleRead(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const double **values)

Get CeedQFunctionContext field holding double precision values, read-only.

For composite operators, the values correspond to the first sub-operator CeedQFunctionContext that has a matching field_name.

User Functions

Parameters:

op – [in] CeedOperator
field_label – [in] Label of field to get
num_values – [out] Number of values in the field label
values – [out] Pointer to context values

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorRestoreContextDoubleRead(CeedOperator op, CeedContextFieldLabel field_label, const double **values)

Restore CeedQFunctionContext field holding double precision values, read-only.

User Functions

Parameters:

op – [in] CeedOperator
field_label – [in] Label of field to restore
values – [out] Pointer to context values

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorSetContextInt32(CeedOperator op, CeedContextFieldLabel field_label, int32_t *values)

Set CeedQFunctionContext field holding int32 values.

For composite operators, the values are set in all sub-operator CeedQFunctionContext that have a matching field_name.

User Functions

Parameters:

op – [inout] CeedOperator
field_label – [in] Label of field to set
values – [in] Values to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetContextInt32Read(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const int32_t **values)

Get CeedQFunctionContext field holding int32 values, read-only.

For composite operators, the values correspond to the first sub-operator CeedQFunctionContext that has a matching field_name.

User Functions

Parameters:

op – [in] CeedOperator
field_label – [in] Label of field to get
num_values – [out] Number of int32 values in values
values – [out] Pointer to context values

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorRestoreContextInt32Read(CeedOperator op, CeedContextFieldLabel field_label, const int32_t **values)

Restore CeedQFunctionContext field holding int32 values, read-only.

User Functions

Parameters:

op – [in] CeedOperator
field_label – [in] Label of field to get
values – [out] Pointer to context values

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorSetContextBoolean(CeedOperator op, CeedContextFieldLabel field_label, bool *values)

Set CeedQFunctionContext field holding boolean values.

For composite operators, the values are set in all sub-operator CeedQFunctionContext that have a matching field_name.

User Functions

Parameters:

op – [inout] CeedOperator
field_label – [in] Label of field to set
values – [in] Values to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorGetContextBooleanRead(CeedOperator op, CeedContextFieldLabel field_label, size_t *num_values, const bool **values)

Get CeedQFunctionContext field holding boolean values, read-only.

For composite operators, the values correspond to the first sub-operator CeedQFunctionContext that has a matching field_name.

User Functions

Parameters:

op – [in] CeedOperator
field_label – [in] Label of field to get
num_values – [out] Number of boolean values in values
values – [out] Pointer to context values

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorRestoreContextBooleanRead(CeedOperator op, CeedContextFieldLabel field_label, const bool **values)

Restore CeedQFunctionContext field holding boolean values, read-only.

User Functions

Parameters:

op – [in] CeedOperator
field_label – [in] Label of field to get
values – [out] Pointer to context values

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorApply(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request)

Apply CeedOperator to a CeedVector.

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

Note

Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

Parameters:

op – [in] 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 outputs
request – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorApplyAdd(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request)

Apply CeedOperator to a CeedVector and add result to output CeedVector.

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

See also

CeedOperatorApplyAddActive()

Note

Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

Warning

This function adds into ALL outputs, including passive outputs. To only add into the active output, use CeedOperatorApplyAddActive().

Parameters:

op – [in] CeedOperator to apply
in – [in] CeedVector containing input state or CEED_VECTOR_NONE if there are no active inputs
out – [out] CeedVector to sum in result of applying operator (must be distinct from in) or CEED_VECTOR_NONE if there are no active outputs
request – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorApplyAddActive(CeedOperator op, CeedVector in, CeedVector out, CeedRequest *request)

Apply CeedOperator to a CeedVector and add result to output CeedVector.

Only sums into active outputs, overwrites passive outputs.

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

Note

Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

Parameters:

op – [in] CeedOperator to apply
in – [in] CeedVector containing input state or CEED_VECTOR_NONE if there are no active inputs
out – [out] CeedVector to sum in result of applying operator (must be distinct from in) or CEED_VECTOR_NONE if there are no active outputs
request – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorAssemblyDataStrip(CeedOperator op)

Destroy temporary assembly data associated with a CeedOperator

User Functions

Parameters:

op – [inout] CeedOperator whose assembly data to destroy

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorDestroy(CeedOperator *op)

Destroy a CeedOperator

User Functions

Parameters:

op – [inout] CeedOperator to destroy

Returns:

An error code: 0 - success, otherwise - failure

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 CeedQFunction 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].

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to assemble CeedQFunction
assembled – [out] CeedVector to store assembled CeedQFunction at quadrature points
rstr – [out] CeedElemRestriction for CeedVector containing assembled CeedQFunction
request – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorLinearAssembleQFunctionBuildOrUpdate(CeedOperator op, CeedVector *assembled, CeedElemRestriction *rstr, CeedRequest *request)

Assemble CeedQFunction and store result internally.

Return copied references of stored data to the caller. Caller is responsible for ownership and destruction of the copied references. See also CeedOperatorLinearAssembleQFunction().

Note: If the value of assembled or rstr passed to this function are non-NULL , then it is assumed that they hold valid pointers. These objects will be destroyed if *assembled or *rstr is the only reference to the object.

User Functions

Parameters:

op – [in] CeedOperator to assemble CeedQFunction
assembled – [out] CeedVector to store assembled CeedQFunction at quadrature points
rstr – [out] CeedElemRestriction for CeedVector containing assembled CeedQFunction
request – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

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 CeedOperator with a single field and composite CeedOperator with single field sub-operators are supported.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to assemble CeedQFunction
assembled – [out] CeedVector to store assembled CeedOperator diagonal
request – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

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 CeedOperator with a single field and composite CeedOperator with single field sub-operators are supported.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to assemble CeedQFunction
assembled – [out] CeedVector to store assembled CeedOperator diagonal
request – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorLinearAssemblePointBlockDiagonalSymbolic(CeedOperator op, CeedSize *num_entries, CeedInt **rows, CeedInt **cols)

Fully assemble the point-block diagonal pattern of a linear CeedOperator.

Expected to be used in conjunction with CeedOperatorLinearAssemblePointBlockDiagonal().

The assembly routines use coordinate format, with num_entries tuples of the form (i, j, value) which indicate that value should be added to the matrix in entry (i, j). Note that the (i, j) pairs are unique. This function returns the number of entries and their (i, j) locations, while CeedOperatorLinearAssemblePointBlockDiagonal() provides the values in the same ordering.

This will generally be slow unless your operator is low-order.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to assemble
num_entries – [out] Number of entries in coordinate nonzero pattern
rows – [out] Row number for each entry
cols – [out] Column number for each entry

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 CeedOperator with a single field and composite CeedOperator with single field sub-operators are supported.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to assemble CeedQFunction
assembled – [out] CeedVector to store assembled CeedOperator point block diagonal, provided in row-major form with an num_comp * num_comp 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 – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

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 CeedOperator with a single field and composite CeedOperator with single field sub-operators are supported.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to assemble CeedQFunction
assembled – [out] CeedVector to store assembled CeedOperator point block diagonal, provided in row-major form with an num_comp * num_comp 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 – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorLinearAssembleSymbolic(CeedOperator op, CeedSize *num_entries, CeedInt **rows, CeedInt **cols)

Fully assemble the nonzero pattern of a linear CeedOperator.

Expected to be used in conjunction with CeedOperatorLinearAssemble().

The assembly routines use coordinate format, with num_entries tuples of the form (i, j, value) which indicate that value should be added to the matrix in entry (i, j). Note that the (i, j) pairs are not unique and may repeat. This function returns the number of entries and their (i, j) locations, while CeedOperatorLinearAssemble() provides the values in the same ordering.

This will generally be slow unless your operator is low-order.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to assemble
num_entries – [out] Number of entries in coordinate nonzero pattern
rows – [out] Row number for each entry
cols – [out] Column number for each entry

int CeedOperatorLinearAssemble(CeedOperator op, CeedVector values)

Fully assemble the nonzero entries of a linear operator.

Expected to be used in conjunction with CeedOperatorLinearAssembleSymbolic().

The assembly routines use coordinate format, with num_entries tuples of the form (i, j, value) which indicate that value should be added to the matrix in entry (i, j). Note that the (i, j) pairs are not unique and may repeat. This function returns the values of the nonzero entries to be added, their (i, j) locations are provided by CeedOperatorLinearAssembleSymbolic().

This will generally be slow unless your operator is low-order.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to assemble
values – [out] Values to assemble into matrix

int CeedOperatorCompositeGetMultiplicity(CeedOperator op, CeedInt num_skip_indices, CeedInt *skip_indices, CeedVector mult)

Get the multiplicity of nodes across sub-operators in a composite CeedOperator.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] Composite CeedOperator
num_skip_indices – [in] Number of sub-operators to skip
skip_indices – [in] Array of indices of sub-operators to skip
mult – [out] Vector to store multiplicity (of size l_size )

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorMultigridLevelCreate(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse, CeedBasis basis_coarse, CeedOperator *op_coarse, CeedOperator *op_prolong, CeedOperator *op_restrict)

Create a multigrid coarse CeedOperator and level transfer CeedOperator for a CeedOperator, creating the prolongation basis from the fine and coarse grid interpolation.

Note: Calling this function asserts that setup is complete and sets all four CeedOperator as immutable.

User Functions

Parameters:

op_fine – [in] Fine grid CeedOperator
p_mult_fine – [in] L-vector multiplicity in parallel gather/scatter, or NULL if not creating prolongation/restriction CeedOperator
rstr_coarse – [in] Coarse grid CeedElemRestriction
basis_coarse – [in] Coarse grid active vector CeedBasis
op_coarse – [out] Coarse grid CeedOperator
op_prolong – [out] Coarse to fine CeedOperator, or NULL
op_restrict – [out] Fine to coarse CeedOperator, or NULL

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorMultigridLevelCreateTensorH1(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse, CeedBasis basis_coarse, const CeedScalar *interp_c_to_f, CeedOperator *op_coarse, CeedOperator *op_prolong, CeedOperator *op_restrict)

Create a multigrid coarse CeedOperator and level transfer CeedOperator for a CeedOperator with a tensor basis for the active basis.

Note: Calling this function asserts that setup is complete and sets all four CeedOperator as immutable.

User Functions

Parameters:

op_fine – [in] Fine grid CeedOperator
p_mult_fine – [in] L-vector multiplicity in parallel gather/scatter, or NULL if not creating prolongation/restriction CeedOperator
rstr_coarse – [in] Coarse grid CeedElemRestriction
basis_coarse – [in] Coarse grid active vector CeedBasis
interp_c_to_f – [in] Matrix for coarse to fine interpolation, or NULL if not creating prolongation/restriction CeedOperator
op_coarse – [out] Coarse grid CeedOperator
op_prolong – [out] Coarse to fine CeedOperator, or NULL
op_restrict – [out] Fine to coarse CeedOperator, or NULL

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorMultigridLevelCreateH1(CeedOperator op_fine, CeedVector p_mult_fine, CeedElemRestriction rstr_coarse, CeedBasis basis_coarse, const CeedScalar *interp_c_to_f, CeedOperator *op_coarse, CeedOperator *op_prolong, CeedOperator *op_restrict)

Create a multigrid coarse CeedOperator and level transfer CeedOperator for a CeedOperator with a non-tensor basis for the active vector.

Note: Calling this function asserts that setup is complete and sets all four CeedOperator as immutable.

User Functions

Parameters:

op_fine – [in] Fine grid CeedOperator
p_mult_fine – [in] L-vector multiplicity in parallel gather/scatter, or NULL if not creating prolongation/restriction CeedOperator
rstr_coarse – [in] Coarse grid CeedElemRestriction
basis_coarse – [in] Coarse grid active vector CeedBasis
interp_c_to_f – [in] Matrix for coarse to fine interpolation, or NULL if not creating prolongation/restriction CeedOperator
op_coarse – [out] Coarse grid CeedOperator
op_prolong – [out] Coarse to fine CeedOperator, or NULL
op_restrict – [out] Fine to coarse CeedOperator, or NULL

Returns:

An error code: 0 - success, otherwise - failure

int CeedOperatorCreateFDMElementInverse(CeedOperator op, CeedOperator *fdm_inv, 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 CeedQFunction is used to modify the eigenvalues from simultaneous diagonalization and obtain an approximate inverse of the form \(V^T \hat S V\). The CeedOperator must be linear and non-composite. The associated CeedQFunction must therefore also be linear.

Note: Calling this function asserts that setup is complete and sets the CeedOperator as immutable.

User Functions

Parameters:

op – [in] CeedOperator to create element inverses
fdm_inv – [out] CeedOperator to apply the action of a FDM based inverse for each element
request – [in] Address of CeedRequest for non-blocking completion, else CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure