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”. 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. 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 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 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 QFunctionContext a 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 QFunctionContext a 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 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, 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.