CeedVector

CeedVectors constitute the main data structure and serve as input/output for 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_WEIGHTS).

int CeedVectorCreate(Ceed ceed, CeedInt length, CeedVector *vec)

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

User Functions

Return

An error code: 0 - success, otherwise - failure

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

  • length: Length of vector

  • [out] vec: Address of the variable where the newly created CeedVector will be stored

int CeedVectorSetArray(CeedVector vec, CeedMemType mtype, CeedCopyMode cmode, 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

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector

  • mtype: Memory type of the array being passed

  • cmode: Copy mode for the array

  • array: Array to be used, or NULL with CEED_COPY_VALUES to have the library allocate

int CeedVectorSetValue(CeedVector vec, CeedScalar value)

Set the CeedVector to a constant value.

User Functions

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector

  • [in] value: Value to be used

int CeedVectorSyncArray(CeedVector vec, CeedMemType mtype)

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

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector

  • mtype: Memtype to be synced

int CeedVectorTakeArray(CeedVector vec, CeedMemType mtype, 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

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector

  • mtype: Memory type on which to take the array. If the backend uses a different memory type, this will perform a copy.

  • [out] array: Array on memory type mtype, or NULL if array pointer is not required

int CeedVectorGetArray(CeedVector vec, CeedMemType mtype, 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.

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector to access

  • mtype: Memory type on which to access the array. If the backend uses a different memory type, this will perform a copy.

  • [out] array: Array on memory type mtype

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

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

Restore access with CeedVectorRestoreArrayRead().

User Functions

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector to access

  • mtype: Memory type on which to access the array. If the backend uses a different memory type, this will perform a copy (possibly cached).

  • [out] array: Array on memory type mtype

int CeedVectorRestoreArray(CeedVector vec, CeedScalar **array)

Restore an array obtained using CeedVectorGetArray()

User Functions

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector to restore

  • array: Array of vector data

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

Restore an array obtained using CeedVectorGetArrayRead()

User Functions

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector to restore

  • array: Array of vector data

int CeedVectorNorm(CeedVector vec, CeedNormType 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

Return

An error code: 0 - success, otherwise - failure

Parameters

int CeedVectorReciprocal(CeedVector vec)

Take the reciprocal of a CeedVector.

User Functions

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector to take reciprocal

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

View a CeedVector.

User Functions

Return

An error code: 0 - success, otherwise - failure

Parameters
  • [in] vec: CeedVector to view

  • [in] fpfmt: Printing format

  • [in] stream: Filestream to write to

int CeedVectorGetLength(CeedVector vec, CeedInt *length)

Get the length of a CeedVector.

User Functions

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector to retrieve length

  • [out] length: Variable to store length

int CeedVectorDestroy(CeedVector *vec)

Destroy a CeedVector.

User Functions

Return

An error code: 0 - success, otherwise - failure

Parameters
  • vec: CeedVector to destroy

Typedefs and Enumerations

typedef int32_t CeedInt

Integer type, used for indexing.

typedef double CeedScalar

Scalar (floating point) type.

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