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 where the CeedVector will be created
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 thatvec_copy
is a pointer to a CeedVector. This CeedVector will be destroyed ifvec_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 memtype, 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 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 – [inout] CeedVector
mem_type – [in] 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 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 Vector 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] 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 CeedVectorAXPBY(CeedVector y, CeedScalar alpha, CeedScalar beta, CeedVector x)
Compute y = alpha x + beta y.
User Functions
- Parameters:
y – [inout] target vector for sum
alpha – [in] first scaling factor
beta – [in] second 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.
User Functions
- 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 – [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
orstop
and any nonzero integer forstep
. 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
-
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().
-
enumerator CEED_COPY_VALUES