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 arguments.

User Functions

Parameters:

ceed – [in] Ceed object used to create the CeedQFunction
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 CeedQFunctionUser.
source – [in] Absolute path to source of CeedQFunctionUser, “\abs_path\file.h:function_name”. The entire source file must only contain constructs supported by all targeted backends (i.e. CUDA for /gpu/cuda, OpenCL/SYCL for /gpu/sycl, etc.). The entire contents of this file and all locally included files are used during JiT compilation for GPU backends. The header ceed/types.h is preferred over ceed.h or ceed/ceed.h for CeedQFunction source files. The macro CEED_RUNNING_JIT_PASS is set during JiT and can be used to guard include statements that JiT compilers cannot use, such as math.h or std*.h. All source files must be at the provided filepath at runtime for JiT to function.
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 used to create the CeedQFunction
name – [in] Name of CeedQFunction 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 CeedOperator that can be represented with only the action of aCeedElemRestrictionandCeedBasis, such as restriction and prolongation operators for p-multigrid. Backends may optimizeCeedOperatorwith thisCeedQFunction` 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 used to create the CeedQFunction
size – [in] Size of the CeedQFunction 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 CeedQFunction field
size – [in] Size of CeedQFunction 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(\mathrm{div})\) or \(H(\mathrm{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 otherwise curl_dim = 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 CeedQFunction field
size – [in] Size of CeedQFunction 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(\mathrm{div})\) or \(H(\mathrm{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 CeedQFunctionField 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, const 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 CeedQFunctionFieldGetData(CeedQFunctionField qf_field, const char **field_name, CeedInt *size, CeedEvalMode *eval_mode)

Get the data of a CeedQFunctionField.

Any arguments set as NULL are ignored.

Advanced Functions

Parameters:

qf_field – [in] CeedQFunctionField
field_name – [out] Variable to store the field name
size – [out] Variable to store the size of the field
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 CeedQFunctionContext and requires memory synchronization after calling CeedQFunctionApply().

Setting ‘is_writable == false’ asserts that CeedQFunctionUser does not modify the CeedQFunctionContext. 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] Boolean flag for 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 CeedQFunction

Backend Developer Functions

Parameters:

qf – [in] CeedQFunction 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 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 storeCeed

Returns:

An error code: 0 - success, otherwise - failure

Ceed CeedQFunctionReturnCeed(CeedQFunction qf)

Return the Ceed associated with a CeedQFunction

Advanced Functions

Parameters:

qf – [in] CeedQFunction

Returns:

Ceed associated with the qf

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 CeedVector
v – [out] Array of output CeedVector

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 CeedQFunctionContext user context data.

User Functions

Parameters:

ceed – [in] Ceed object used to create the CeedQFunctionContext
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 CeedMemType, 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 CeedQFunctionContext 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 CeedQFunctionContext 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 a CeedQFunctionContext field holding double precision values.

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 a CeedQFunctionContext field holding int32 values.

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 CeedQFunctionContextRegisterBoolean(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values, const char *field_description)

Register a CeedQFunctionContext field holding boolean values.

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 CeedQFunctionContext 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, size_t *field_offset, size_t *num_values, const char **field_description, CeedContextFieldType *field_type)

Get the descriptive information about a CeedContextFieldLabel

User Functions

Parameters:

label – [in] CeedContextFieldLabel
field_name – [out] Name of labeled field
field_offset – [out] Offset of field registered
num_values – [out] Number of values registered
field_description – [out] Description of field, or NULL for none
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.