CeedQFunction

A CeedQFunction represents the spatial terms of the point-wise functions describing the physics at the quadrature points.

Resolution/space-independent weak forms and quadrature-based operations

typedef struct CeedQFunction_private *CeedQFunction

Handle for object describing functions evaluated independently at quadrature points.

typedef struct CeedQFunctionContext_private *CeedQFunctionContext

Handle for object describing context data for CeedQFunctions.

typedef struct CeedContextFieldLabel_private *CeedContextFieldLabel

Handle for object describing registered fields for CeedQFunctionContext.

const CeedQFunction CEED_QFUNCTION_NONE = &ceed_qfunction_none

int CeedQFunctionCreateInterior(Ceed ceed, CeedInt vec_length, CeedQFunctionUser f, const char *source, CeedQFunction *qf)

Create a CeedQFunction for evaluating interior (volumetric) terms.

See Public API for CeedQFunction for details on the call-back function f’s arguments.

User Functions

Parameters

• ceed – [in] Ceed object where the CeedQFunction will be created

• vec_length – [in] Vector length. Caller must ensure that number of quadrature points is a multiple of vec_length.

• f – [in] Function pointer to evaluate action at quadrature points. See Public API for CeedQFunction.

• source – [in] Absolute path to source of QFunction, “\abs_path\file.h:function_name”. For support across all backends, this source must only contain constructs supported by C99, C++11, and CUDA.

• qf – [out] Address of the variable where the newly created CeedQFunction will be stored

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionCreateInteriorByName(Ceed ceed, const char *name, CeedQFunction *qf)

Create a CeedQFunction for evaluating interior (volumetric) terms by name.

User Functions

Parameters

• ceed – [in] Ceed object where the CeedQFunction will be created

• name – [in] Name of QFunction to use from gallery

• qf – [out] Address of the variable where the newly created CeedQFunction will be stored

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionCreateIdentity(Ceed ceed, CeedInt size, CeedEvalMode in_mode, CeedEvalMode out_mode, CeedQFunction *qf)

Create an identity CeedQFunction.

Inputs are written into outputs in the order given. This is useful for CeedOperators that can be represented with only the action of a CeedElemRestriction and CeedBasis, such as restriction and prolongation operators for p-multigrid. Backends may optimize CeedOperators with this CeedQFunction to avoid the copy of input data to output fields by using the same memory location for both.

User Functions

Parameters

• ceed – [in] Ceed object where the CeedQFunction will be created

• size – [in] Size of the QFunction fields

• in_mode – [in] CeedEvalMode for input to CeedQFunction

• out_mode – [in] CeedEvalMode for output to CeedQFunction

• qf – [out] Address of the variable where the newly created CeedQFunction will be stored

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionReferenceCopy(CeedQFunction qf, CeedQFunction *qf_copy)

Copy the pointer to a CeedQFunction.

Both pointers should be destroyed with CeedQFunctionDestroy().

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

User Functions

Parameters

• qf – [in] CeedQFunction to copy reference to

• qf_copy – [out] Variable to store copied reference

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionAddInput(CeedQFunction qf, const char *field_name, CeedInt size, CeedEvalMode eval_mode)

Add a CeedQFunction input.

User Functions

Parameters

• qf – [inout] CeedQFunction

• field_name – [in] Name of QFunction field

• size – [in] Size of QFunction field, (num_comp * 1) for CEED_EVAL_NONE, (num_comp * 1) for CEED_EVAL_INTERP for an H^1 space or (num_comp * dim) for an H(div) or H(curl) space, (num_comp * dim) for CEED_EVAL_GRAD, or (num_comp * 1) for CEED_EVAL_DIV, and (num_comp * curl_dim) with curl_dim = 1 if dim < 3 else dim for CEED_EVAL_CURL.

• eval_mode – [in] CEED_EVAL_NONE to use values directly, CEED_EVAL_INTERP to use interpolated values, CEED_EVAL_GRAD to use gradients, CEED_EVAL_DIV to use divergence, CEED_EVAL_CURL to use curl.

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionAddOutput(CeedQFunction qf, const char *field_name, CeedInt size, CeedEvalMode eval_mode)

Add a CeedQFunction output.

User Functions

Parameters

• qf – [inout] CeedQFunction

• field_name – [in] Name of QFunction field

• size – [in] Size of QFunction field, (num_comp * 1) for CEED_EVAL_NONE, (num_comp * 1) for CEED_EVAL_INTERP for an H^1 space or (num_comp * dim) for an H(div) or H(curl) space, (num_comp * dim) for CEED_EVAL_GRAD, or (num_comp * 1) for CEED_EVAL_DIV, and (num_comp * curl_dim) with curl_dim = 1 if dim < 3 else dim for CEED_EVAL_CURL.

• eval_mode – [in] CEED_EVAL_NONE to use values directly, CEED_EVAL_INTERP to use interpolated values, CEED_EVAL_GRAD to use gradients, CEED_EVAL_DIV to use divergence, CEED_EVAL_CURL to use curl.

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionGetFields(CeedQFunction qf, CeedInt *num_input_fields, CeedQFunctionField **input_fields, CeedInt *num_output_fields, CeedQFunctionField **output_fields)

Get the CeedQFunctionFields of a CeedQFunction.

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

Advanced Functions

Parameters

• qf – [in] CeedQFunction

• 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 CeedQFunctionFieldGetName(CeedQFunctionField qf_field, char **field_name)

Get the name of a CeedQFunctionField.

Advanced Functions

Parameters

• qf_field – [in] CeedQFunctionField

• field_name – [out] Variable to store the field name

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionFieldGetSize(CeedQFunctionField qf_field, CeedInt *size)

Get the number of components of a CeedQFunctionField.

Advanced Functions

Parameters

• qf_field – [in] CeedQFunctionField

• size – [out] Variable to store the size of the field

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionFieldGetEvalMode(CeedQFunctionField qf_field, CeedEvalMode *eval_mode)

Get the CeedEvalMode of a CeedQFunctionField.

Advanced Functions

Parameters

• qf_field – [in] CeedQFunctionField

• eval_mode – [out] Variable to store the field evaluation mode

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionSetContext(CeedQFunction qf, CeedQFunctionContext ctx)

Set global context for a CeedQFunction.

User Functions

Parameters

• qf – [inout] CeedQFunction

• ctx – [in] Context data to set

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionSetContextWritable(CeedQFunction qf, bool is_writable)

Set writability of CeedQFunctionContext when calling the CeedQFunctionUser.

The default value is is_writable == true.

Setting is_writable == true indicates the CeedQFunctionUser writes into the CeedQFunctionContextData and requires memory syncronization after calling CeedQFunctionApply().

Setting ‘is_writable == false’ asserts that CeedQFunctionUser does not modify the CeedQFunctionContextData. Violating this assertion may lead to inconsistent data.

Setting is_writable == false may offer a performance improvement on GPU backends.

User Functions

Parameters

• qf – [inout] CeedQFunction

• is_writable – [in] Writability status

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionSetUserFlopsEstimate(CeedQFunction qf, CeedSize flops)

Set estimated number of FLOPs per quadrature required to apply QFunction.

Backend Developer Functions

Parameters

• qf – [in] QFunction to estimate FLOPs for

• flops – [out] FLOPs per quadrature point estimate

int CeedQFunctionView(CeedQFunction qf, FILE *stream)

View a CeedQFunction.

User Functions

Parameters

• qf – [in] CeedQFunction to view

• stream – [in] Stream to write; typically stdout/stderr or a file

Returns

Error code: 0 - success, otherwise - failure

int CeedQFunctionGetCeed(CeedQFunction qf, Ceed *ceed)

Get the Ceed associated with a CeedQFunction.

Advanced Functions

Parameters

• qf – [in] CeedQFunction

• ceed – [out] Variable to store Ceed

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionApply(CeedQFunction qf, CeedInt Q, CeedVector *u, CeedVector *v)

Apply the action of a CeedQFunction.

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

User Functions

Parameters

• qf – [in] CeedQFunction

• Q – [in] Number of quadrature points

• u – [in] Array of input CeedVectors

• v – [out] Array of output CeedVectors

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionDestroy(CeedQFunction *qf)

Destroy a CeedQFunction.

User Functions

Parameters

• qf – [inout] CeedQFunction to destroy

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextCreate(Ceed ceed, CeedQFunctionContext *ctx)

Create a CeedQFunctionContext for storing CeedQFunction user context data.

User Functions

Parameters

• ceed – [in] Ceed object where the CeedQFunctionContext will be created

• ctx – [out] Address of the variable where the newly created CeedQFunctionContext will be stored

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextReferenceCopy(CeedQFunctionContext ctx, CeedQFunctionContext *ctx_copy)

Copy the pointer to a CeedQFunctionContext.

Both pointers should be destroyed with CeedQFunctionContextDestroy().

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

User Functions

Parameters

• ctx – [in] CeedQFunctionContext to copy reference to

• ctx_copy – [inout] Variable to store copied reference

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextSetData(CeedQFunctionContext ctx, CeedMemType mem_type, CeedCopyMode copy_mode, size_t size, void *data)

Set the data used by a CeedQFunctionContext, freeing any previously allocated data if applicable.

The backend may copy values to a different memtype, such as during CeedQFunctionApply(). See also CeedQFunctionContextTakeData().

User Functions

Parameters

• ctx – [inout] CeedQFunctionContext

• mem_type – [in] Memory type of the data being passed

• copy_mode – [in] Copy mode for the data

• size – [in] Size of data, in bytes

• data – [in] Data to be used

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextTakeData(CeedQFunctionContext ctx, CeedMemType mem_type, void *data)

Take ownership of the data in a CeedQFunctionContext via the specified memory type.

The caller is responsible for managing and freeing the memory.

User Functions

Parameters

• ctx – [in] CeedQFunctionContext to access

• mem_type – [in] Memory type on which to access the data. If the backend uses a different memory type, this will perform a copy.

• data – [out] Data on memory type mem_type

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextGetData(CeedQFunctionContext ctx, CeedMemType mem_type, void *data)

Get read/write access to a CeedQFunctionContext via the specified memory type.

Restore access with CeedQFunctionContextRestoreData().

User Functions

Note

The CeedQFunctionContextGetData() and CeedQFunctionContextRestoreData() functions provide access to array pointers in the desired memory space. Pairing get/restore allows the Context to track access.

Parameters

• ctx – [in] CeedQFunctionContext to access

• mem_type – [in] Memory type on which to access the data. If the backend uses a different memory type, this will perform a copy.

• data – [out] Data on memory type mem_type

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextGetDataRead(CeedQFunctionContext ctx, CeedMemType mem_type, void *data)

Get read only access to a CeedQFunctionContext via the specified memory type.

Restore access with CeedQFunctionContextRestoreData().

User Functions

Note

The CeedQFunctionContextGetDataRead() and CeedQFunctionContextRestoreDataRead() functions provide access to array pointers in the desired memory space. Pairing get/restore allows the Context to track access.

Parameters

• ctx – [in] CeedQFunctionContext to access

• mem_type – [in] Memory type on which to access the data. If the backend uses a different memory type, this will perform a copy.

• data – [out] Data on memory type mem_type

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextRestoreData(CeedQFunctionContext ctx, void *data)

Restore data obtained using CeedQFunctionContextGetData()

User Functions

Parameters

• ctx – [in] CeedQFunctionContext to restore

• data – [inout] Data to restore

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextRestoreDataRead(CeedQFunctionContext ctx, void *data)

Restore data obtained using CeedQFunctionContextGetDataRead()

User Functions

Parameters

• ctx – [in] CeedQFunctionContext to restore

• data – [inout] Data to restore

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextRegisterDouble(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values, const char *field_description)

Register QFunctionContext a field holding a double precision value.

User Functions

Parameters

• ctx – [inout] CeedQFunctionContext

• field_name – [in] Name of field to register

• field_offset – [in] Offset of field to register

• num_values – [in] Number of values to register, must be contiguous in memory

• field_description – [in] Description of field, or NULL for none

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextRegisterInt32(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values, const char *field_description)

Register QFunctionContext a field holding a int32 value.

User Functions

Parameters

• ctx – [inout] CeedQFunctionContext

• field_name – [in] Name of field to register

• field_offset – [in] Offset of field to register

• num_values – [in] Number of values to register, must be contiguous in memory

• field_description – [in] Description of field, or NULL for none

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextGetAllFieldLabels(CeedQFunctionContext ctx, const CeedContextFieldLabel **field_labels, CeedInt *num_fields)

Get labels for all registered QFunctionContext fields.

User Functions

Parameters

• ctx – [in] CeedQFunctionContext

• field_labels – [out] Variable to hold array of field labels

• num_fields – [out] Length of field descriptions array

Returns

An error code: 0 - success, otherwise - failure

int CeedContextFieldLabelGetDescription(CeedContextFieldLabel label, const char **field_name, const char **field_description, size_t *num_values, CeedContextFieldType *field_type)

Get the descriptive information about a CeedContextFieldLabel.

User Functions

Parameters

• label – [in] CeedContextFieldLabel

• field_name – [out] Name of labeled field

• field_description – [out] Description of field, or NULL for none

• num_values – [out] Number of values registered

• field_type – [out] CeedContextFieldType

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextGetContextSize(CeedQFunctionContext ctx, size_t *ctx_size)

Get data size for a Context.

User Functions

Parameters

• ctx – [in] CeedQFunctionContext

• ctx_size – [out] Variable to store size of context data values

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextView(CeedQFunctionContext ctx, FILE *stream)

View a CeedQFunctionContext.

User Functions

Parameters

• ctx – [in] CeedQFunctionContext to view

• stream – [in] Filestream to write to

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextSetDataDestroy(CeedQFunctionContext ctx, CeedMemType f_mem_type, CeedQFunctionContextDataDestroyUser f)

Set additional destroy routine for CeedQFunctionContext user data.

User Functions

Parameters

• ctx – [inout] CeedQFunctionContext to set user destroy function

• f_mem_type – [in] Memory type to use when passing data into f

• f – [in] Additional routine to use to destroy user data

Returns

An error code: 0 - success, otherwise - failure

int CeedQFunctionContextDestroy(CeedQFunctionContext *ctx)

Destroy a CeedQFunctionContext.

User Functions

Parameters

• ctx – [inout] CeedQFunctionContext to destroy

Returns

An error code: 0 - success, otherwise - failure

Macros

CEED_QFUNCTION(name)

This macro populates the correct function annotations for User QFunction source for code generation backends or populates default values for CPU backends.

It also creates a variable name_loc populated with the correct source path for creating the respective User QFunction.

CEED_QFUNCTION_HELPER

This macro populates the correct function annotations for User QFunction helper function source for code generation backends or populates default values for CPU backends.

CEED_Q_VLA

Using VLA syntax to reshape User QFunction inputs and outputs can make user code more readable.

VLA is a C99 feature that is not supported by the C++ dialect used by CUDA. This macro allows users to use the VLA syntax with the CUDA backends.