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, CeedInt length, CeedVector *vec)

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

User Functions

Parameters
  • ceed – Ceed object where the CeedVector will be created

  • length – 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 *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 – CeedVector to copy reference to

  • vec_copy[out] Variable to store copied reference

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 memtype, such as during CeedOperatorApply(). See also CeedVectorSyncArray() and CeedVectorTakeArray().

User Functions

Parameters
  • vec – CeedVector

  • mem_type – Memory type of the array being passed

  • copy_mode – Copy mode for the array

  • array – 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 – 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 memtype.

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

User Functions

Parameters
  • vec – CeedVector

  • mem_type – Memtype 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 and remove the array from the CeedVector.

The caller is responsible for managing and freeing the array.

User Functions

Parameters
  • vec – CeedVector

  • mem_type – 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 Vector to track access, thus knowing if norms or other operations may need to be recomputed.

Parameters
  • vec – CeedVector to access

  • mem_type – 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 – CeedVector to access

  • mem_type – 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 CeedVectorRestoreArray(CeedVector vec, CeedScalar **array)

Restore an array obtained using CeedVectorGetArray()

User Functions

Parameters
  • vec – CeedVector to restore

  • array – 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 – CeedVector to restore

  • array – 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] vector 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 vector for sum

  • alpha[in] scaling factor

  • x[in] second vector, 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 vector.

@ ref User

Parameters
  • w[out] target vector for the product

  • x[in] first vector for product

  • y[in] second vector 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 – CeedVector to take reciprocal

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 – CeedVector to retrieve state

  • ceed[out] Variable to store ceed

Returns

An error code: 0 - success, otherwise - failure

int CeedVectorGetLength(CeedVector vec, CeedInt *length)

Get the length of a CeedVector.

User Functions

Parameters
  • vec – 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 – 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(3).

enum CeedNormType

Denotes type of vector norm to be computed.

Values:

enumerator CEED_NORM_1

L_1 norm: sum_i |x_i|.

enumerator CEED_NORM_2

L_2 norm: sqrt(sum_i |x_i|^2)

enumerator CEED_NORM_MAX

L_Infinity norm: max_i |x_i|.