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.
-
const CeedQFunction
CEED_QFUNCTION_NONE
= &ceed_qfunction_none¶
-
int
CeedQFunctionCreateInterior
(Ceed ceed, CeedInt vlength, 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.- Return
An error code: 0 - success, otherwise - failure
- Parameters
ceed
: A Ceed object where the CeedQFunction will be createdvlength
: Vector length. Caller must ensure that number of quadrature points is a multiple of vlength.f
: Function pointer to evaluate action at quadrature points. See Public API for CeedQFunction.source
: 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.[out] qf
: Address of the variable where the newly created CeedQFunction will be stored
User Functions
-
int
CeedQFunctionCreateInteriorByName
(Ceed ceed, const char *name, CeedQFunction *qf)¶ Create a CeedQFunction for evaluating interior (volumetric) terms by name.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ceed
: A Ceed object where the CeedQFunction will be createdname
: Name of QFunction to use from gallery[out] qf
: Address of the variable where the newly created CeedQFunction will be stored
-
int
CeedQFunctionCreateIdentity
(Ceed ceed, CeedInt size, CeedEvalMode inmode, CeedEvalMode outmode, 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 CeedRestriction 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
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ceed
: A Ceed object where the CeedQFunction will be created[in] size
: Size of the qfunction fields[in] inmode
: CeedEvalMode for input to CeedQFunction[in] outmode
: CeedEvalMode for output to CeedQFunction[out] qf
: Address of the variable where the newly created CeedQFunction will be stored
-
int
CeedQFunctionAddInput
(CeedQFunction qf, const char *fieldname, CeedInt size, CeedEvalMode emode)¶ Add a CeedQFunction input.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
qf
: CeedQFunctionfieldname
: Name of QFunction fieldsize
: Size of QFunction field, (ncomp * dim) for CEED_EVAL_GRAD or (ncomp * 1) for CEED_EVAL_NONE and CEED_EVAL_INTERPemode
: CEED_EVAL_NONE to use values directly, CEED_EVAL_INTERP to use interpolated values, CEED_EVAL_GRAD to use gradients.
-
int
CeedQFunctionAddOutput
(CeedQFunction qf, const char *fieldname, CeedInt size, CeedEvalMode emode)¶ Add a CeedQFunction output.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
qf
: CeedQFunctionfieldname
: Name of QFunction fieldsize
: Size of QFunction field, (ncomp * dim) for CEED_EVAL_GRAD or (ncomp * 1) for CEED_EVAL_NONE and CEED_EVAL_INTERPemode
: CEED_EVAL_NONE to use values directly, CEED_EVAL_INTERP to use interpolated values, CEED_EVAL_GRAD to use gradients.
-
int
CeedQFunctionSetContext
(CeedQFunction qf, CeedQFunctionContext ctx)¶ Set global context for a CeedQFunction.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
qf
: CeedQFunctionctx
: Context data to set
-
int
CeedQFunctionView
(CeedQFunction qf, FILE *stream)¶ View a CeedQFunction.
User Functions
- Return
Error code: 0 - success, otherwise - failure
- Parameters
[in] qf
: CeedQFunction to view[in] stream
: Stream to write; typically stdout/stderr or a file
-
int
CeedQFunctionApply
(CeedQFunction qf, CeedInt Q, CeedVector *u, CeedVector *v)¶ Apply the action of a CeedQFunction.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
qf
: CeedQFunctionQ
: Number of quadrature points[in] u
: Array of input CeedVectors[out] v
: Array of output CeedVectors
-
int
CeedQFunctionDestroy
(CeedQFunction *qf)¶ Destroy a CeedQFunction.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
qf
: CeedQFunction to destroy
-
int
CeedQFunctionContextCreate
(Ceed ceed, CeedQFunctionContext *ctx)¶ Create a CeedQFunctionContext for storing CeedQFunction user context data.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ceed
: A Ceed object where the CeedQFunctionContext will be created[out] ctx
: Address of the variable where the newly created CeedQFunctionContext will be stored
-
int
CeedQFunctionContextSetData
(CeedQFunctionContext ctx, CeedMemType mtype, CeedCopyMode cmode, 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
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ctx
: CeedQFunctionContextmtype
: Memory type of the data being passedcmode
: Copy mode for the datadata
: Data to be used
-
int
CeedQFunctionContextGetData
(CeedQFunctionContext ctx, CeedMemType mtype, 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.
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ctx
: CeedQFunctionContext to accessmtype
: Memory type on which to access the data. If the backend uses a different memory type, this will perform a copy.[out] data
: Data on memory type mtype
-
int
CeedQFunctionContextRestoreData
(CeedQFunctionContext ctx, void *data)¶ Restore data obtained using CeedQFunctionContextGetData()
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ctx
: CeedQFunctionContext to restoredata
: Data to restore
-
int
CeedQFunctionContextView
(CeedQFunctionContext ctx, FILE *stream)¶ View a CeedQFunctionContext.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
[in] ctx
: CeedQFunctionContext to view[in] stream
: Filestream to write to
-
int
CeedQFunctionContextDestroy
(CeedQFunctionContext *ctx)¶ Destroy a CeedQFunctionContext.
User Functions
- Return
An error code: 0 - success, otherwise - failure
- Parameters
ctx
: CeedQFunctionContext to destroy
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.
-
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.