Ceed

int CeedObjectCreate(Ceed ceed, int (*view_function)(CeedObject, FILE*), int (*destroy_function)(CeedObject*), CeedObject obj)

Create a CeedObject.

Note: This interface takes a CeedObject and not a pointer to a CeedObject like other Ceed*Create interfaces. This CeedObject will have already been allocated a the first part of the Ceed* struct. This function is only intended to be called inside of Ceed*Create functions.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed object to reference

  • view_function – [in] Ceed* function for viewing the obj

  • destroy_function – [in] Ceed* function for destroying the obj

  • obj – [out] Address of the variable where is CeedObject exists

Returns:

An error code: 0 - success, otherwise - failure

int CeedObjectReference(CeedObject obj)

Increment the reference counter for a CeedObject

Backend Developer Functions

Parameters:

  • obj – [inout] CeedObject to increment the reference counter

Returns:

An error code: 0 - success, otherwise - failure

int CeedObjectDereference(CeedObject obj)

Decrement the reference counter for a CeedObject

Backend Developer Functions

Parameters:

  • obj – [inout] CeedObject to decrement the reference counter

Returns:

The new reference count

int CeedObjectDestroy_Private(CeedObject obj)

Destroy a CeedObject.

Backend Developer Functions

Parameters:

  • obj – [inout] CeedObject to destroy

Returns:

An error code: 0 - success, otherwise - failure

bool CeedDebugFlag(const Ceed ceed)

Return value of CEED_DEBUG environment variable.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

Returns:

Boolean value: true - debugging mode enabled false - debugging mode disabled

bool CeedDebugFlagEnv(void)

Return value of CEED_DEBUG environment variable.

Backend Developer Functions

Returns:

Boolean value: true - debugging mode enabled false - debugging mode disabled

void CeedDebugImpl256(const unsigned char color, const char *format, ...)

Print debugging information in color.

Backend Developer Functions

Parameters:

  • color – [in] Color to print

  • format – [in] Printing format

int CeedMallocArray(size_t n, size_t unit, void *p)

Allocate an array on the host; use CeedMalloc().

Memory usage can be tracked by the library. This ensures sufficient alignment for vectorization and should be used for large allocations.

Backend Developer Functions

See also

CeedFree()

Parameters:

  • n – [in] Number of units to allocate

  • unit – [in] Size of each unit

  • p – [out] Address of pointer to hold the result

Returns:

An error code: 0 - success, otherwise - failure

int CeedCallocArray(size_t n, size_t unit, void *p)

Allocate a cleared (zeroed) array on the host; use CeedCalloc().

Memory usage can be tracked by the library.

Backend Developer Functions

See also

CeedFree()

Parameters:

  • n – [in] Number of units to allocate

  • unit – [in] Size of each unit

  • p – [out] Address of pointer to hold the result

Returns:

An error code: 0 - success, otherwise - failure

int CeedReallocArray(size_t n, size_t unit, void *p)

Reallocate an array on the host; use CeedRealloc().

Memory usage can be tracked by the library.

Backend Developer Functions

See also

CeedFree()

Parameters:

  • n – [in] Number of units to allocate

  • unit – [in] Size of each unit

  • p – [out] Address of pointer to hold the result

Returns:

An error code: 0 - success, otherwise - failure

int CeedStringAllocCopy(const char *source, char **copy)

Allocate a cleared string buffer on the host.

Memory usage can be tracked by the library.

Backend Developer Functions

See also

CeedFree()

Parameters:

  • source – [in] Pointer to string to be copied

  • copy – [out] Pointer to variable to hold newly allocated string copy

Returns:

An error code: 0 - success, otherwise - failure

int CeedFree(void *p)

Free memory allocated using CeedMalloc() or CeedCalloc()

Backend Developer Functions

Parameters:

  • p – [inout] Address of pointer to memory. This argument is of type void* to avoid needing a cast, but is the address of the pointer (which is zeroed) rather than the pointer.

Returns:

An error code: 0 - success, otherwise - failure

static inline int CeedSetHostGenericArray(const void *source_array, CeedCopyMode copy_mode, size_t size_unit, CeedSize num_values, void *target_array_owned, void *target_array_borrowed, void *target_array)

Internal helper to manage handoff of user source_array to backend with proper CeedCopyMode behavior.

Backend Developer Functions

Parameters:

  • source_array – [in] Source data provided by user

  • copy_mode – [in] Copy mode for the data

  • num_values – [in] Number of values to handle

  • size_unit – [in] Size of array element in bytes

  • target_array_owned – [inout] Pointer to location to allocated or hold owned data, may be freed if already allocated

  • target_array_borrowed – [out] Pointer to location to hold borrowed data

  • target_array – [out] Pointer to location for data

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetHostBoolArray(const bool *source_array, CeedCopyMode copy_mode, CeedSize num_values, const bool **target_array_owned, const bool **target_array_borrowed, const bool **target_array)

Manage handoff of user bool source_array to backend with proper CeedCopyMode behavior.

Backend Developer Functions

Parameters:

  • source_array – [in] Source data provided by user

  • copy_mode – [in] Copy mode for the data

  • num_values – [in] Number of values to handle

  • target_array_owned – [inout] Pointer to location to allocated or hold owned data, may be freed if already allocated

  • target_array_borrowed – [out] Pointer to location to hold borrowed data

  • target_array – [out] Pointer to location for data

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetHostCeedInt8Array(const CeedInt8 *source_array, CeedCopyMode copy_mode, CeedSize num_values, const CeedInt8 **target_array_owned, const CeedInt8 **target_array_borrowed, const CeedInt8 **target_array)

Manage handoff of user CeedInt8 source_array to backend with proper CeedCopyMode behavior.

Backend Developer Functions

Parameters:

  • source_array – [in] Source data provided by user

  • copy_mode – [in] Copy mode for the data

  • num_values – [in] Number of values to handle

  • target_array_owned – [inout] Pointer to location to allocated or hold owned data, may be freed if already allocated

  • target_array_borrowed – [out] Pointer to location to hold borrowed data

  • target_array – [out] Pointer to location for data

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetHostCeedIntArray(const CeedInt *source_array, CeedCopyMode copy_mode, CeedSize num_values, const CeedInt **target_array_owned, const CeedInt **target_array_borrowed, const CeedInt **target_array)

Manage handoff of user CeedInt source_array to backend with proper CeedCopyMode behavior.

Backend Developer Functions

Parameters:

  • source_array – [in] Source data provided by user

  • copy_mode – [in] Copy mode for the data

  • num_values – [in] Number of values to handle

  • target_array_owned – [inout] Pointer to location to allocated or hold owned data, may be freed if already allocated

  • target_array_borrowed – [out] Pointer to location to hold borrowed data

  • target_array – [out] Pointer to location for data

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetHostCeedScalarArray(const CeedScalar *source_array, CeedCopyMode copy_mode, CeedSize num_values, const CeedScalar **target_array_owned, const CeedScalar **target_array_borrowed, const CeedScalar **target_array)

Manage handoff of user CeedScalar source_array to backend with proper CeedCopyMode behavior.

Backend Developer Functions

Parameters:

  • source_array – [in] Source data provided by user

  • copy_mode – [in] Copy mode for the data

  • num_values – [in] Number of values to handle

  • target_array_owned – [inout] Pointer to location to allocated or hold owned data, may be freed if already allocated

  • target_array_borrowed – [out] Pointer to location to hold borrowed data

  • target_array – [out] Pointer to location for data

Returns:

An error code: 0 - success, otherwise - failure

int CeedRegister(const char *prefix, int (*init)(const char*, Ceed), unsigned int priority)

Register a Ceed backend.

Backend Developer Functions

Parameters:

  • prefix – [in] Prefix of resources for this backend to respond to. For example, the reference backend responds to “/cpu/self”.

  • init – [in] Initialization function called by CeedInit() when the backend is selected to drive the requested resource

  • priority – [in] Integer priority. Lower values are preferred in case the resource requested by CeedInit() has non-unique best prefix match.

Returns:

An error code: 0 - success, otherwise - failure

int CeedIsDebug(Ceed ceed, bool *is_debug)

Return debugging status flag.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context to get debugging flag

  • is_debug – [out] Variable to store debugging flag

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetResourceRoot(Ceed ceed, const char *resource, const char *delineator, char **resource_root)

Get the root of the requested resource.

Note: Caller is responsible for calling CeedFree() on the resource_root.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context to get resource name of

  • resource – [in] Full user specified resource

  • delineator – [in] Delineator to break resource_root and resource_spec

  • resource_root – [out] Variable to store resource root

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetParent(Ceed ceed, Ceed *parent)

Retrieve a parent Ceed context.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context to retrieve parent of

  • parent – [out] Address to save the parent to

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetDelegate(Ceed ceed, Ceed *delegate)

Retrieve a delegate Ceed context.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context to retrieve delegate of

  • delegate – [out] Address to save the delegate to

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetDelegate(Ceed ceed, Ceed delegate)

Set a delegate Ceed context.

This function allows a Ceed context to set a delegate Ceed context. All backend implementations default to the delegate Ceed context, unless overridden.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context to set delegate of

  • delegate – [out] Address to set the delegate to

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetObjectDelegate(Ceed ceed, Ceed *delegate, const char *obj_name)

Retrieve a delegate Ceed context for a specific object type.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context to retrieve delegate of

  • delegate – [out] Address to save the delegate to

  • obj_name – [in] Name of the object type to retrieve delegate for

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetObjectDelegate(Ceed ceed, Ceed delegate, const char *obj_name)

Set a delegate Ceed context for a specific object type.

This function allows a Ceed context to set a delegate Ceed context for a given type of Ceed object. All backend implementations default to the delegate Ceed context for this object. For example, CeedSetObjectDelegate(ceed, delegate, "Basis") uses delegate implementations for all CeedBasis backend functions.

Backend Developer Functions

Parameters:

  • ceed – [inout] Ceed context to set delegate of

  • delegate – [in] Ceed context to use for delegation

  • obj_name – [in] Name of the object type to set delegate for

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetOperatorFallbackCeed(Ceed ceed, Ceed *fallback_ceed)

Get the fallback Ceed for CeedOperator

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • fallback_ceed – [out] Variable to store fallback Ceed

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetOperatorFallbackCeed(Ceed ceed, Ceed fallback_ceed)

Set the fallback resource for CeedOperator.

The current fallback, if any, is freed by calling this function.

Backend Developer Functions

Parameters:

  • ceed – [inout] Ceed context

  • fallback_ceed – [in] Ceed context to create fallback operators

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetDeterministic(Ceed ceed, bool is_deterministic)

Flag Ceed context as deterministic.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed to flag as deterministic

  • is_deterministic – [out] Deterministic status to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetBackendFunctionImpl(Ceed ceed, const char *type, void *object, const char *func_name, void (*f)(void))

Set a backend function.

This function is used for a backend to set the function associated with the Ceed objects. For example, CeedSetBackendFunction(ceed, "Ceed", ceed, "VectorCreate", BackendVectorCreate) sets the backend implementation of CeedVectorCreate() and CeedSetBackendFunction(ceed, "Basis", basis, "Apply", BackendBasisApply) sets the backend implementation of CeedBasisApply(). Note, the prefix ‘Ceed’ is not required for the object type (“Basis” vs “CeedBasis”).

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context for error handling

  • type – [in] Type of Ceed object to set function for

  • object – [out] Ceed object to set function for

  • func_name – [in] Name of function to set

  • f – [in] Function to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetData(Ceed ceed, void *data)

Retrieve backend data for a Ceed context.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context to retrieve data of

  • data – [out] Address to save data to

Returns:

An error code: 0 - success, otherwise - failure

int CeedSetData(Ceed ceed, void *data)

Set backend data for a Ceed context.

Backend Developer Functions

Parameters:

  • ceed – [inout] Ceed context to set data of

  • data – [in] Address of data to set

Returns:

An error code: 0 - success, otherwise - failure

int CeedReference(Ceed ceed)

Increment the reference counter for a Ceed context.

Backend Developer Functions

Parameters:

  • ceed – [inout] Ceed context to increment the reference counter

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetWorkVectorMemoryUsage(Ceed ceed, CeedScalar *usage_mb)

Computes the current memory usage of the work vectors in a Ceed context and prints to debug.abort.

Library Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • usage_mb – [out] Address of the variable where the MB of work vector usage will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedClearWorkVectors(Ceed ceed, CeedSize min_len)

Clear inactive work vectors in a Ceed context below a minimum length.

Backend Developer Functions

Parameters:

  • ceed – [inout] Ceed context

  • min_len – [in] Minimum length of work vector to keep

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetWorkVector(Ceed ceed, CeedSize len, CeedVector *vec)

Get a CeedVector for scratch work from a Ceed context.

Note: This vector must be restored with CeedRestoreWorkVector().

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • len – [in] Minimum length of work vector

  • vec – [out] Address of the variable where CeedVector will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedRestoreWorkVector(Ceed ceed, CeedVector *vec)

Restore a CeedVector for scratch work from a Ceed context from CeedGetWorkVector()

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • vec – [out] CeedVector to restore

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetJitSourceRoots(Ceed ceed, CeedInt *num_source_roots, const char ***jit_source_roots)

Retrieve list of additional JiT source roots from Ceed context.

Note: The caller is responsible for restoring jit_source_roots with CeedRestoreJitSourceRoots().

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • num_source_roots – [out] Number of JiT source directories

  • jit_source_roots – [out] Absolute paths to additional JiT source directories

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetRustSourceRoots(Ceed ceed, CeedInt *num_source_roots, const char ***rust_source_roots)

Retrieve list of additional Rust source roots from Ceed context.

Note: The caller is responsible for restoring rust_source_roots with CeedRestoreRustSourceRoots().

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • num_source_roots – [out] Number of JiT source directories

  • rust_source_roots – [out] Absolute paths to additional Rust source directories

Returns:

An error code: 0 - success, otherwise - failure

int CeedRestoreJitSourceRoots(Ceed ceed, const char ***jit_source_roots)

Restore list of additional JiT source roots from with CeedGetJitSourceRoots()

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • jit_source_roots – [out] Absolute paths to additional JiT source directories

Returns:

An error code: 0 - success, otherwise - failure

int CeedRestoreRustSourceRoots(Ceed ceed, const char ***rust_source_roots)

Restore list of additional Rust source roots from with CeedGetJitSourceRoots()

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • rust_source_roots – [out] Absolute paths to additional Rust source directories

Returns:

An error code: 0 - success, otherwise - failure

int CeedGetJitDefines(Ceed ceed, CeedInt *num_jit_defines, const char ***jit_defines)

Retrieve list of additional JiT defines from Ceed context.

Note: The caller is responsible for restoring jit_defines with CeedRestoreJitDefines().

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • num_jit_defines – [out] Number of JiT defines

  • jit_defines – [out] Strings such as foo=bar, used as -Dfoo=bar in JiT

Returns:

An error code: 0 - success, otherwise - failure

int CeedRestoreJitDefines(Ceed ceed, const char ***jit_defines)

Restore list of additional JiT defines from with CeedGetJitDefines()

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed context

  • jit_defines – [out] String such as foo=bar, used as -Dfoo=bar in JiT

Returns:

An error code: 0 - success, otherwise - failure

Macros

CeedDebug256(ceed, color, ...)

Print debugging information in color.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed

  • color – [in] Color to print with

CeedDebug(ceed, ...)

Print debugging information to terminal.

Backend Developer Functions

Parameters:

  • ceed – [in] Ceed

CeedDebugEnv256(color, ...)

Print debugging information in color without Ceed to reference.

Backend Developer Functions

Parameters:

  • color – [in] Color to print with

CeedDebugEnv(...)

Print debugging information to terminal without Ceed to reference.

Backend Developer Functions

Typedefs and Enumerations

enum CeedDebugColor

This enum supplies common colors for CeedDebug256 debugging output.

Set the environment variable CEED_DEBUG = 1 to activate debugging output.

Backend Developer Functions

Values:

enumerator CEED_DEBUG_COLOR_SUCCESS

Success color.

enumerator CEED_DEBUG_COLOR_WARNING

Warning color.

enumerator CEED_DEBUG_COLOR_ERROR

Error color.

enumerator CEED_DEBUG_COLOR_NONE

Use native terminal coloring.