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