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 a CeedElemRestriction and CeedBasis, such as restriction and prolongation operators for p-multigrid. Backends may optimize CeedOperator 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 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.

Note: In the user CeedQFunctionUser, the in argument list the fields in the order given by the calls to CeedQFunctionAddInput.

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, (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.

Note: In the user CeedQFunctionUser, the out argument list the fields in the order given by the calls to CeedQFunctionAddOutput.

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, (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 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 CeedQFunctionSetNumViewTabs(CeedQFunction qf, CeedInt num_tabs)

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

User Functions

Parameters:

qf – [in] CeedQFunction to set the number of view tabs
num_tabs – [in] Number of view tabs to set

Returns:

Error code: 0 - success, otherwise - failure

int CeedQFunctionGetNumViewTabs(CeedQFunction qf, CeedInt *num_tabs)

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

User Functions

Parameters:

qf – [in] CeedQFunction to get the number of view tabs
num_tabs – [out] Number of view tabs

Returns:

Error code: 0 - success, otherwise - failure

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 CeedQFunctionContextSetNumViewTabs(CeedQFunctionContext ctx, CeedInt num_tabs)

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

User Functions

Parameters:

ctx – [in] CeedQFunctionContext to set the number of view tabs
num_tabs – [in] Number of view tabs to set

Returns:

Error code: 0 - success, otherwise - failure

int CeedQFunctionContextGetNumViewTabs(CeedQFunctionContext ctx, CeedInt *num_tabs)

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

User Functions

Parameters:

ctx – [in] CeedQFunctionContext to get the number of view tabs
num_tabs – [out] Number of view tabs

Returns:

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.