Template Class Vector

Defined in File Vector.hpp

Class Documentation

template<typename ScalarT, typename IdxT> class Vector

This class implements vectors (dense arrays) and multivectors and some basic utilities (get size, allocate, set data, get data, etc).

What you need to know:

Multivectors are stored in one array, organized column-wise. A vector is a multivector of size 1.
There is a mirroring memory approach: the class has DEVICE and HOST data pointers. If needed, only one (or none) can be used or allocated. Unless triggered directly or by other function, the data is NOT automatically updated between HOST and DEVICE.
Constructor DOES NOT allocate memory. This has to be done separately.
You can get (and set) “raw” data easily, if needed.
There is memory ownership utility - vector can own memory (separate flags for HOST and DEVICE) or not, depending on how it is used.

Author: Kasia Swirydowicz kasia.swirydowicz@pnnl.gov
Author: Slaven Peles peless@ornl.gov

Public Functions

Vector(IdxT n)

Single vector constructor.

Parameters:: n – [in] - Number of elements in the vector

Vector(IdxT n, IdxT k)

Multivector constructor.

Parameters:

n – [in] - Number of elements in the vector
k – [in] - Number of vectors in multivector

~Vector(): destructor.

int copyFromExternal(const ScalarT *source, memory::MemorySpace memspaceIn = memory::HOST, memory::MemorySpace memspaceOut = memory::HOST)

Copy vector data from an input array.

Destination memory must be pre-allocated via allocate() before calling this function.

Parameters:

source – [in] - Array to copy from
memspaceSrc – [in] - Memory space of the source array (HOST or DEVICE)
memspaceDst – [in] - Memory space to copy data to (HOST or DEVICE)

Returns:

0 if successful, 1 otherwise.

int copyFromExternal(const Vector &source, memory::MemorySpace memspaceIn = memory::HOST, memory::MemorySpace memspaceOut = memory::HOST)

Copy data from another vector.

Parameters:

source – [in] - Vector whose data will be copied
memspaceSrc – [in] - Memory space of the data source (HOST or DEVICE)
memspaceDst – [in] - Memory space to copy data to (HOST or DEVICE)

Pre:

Size of source is greater than or equal to the current vector size.

ScalarT *getData(memory::MemorySpace memspace = memory::HOST)

get a pointer to HOST or DEVICE vector data.

Note

This function gives you access to the pointer, not to a copy. If you change the values using the pointer, the vector values will change too. Make sure to use setDataUpdated function to set the update flags correctly after changing the values.

Parameters:: memspace – [in] - Memory space of the pointer (HOST or DEVICE)
Returns:: pointer to the vector data (HOST or DEVICE). In case of multivectors, vectors are stored column-wise.

ScalarT *getData(IdxT i, memory::MemorySpace memspace = memory::HOST)

Get a pointer to HOST or DEVICE data of a vector in a multivector.

Note

This function gives you access to the pointer, not to a copy. If you change the values using the pointer, the vector values will change too. Call setDataUpdated() to update the staleness flags.

Parameters:

j – [in] - Index of a vector in multivector
memspace – [in] - Memory space of the pointer (HOST or DEVICE)

Returns:

Pointer to the _j_th vector data (HOST or DEVICE).

Pre:

j < k_, i.e., j is smaller than the number of vectors.

const ScalarT *getData(memory::MemorySpace memspace = memory::HOST) const

get a pointer to HOST or DEVICE vector data.

Parameters:: memspace – [in] - Memory space of the pointer (HOST or DEVICE)
Returns:: pointer to the vector data (HOST or DEVICE). In case of multivectors, vectors are stored column-wise.

const ScalarT *getData(IdxT i, memory::MemorySpace memspace = memory::HOST) const

Get a const pointer to HOST or DEVICE data of a vector in a multivector.

Parameters:

j – [in] - Index of a vector in multivector
memspace – [in] - Memory space of the pointer (HOST or DEVICE)

Returns:

Const pointer to the _j_th vector data (HOST or DEVICE).

Pre:

j < k_, i.e., j is smaller than the number of vectors.

IdxT getCapacity() const

Get capacity of a single vector.

Vector memory is allocated to n_capacity_*k_. This is the maximum number of elements that the (multi)vector can hold.

Returns:: n_capacity_ the maximum number of elements in the vector.

IdxT getSize() const

Get the number of elements in a single vector.

For vectors with changing sizes, set the vector capacity to the maximum expected size.

Returns:: n_size_ number of elements currently in the vector.

IdxT getNumVectors() const

Get the number of vectors in multivector.

Returns:: k, number of vectors in the multivector, or 1 if the vector is not a multivector.

int setDataUpdated(memory::MemorySpace memspace = memory::HOST)

Set the flag to indicate that the data (HOST or DEVICE) has been updated.

Use this function if you update vector elements by accessing the raw data pointer.

Warning

This is an expert level method. Use only if you know what you are doing.

Parameters:: memspace – [in] - Memory space (HOST or DEVICE)

int setDataUpdated(IdxT j, memory::MemorySpace memspace = memory::HOST)

Set the flag to indicate that the data (HOST or DEVICE) for vector j in the multivector has been updated.

Use this function if you update vector elements by accessing the raw data pointer.

Warning

This is an expert level method. Use only if you know what you are doing.

Parameters:: memspace – [in] - Memory space (HOST or DEVICE)

int setData(ScalarT *data, memory::MemorySpace memspace = memory::HOST)

Set the vector data pointer (HOST or DEVICE) to an external data.

Warning

This function DOES NOT ALLOCATE any data, it only assigns the pointer.

Warning

This is an expert level method. Use only if you know what you are doing.

Parameters:

data – [in] - Pointer to data
memspace – [in] - Memory space (HOST or DEVICE)

Pre:

Vector data pointers must be null. If the vector data already exists this function returns error message.

int allocate(memory::MemorySpace memspace = memory::HOST)

Allocate vector data for HOST or DEVICE.

Parameters:: memspace – [in] - Memory space of the data to be allocated

int setToZero(memory::MemorySpace memspace = memory::HOST)

Set vector data to zero.

In case of multivectors, the entire multivector is set to zero.

Parameters:: memspace – [in] - Memory space of the data to be zeroed (HOST or DEVICE)

int setToZero(IdxT i, memory::MemorySpace memspace = memory::HOST)

set the data of a single vector in a multivector to zero.

Parameters:

j – [in] - Index of a vector in the multivector
memspace – [in] - Memory space of the data to be zeroed (HOST or DEVICE)

Pre:

j < k_, i.e., j is smaller than the number of vectors.

int setToConst(ScalarT C, memory::MemorySpace memspace = memory::HOST)

set vector data to a given constant.

In case of multivectors, entire multivector is set to the constant.

Parameters:

C – [in] - Constant value to set
memspace – [in] - Memory space of the data to be set (HOST or DEVICE)

int setToConst(IdxT i, ScalarT C, memory::MemorySpace memspace = memory::HOST)

set the data of a single vector in a multivector to a given constant.

Parameters:

j – [in] - Index of a vector in the multivector
C – [in] - Constant value to set
memspace – [in] - Memory space of the data to be set (HOST or DEVICE)

Pre:

j < k_, i.e., j is smaller than the number of vectors.

int syncData(memory::MemorySpace memspaceOut = memory::HOST)

Sync out of date memory space with the updated one.

syncData is the only function that can set data on both HOST and DEVICE to the same values.

Warning

This function can be called only when all vectors in a multivector have the same update status. Otherwise, you need to sync vectors in a multivector individually.

Parameters:: memspaceDst – [in] - Memory space to sync
Returns:: 0 if successful, 1 otherwise.

int syncData(IdxT j, memory::MemorySpace memspaceOut = memory::HOST)

Sync out of date memory space with the updated one.

syncData is the only function that can set data on both HOST and DEVICE to the same values.

Warning

This function can be called only when all vectors in a multivector have the same update status. Otherwise, you need to sync vectors in a multivector individually.

Parameters:: memspaceDst – [in] - Memory space to sync
Returns:: 0 if successful, 1 otherwise.

int resize(IdxT new_n_current)

Resize vector to new_n_size.

Use for vectors and multivectors that change size throughout computation.

Note

Vector needs to have capacity set to maximum expected size.

Warning

This method is not to be used in vectors who do not own their data.

Parameters:: new_n_size – [in] - New vector length
Returns:: 0 if successful, 1 otherwise.
Pre:: new_n_size <= n_capacity_

int copyToExternal(ScalarT *dest, IdxT i, memory::MemorySpace memspaceSrc = memory::HOST, memory::MemorySpace memspaceDst = memory::HOST)

Copy HOST or DEVICE data of a single vector in a multivector to dest.

Supports cross-space copies, e.g. vector i from HOST to DEVICE.

Parameters:

dest – [out] - Destination array
i – [in] - Index of a vector in the multivector
memspaceSrc – [in] - Memory space of the source data (HOST or DEVICE)
memspaceDst – [in] - Memory space of the destination (HOST or DEVICE)

Returns:

0 if successful, 1 otherwise.

Pre:

i < k_, i.e., i is smaller than the number of vectors.

Pre:

dest is allocated with at least n elements in memspaceDst.

Post:

All elements of vector i are copied to dest.

int copyToExternal(ScalarT *dest, memory::MemorySpace memspaceSrc = memory::HOST, memory::MemorySpace memspaceDst = memory::HOST)

copy HOST or DEVICE data of multivector to dest.

This function allows to copy data between different memory spaces in one call. For example, you can copy data of multivector from HOST to DEVICE, or from DEVICE to HOST.

Parameters:

dest – [out] - Pointer to the memory to which data is copied
memspaceSrc – [in] - Memory space (HOST or DEVICE) of the data to be copied
memspaceDst – [in] - Memory space (HOST or DEVICE) to which data is copied

Returns:

0 if successful, 1 otherwise.

Pre:

dest is allocated, and the size of dest is at least n * k (total length of all vectors in the multivector).

Pre:

dest is allocated in memspaceOutDst memory space.

Post:

All elements of all vectors in multivector are copied to the array dest.