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
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[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 the CeedQFunctionUser writes into the CeedQFunctionContextData and requires memory syncronization after calling CeedQFunctionApply().

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