Multidimensional view#
The ndview class provides a view of the homogeneous data as a multidimensional structure
stored in an externally-managed memory block.
Programming interface#
All types and functions in this section are declared in the
oneapi::dal::backend::primitives namespace and be available via inclusion of the
oneapi/dal/table/ndarray.hpp header file.
-
template<typename T, std::int64_t axis_count, ndorder order = ndorder::c>
class ndview# - Template Parameters:
T – The type of elements in the view.
axis_count – The number of dimensions in the view.
order – C-contiguous (row-major) or FORTRAN-contiguous (column-major) order of the elements in 2-dimensional view.
Public Static Methods
-
static ndview wrap(T *data, const shape_t &shape)#
Creates a new multidimensional view instance by passing the pointer to externally-defined memory block for mutable data.
- Parameters:
data – The pointer to a homogeneous data block.
shape – The shape of the created multidimensional array.
-
static ndview wrap(const T *data, const shape_t &shape)#
Creates a new multidimensional view instance by passing the pointer to externally-defined memory block for immutable data.
- Parameters:
data – The pointer to a homogeneous data block.
shape – The shape of the created multidimensional array.
-
static ndview wrap(T *data, const shape_t &shape, const shape_t &strides)#
Creates a new strided multidimensional view instance by passing the pointer to externally-defined memory block for mutable data.
- Parameters:
data – The pointer to a homogeneous data block.
shape – The shape of the created multidimensional view.
strides – The strides of the created multidimensional view.
-
static ndview wrap(const T *data, const shape_t &shape, const shape_t &strides)#
Creates a new strided multidimensional view instance by passing the pointer to externally-defined memory block for immutable data.
- Parameters:
data – The pointer to a homogeneous data block.
shape – The shape of the created multidimensional view.
strides – The strides of the created multidimensional view.
-
static ndview wrap_mutable(const array<T> &data, const shape_t &shape)#
Creates a new multidimensional view instance from a mutable array.
- Parameters:
data – The array that stores a homogeneous data block.
shape – The shape of the created multidimensional view.
-
static ndview wrap_mutable(const array<T> &data, const shape_t &shape, const shape_t &strides)#
Creates a new strided multidimensional view instance from a mutable array.
- Parameters:
data – The array that stores a homogeneous data block.
shape – The shape of the created multidimensional view.
strides – The strides of the created multidimensional view.
-
template<std::int64_t d = axis_count, typename None = std::enable_if_t<d == 1>>
static ndview wrap(const array<T> &data)# Creates a new 1d view instance from an immutable array.
- Parameters:
data – The array that stores a homogeneous data block.
-
template<std::int64_t d = axis_count, typename None = std::enable_if_t<d == 1>>
static ndview wrap_mutable(const array<T> &data)# Creates a new 1d view instance from a mutable array.
- Parameters:
data – The array that stores a homogeneous data block.
Constructors
-
ndview()#
Public Methods
-
const T *get_data() const#
The pointer to the memory block holding immutable data.
-
T *get_mutable_data() const#
The pointer to the memory block holding mutable data.
-
bool has_data() const#
Returns whether the view contains data or not.
-
bool has_mutable_data() const#
Returns whether the view contains mutable data or not.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 1>>
const T &at(std::int64_t id) const# Returns a reference to the element of 1d immutable view at specified location.
- Parameters:
id – The index of the element to be returned.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 2>>
const T &at(std::int64_t id0, std::int64_t id1) const# Returns a reference to the element of 2d immutable view at specified location.
- Parameters:
id0 – The index of the element along the 0-th axis.
id1 – The index of the element along the 1-st axis.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 1>>
T &at(std::int64_t id)# Returns a reference to the element of 1d mutable view at specified location.
- Parameters:
id – The index of the element to be returned.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 2>>
T &at(std::int64_t id0, std::int64_t id1)# Returns a reference to the element of 2d mutable view at specified location.
- Parameters:
id0 – The index of the element along the 0-th axis.
id1 – The index of the element along the 1-st axis.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 1>>
T at_device(sycl::queue &queue, std::int64_t id, const event_vector &deps = {}) const# Returns a copy of the element of 1d immutable view located in USM at specified location. The data is copied from the device to the host after the dependency events are completed.
- Parameters:
queue – The SYCL* queue object.
id – The index of the element to be returned.
deps – The vector of events that the operation depends on.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 2>>
T at_device(sycl::queue &queue, std::int64_t id0, std::int64_t id1, const event_vector &deps = {}) const# Returns a copy of the element of 2d immutable view located in USM at specified location. The data is copied from the device to the host after the dependency events are completed.
- Parameters:
queue – The SYCL* queue object.
id0 – The index of the element along the 0-th axis.
id1 – The index of the element along the 1-st axis.
deps – The vector of events that the operation depends on.
-
auto t() const#
Get transposed multidimensional view. The shape and strides of the transposed multidimensional view are swapped.The data is not modified or copied: The transposed ndview points to the same memory block as the original ndview.
-
template<std::int64_t new_axis_count, ndorder new_order = order>
auto reshape(const ndshape<new_axis_count> &new_shape) const# Get the multidimensional view of the data reshaped to the requested shape. The total number of elements in the reshaped view must remain the same. The data is not copied: the reshaped ndview points to the same memory block as the original ndview.
- Template Parameters:
new_axis_count – The number of dimensions in the reshaped multidimensional view.
- Parameters:
new_shape – The shape of the reshaped multidimensional view.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 1>>
ndview get_slice(std::int64_t from, std::int64_t to) const# Get 1-dimensional slice of 1-dimensional view. The slice is a view into the original memory block. The data is not copied: The sliced view points to the data within the same memory block as the original ndview.
- Parameters:
from – The starting index of the data slice within the input view.
to – The ending index of the data slice within the input view.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 2>>
ndview get_row_slice(std::int64_t from_row, std::int64_t to_row) const# Get 2-dimensional row slice of 2-dimensional view. The slice is a view into the original memory block. The data is not copied: The sliced view points to the data within the same memory block as the original ndview.
- Parameters:
from_row – The starting row index of the data slice within the input view.
to_row – The ending row index of the data slice within the input view.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 2>>
ndview get_col_slice(std::int64_t from_col, std::int64_t to_col) const# Get 2-dimensional column slice of 2-dimensional view. The slice is a view into the original memory block. The data is not copied: The sliced view points to the data within the same memory block as the original ndview.
- Parameters:
from_col – The starting column index of the data slice within the input view.
to_col – The ending column index of the data slice within the input view.
-
ndarray<T, axis_count, order> to_host(sycl::queue &q, const event_vector &deps = {}) const#
Creates a multidimensional array with the same shape as the view, but having the data allocated on host. The data from the view is copied to the array on host.
- Parameters:
q – The SYCL* queue object.
deps – The vector of events that the operation depends on.
-
ndarray<T, axis_count, order> to_device(sycl::queue &q, const event_vector &deps = {}) const#
Creates a multidimensional array with the same shape as the view, but having the data allocated in USM on device. The data from the view is copied to the array on device.
- Parameters:
q – The SYCL* queue object.
deps – The vector of events that the operation depends on.
-
sycl::event prefetch(sycl::queue &queue) const#
Prefetches the data from high bandwidth memory to local cache. Should be submitted ahead the expected computations to have enough time for data transfer.
- Parameters:
queue – The SYCL* queue object.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 1>>
T *begin()# Returns the pointer to the first element of the 1-dimensional view.
-
template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 1>>
T *end()# Returns the pointer to the past-the-last element of the 1-dimensional view.