CeedQFunction

QFunctions represent 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 created

• vlength: 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 created

• name: 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: CeedQFunction

• fieldname: Name of QFunction field

• size: Size of QFunction field, (ncomp * dim) for CEED_EVAL_GRAD or (ncomp * 1) for CEED_EVAL_NONE and CEED_EVAL_INTERP

• emode: 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: CeedQFunction

• fieldname: Name of QFunction field

• size: Size of QFunction field, (ncomp * dim) for CEED_EVAL_GRAD or (ncomp * 1) for CEED_EVAL_NONE and CEED_EVAL_INTERP

• emode: 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: CeedQFunction

• ctx: 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: CeedQFunction

• Q: 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: CeedQFunctionContext

• mtype: Memory type of the data being passed

• cmode: Copy mode for the data

• data: 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 access

• mtype: 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 restore

• data: 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.