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

User Functions

Parameters:
  • ceed[in] Ceed object used to create the CeedQFunction

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

  • source[in] Absolute path to source of CeedQFunctionUser, “\abs_path\file.h:function_name”. The entire source file must only contain constructs supported by all targeted backends (i.e. CUDA for /gpu/cuda, OpenCL/SYCL for /gpu/sycl, etc.). The entire contents of this file and all locally included files are used during JiT compilation for GPU backends. All source files must be at the provided filepath at runtime for JiT to function.

  • 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 used to create the CeedQFunction

  • name[in] Name of CeedQFunction 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 CeedOperator that can be represented with only the action of aCeedElemRestrictionandCeedBasis, such as restriction and prolongation operators for p-multigrid. Backends may optimizeCeedOperatorwith thisCeedQFunction` 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 used to create the CeedQFunction

  • size[in] Size of the CeedQFunction 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 CeedQFunctionField 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, const 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 CeedQFunctionFieldGetData(CeedQFunctionField qf_field, const char **field_name, CeedInt *size, CeedEvalMode *eval_mode)

Get the data of a CeedQFunctionField.

Any arguments set as NULL are ignored.

Advanced Functions

Parameters:
  • qf_field[in] CeedQFunctionField

  • field_name[out] Variable to store the field name

  • size[out] Variable to store the size of the field

  • 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 CeedQFunctionContext and requires memory synchronization after calling CeedQFunctionApply().

Setting ‘is_writable == false’ asserts that CeedQFunctionUser does not modify the CeedQFunctionContext. 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] Boolean flag for 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 CeedQFunction

Backend Developer Functions

Parameters:
  • qf[in] CeedQFunction 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 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 storeCeed

Returns:

An error code: 0 - success, otherwise - failure

Ceed CeedQFunctionReturnCeed(CeedQFunction qf)

Return the Ceed associated with a CeedQFunction

Advanced Functions

Parameters:
  • qf[in] CeedQFunction

Returns:

Ceed associated with the qf

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 CeedVector

  • v[out] Array of output CeedVector

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 CeedQFunctionContext user context data.

User Functions

Parameters:
  • ceed[in] Ceed object used to create the CeedQFunctionContext

  • 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 CeedMemType, 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 CeedQFunctionContext 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 CeedQFunctionContext 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 a CeedQFunctionContext field holding double precision values.

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 a CeedQFunctionContext field holding int32 values.

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 CeedQFunctionContextRegisterBoolean(CeedQFunctionContext ctx, const char *field_name, size_t field_offset, size_t num_values, const char *field_description)

Register a CeedQFunctionContext field holding boolean values.

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 CeedQFunctionContext 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, size_t *field_offset, size_t *num_values, const char **field_description, CeedContextFieldType *field_type)

Get the descriptive information about a CeedContextFieldLabel

User Functions

Parameters:
  • label[in] CeedContextFieldLabel

  • field_name[out] Name of labeled field

  • field_offset[out] Offset of field registered

  • num_values[out] Number of values registered

  • field_description[out] Description of field, or NULL for none

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