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 theCeedQFunctionUser
writes into the CeedQFunctionContextData and requires memory syncronization after callingCeedQFunctionApply()
.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 thatctx_copy
is a pointer to a CeedQFunctionContext. This CeedQFunctionContext will be destroyed ifctx_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.