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.

User Functions

Parameters:

  • vec – [in] CeedVector to copy

  • vec_copy – [inout] CeedVector to copy array into

Returns:

An error code: 0 - success, otherwise - failure

int CeedVectorCopyStrided(CeedVector vec, CeedSize start, CeedSize stop, CeedSize step, CeedVector vec_copy)

Copy a strided portion of CeedVector contents into a different CeedVector

User Functions

Parameters:

  • vec – [in] CeedVector to copy

  • start – [in] First index to copy in the range [start, stop)

  • stop – [in] One past the last element to copy in the range, or -1 for length

  • step – [in] Stride between indices to copy

  • vec_copy – [inout] CeedVector to copy values 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 CeedVectorSetValueStrided(CeedVector vec, CeedSize start, CeedSize stop, CeedSize step, CeedScalar value)

Set a portion of a CeedVector to a constant value.

Note: The CeedVector must already have valid data set via CeedVectorSetArray() or similar.

User Functions

Parameters:

  • vec – [inout] CeedVector

  • start – [in] First index to set in range [start, stop)

  • stop – [in] One past the last element to set in the range, or -1 for length

  • step – [in] Stride between indices to set

  • 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:
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 CeedVectorSetNumViewTabs(CeedVector vec, CeedInt num_tabs)

Set the number of tabs to indent for CeedVectorView() output.

User Functions

Parameters:

  • vec – [in] CeedVector to set the number of view tabs

  • num_tabs – [in] Number of view tabs to set

Returns:

Error code: 0 - success, otherwise - failure

int CeedVectorGetNumViewTabs(CeedVector vec, CeedInt *num_tabs)

Get the number of tabs to indent for CeedVectorView() output.

User Functions

Parameters:

  • vec – [in] CeedVector to get the number of view tabs

  • num_tabs – [out] Number of view tabs

Returns:

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 in the range [start, stop)

  • stop – [in] One past the last element to view in the range, or -1 for length

  • 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\)