CeedVector

A CeedVector constitutes the main data structure and serves as input/output for the CeedOperators.

Basic vector operations

typedef struct CeedVector_private *CeedVector: Handle for vectors over the field CeedScalar.

const CeedVector CEED_VECTOR_ACTIVE = &ceed_vector_active: Indicate that vector will be provided as an explicit argument to CeedOperatorApply().

const CeedVector CEED_VECTOR_NONE = &ceed_vector_none: Indicate that no vector is applicable (i.e., for CEED_EVAL_WEIGHT).

int CeedVectorCreate(Ceed ceed, CeedSize length, CeedVector *vec)

Create a CeedVector of the specified length (does not allocate memory)

User Functions

Parameters:

ceed – [in] Ceed object used to create the CeedVector
length – [in] Length of vector
vec – [out] Address of the variable where the newly created CeedVector will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorReferenceCopy(CeedVector vec, CeedVector *vec_copy)

Copy the pointer to a CeedVector.

Both pointers should be destroyed with CeedVectorDestroy().

Note: If the value of *vec_copy passed to this function is non-NULL, then it is assumed that *vec_copy is a pointer to a CeedVector. This CeedVector will be destroyed if *vec_copy is the only reference to this CeedVector.

User Functions

Parameters:

vec – [in] CeedVector to copy reference to
vec_copy – [inout] Variable to store copied reference

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorCopy(CeedVector vec, CeedVector vec_copy)

Copy a CeedVector into a different CeedVector.

Both pointers should be destroyed with CeedVectorDestroy().

Note: If *vec_copy is non-NULL, then it is assumed that *vec_copy is a pointer to a CeedVector. This CeedVector will be destroyed if *vec_copy is the only reference to this CeedVector.

User Functions

Parameters:

vec – [in] CeedVector to copy
vec_copy – [inout] Variable to store copied CeedVector to

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorSetArray(CeedVector vec, CeedMemType mem_type, CeedCopyMode copy_mode, CeedScalar *array)

Set the array used by a CeedVector, freeing any previously allocated array if applicable.

The backend may copy values to a different CeedMemType, such as during CeedOperatorApply(). See also CeedVectorSyncArray() and CeedVectorTakeArray().

User Functions

Parameters:

vec – [inout] CeedVector
mem_type – [in] Memory type of the array being passed
copy_mode – [in] Copy mode for the array
array – [in] Array to be used, or NULL with CEED_COPY_VALUES to have the library allocate

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorSetValue(CeedVector vec, CeedScalar value)

Set the CeedVector to a constant value.

User Functions

Parameters:

vec – [inout] CeedVector
value – [in] Value to be used

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorSyncArray(CeedVector vec, CeedMemType mem_type)

Sync the CeedVector to a specified mem_type.

This function is used to force synchronization of arrays set with CeedVectorSetArray(). If the requested mem_type is already synchronized, this function results in a no-op.

User Functions

Parameters:

vec – [inout] CeedVector
mem_type – [in] CeedMemType to be synced

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorTakeArray(CeedVector vec, CeedMemType mem_type, CeedScalar **array)

Take ownership of the CeedVector array set by CeedVectorSetArray() with CEED_USE_POINTER and remove the array from the CeedVector.

The caller is responsible for managing and freeing the array. This function will error if CeedVectorSetArray() was not previously called with CEED_USE_POINTER for the corresponding mem_type.

User Functions

Parameters:

vec – [inout] CeedVector
mem_type – [in] Memory type on which to take the array. If the backend uses a different memory type, this will perform a copy.
array – [out] Array on memory type mem_type, or NULL if array pointer is not required

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorGetArray(CeedVector vec, CeedMemType mem_type, CeedScalar **array)

Get read/write access to a CeedVector via the specified memory type.

Restore access with CeedVectorRestoreArray().

User Functions

Note

The CeedVectorGetArray() and CeedVectorRestoreArray() functions provide access to array pointers in the desired memory space. Pairing get/restore allows the CeedVector to track access, thus knowing if norms or other operations may need to be recomputed.

Parameters:

vec – [inout] CeedVector to access
mem_type – [in] Memory type on which to access the array. If the backend uses a different memory type, this will perform a copy.
array – [out] Array on memory type mem_type

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorGetArrayRead(CeedVector vec, CeedMemType mem_type, const CeedScalar **array)

Get read-only access to a CeedVector via the specified memory type.

Restore access with CeedVectorRestoreArrayRead().

User Functions

Parameters:

vec – [in] CeedVector to access
mem_type – [in] Memory type on which to access the array. If the backend uses a different memory type, this will perform a copy (possibly cached).
array – [out] Array on memory type mem_type

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorGetArrayWrite(CeedVector vec, CeedMemType mem_type, CeedScalar **array)

Get write access to a CeedVector via the specified memory type.

Restore access with CeedVectorRestoreArray(). All old values should be assumed to be invalid.

User Functions

Parameters:

vec – [inout] CeedVector to access
mem_type – [in] Memory type on which to access the array.
array – [out] Array on memory type mem_type

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorRestoreArray(CeedVector vec, CeedScalar **array)

Restore an array obtained using CeedVectorGetArray() or CeedVectorGetArrayWrite()

User Functions

Parameters:

vec – [inout] CeedVector to restore
array – [inout] Array of vector data

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorRestoreArrayRead(CeedVector vec, const CeedScalar **array)

Restore an array obtained using CeedVectorGetArrayRead()

User Functions

Parameters:

vec – [in] CeedVector to restore
array – [inout] Array of vector data

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorNorm(CeedVector vec, CeedNormType norm_type, CeedScalar *norm)

Get the norm of a CeedVector.

Note: This operation is local to the CeedVector. This function will likely not provide the desired results for the norm of the libCEED portion of a parallel vector or a CeedVector with duplicated or hanging nodes.

User Functions

Parameters:

vec – [in] CeedVector to retrieve maximum value
norm_type – [in] Norm type CEED_NORM_1, CEED_NORM_2, or CEED_NORM_MAX
norm – [out] Variable to store norm value

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorScale(CeedVector x, CeedScalar alpha)

Compute x = alpha x

User Functions

Parameters:

x – [inout] CeedVector for scaling
alpha – [in] scaling factor

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorAXPY(CeedVector y, CeedScalar alpha, CeedVector x)

Compute y = alpha x + y

User Functions

Parameters:

y – [inout] target CeedVector for sum
alpha – [in] scaling factor
x – [in] second CeedVector, must be different than `y

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorAXPBY(CeedVector y, CeedScalar alpha, CeedScalar beta, CeedVector x)

Compute y = alpha x + beta y

User Functions

Parameters:

y – [inout] target CeedVector for sum
alpha – [in] first scaling factor
beta – [in] second scaling factor
x – [in] second CeedVector, must be different than y

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorPointwiseMult(CeedVector w, CeedVector x, CeedVector y)

Compute the pointwise multiplication \(w = x .* y\).

Any subset of x, y, and w may be the same CeedVector.

User Functions

Parameters:

w – [out] target CeedVector for the product
x – [in] first CeedVector for product
y – [in] second CeedVector for the product

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorReciprocal(CeedVector vec)

Take the reciprocal of a CeedVector.

User Functions

Parameters:

vec – [inout] CeedVector to take reciprocal

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorViewRange(CeedVector vec, CeedSize start, CeedSize stop, CeedInt step, const char *fp_fmt, FILE *stream)

View a CeedVector

Note: It is safe to use any unsigned values for start or stop and any nonzero integer for step. Any portion of the provided range that is outside the range of valid indices for the CeedVector will be ignored.

User Functions

Parameters:

vec – [in] CeedVector to view
start – [in] Index of first CeedVector entry to view
stop – [in] Index of last CeedVector entry to view
step – [in] Step between CeedVector entries to view
fp_fmt – [in] Printing format
stream – [in] Filestream to write to

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorView(CeedVector vec, const char *fp_fmt, FILE *stream)

View a CeedVector

User Functions

Parameters:

vec – [in] CeedVector to view
fp_fmt – [in] Printing format
stream – [in] Filestream to write to

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorGetCeed(CeedVector vec, Ceed *ceed)

Get the Ceed associated with a CeedVector

Advanced Functions

Parameters:

vec – [in] CeedVector to retrieve state
ceed – [out] Variable to store Ceed

Returns:

An error code: 0 - success, otherwise - failure

Ceed CeedVectorReturnCeed(CeedVector vec)

Return the Ceed associated with a CeedVector

Advanced Functions

Parameters:

vec – [in] CeedVector to retrieve state

Returns:

Ceed associated with the vec

int CeedVectorGetLength(CeedVector vec, CeedSize *length)

Get the length of a CeedVector

User Functions

Parameters:

vec – [in] CeedVector to retrieve length
length – [out] Variable to store length

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorDestroy(CeedVector *vec)

Destroy a CeedVector

User Functions

Parameters:

vec – [inout] CeedVector to destroy

Returns:

An error code: 0 - success, otherwise - failure

Typedefs and Enumerations

typedef int32_t CeedInt: Integer type, used for indexing.

typedef float CeedScalar

enum CeedCopyMode

Conveys ownership status of arrays passed to Ceed interfaces.

Values:

enumerator CEED_COPY_VALUES: Implementation will copy the values and not store the passed pointer.

enumerator CEED_USE_POINTER: Implementation can use and modify the data provided by the user, but does not take ownership.

enumerator CEED_OWN_POINTER

Implementation takes ownership of the pointer and will free using CeedFree() when done using it.

The user should not assume that the pointer remains valid after ownership has been transferred. Note that arrays allocated using C++ operator new or other allocators cannot generally be freed using CeedFree(). CeedFree() is capable of freeing any memory that can be freed using free().

enum CeedNormType

Denotes type of vector norm to be computed.

Values:

enumerator CEED_NORM_1: \(\Vert \bm{x}\Vert_1 = \sum_i \vert x_i\vert\)

enumerator CEED_NORM_2: \(\Vert \bm{x} \Vert_2 = \sqrt{\sum_i x_i^2}\)

enumerator CEED_NORM_MAX: \(\Vert \bm{x} \Vert_\infty = \max_i \vert x_i \vert\)