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 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 – A Ceed object where the CeedQFunction will be created

  • vec_length – Vector length. Caller must ensure that number of quadrature points is a multiple of vec_length.

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

  • 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 – A Ceed object where the CeedQFunction will be created

  • name – 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 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

Parameters

  • ceed – A 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 *qf_copy 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 – 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
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
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 – CeedQFunction

  • input_fields – [out] Variable to store input_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 – 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 – 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 – 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 – CeedQFunction

  • ctx – Context data to set

Returns

An error code: 0 - success, otherwise - failure

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 – 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 – CeedQFunction

  • Q – 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 – 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 – A 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 *ctx_copy 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 – CeedQFunctionContext to copy reference to

  • ctx_copy – [out] 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 – CeedQFunctionContext

  • mem_type – Memory type of the data being passed

  • copy_mode – Copy mode for the data

  • size – Size of data, in bytes

  • data – 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 – CeedQFunctionContext to access

  • mem_type – 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 – CeedQFunctionContext to access

  • mem_type – 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 – CeedQFunctionContext to restore

  • data – Data to restore

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 – 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 CeedQFunctionContextDestroy(CeedQFunctionContext *ctx)

Destroy a CeedQFunctionContext.

User Functions

Parameters

  • ctx – 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.

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.