Multidimensional array#

The ndarray class provides a way to store and manipulate homogeneous data in a multidimensional structure. The pointer to the data within the ndarray object is reference-counted:.

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>
class ndarray#
Template Parameters:

  • T – The type of the memory block elements within the multidimensional array.

  • axis_count – The number of dimensions in the multidimensional array.

  • order – Row-major or column-major order of the 2-dimensional array.

Public Static Methods

template<typename Deleter = dal::detail::empty_delete<T>>
static ndarray wrap(T *data, const shape_t &shape, Deleter &&deleter = Deleter{})#

Creates a new multidimensional array instance by passing the pointer to externally-defined memory block for mutable data.

Template Parameters:

Deleter – The type of a deleter called on data when the last ndarray that refers it is out of the scope.

Parameters:

  • data – The pointer to a homogeneous data block.

  • shape – The shape of the created multidimensional array.

  • deleter – The deleter that is called on the data when the last ndarray that refers it is out of the scope.

template<typename Deleter = dal::detail::empty_delete<T>>
static ndarray wrap(const T *data, const shape_t &shape, Deleter &&deleter = Deleter{})#

Creates a new multidimensional array instance by passing the pointer to externally-defined memory block for immutable data.

Template Parameters:

Deleter – The type of a deleter called on data when the last ndarray that refers it is out of the scope.

Parameters:

  • data – The pointer to a homogeneous data block.

  • shape – The shape of the created multidimensional array.

  • deleter – The deleter that is called on the data when the last ndarray that refers it is out of the scope.

static ndarray wrap(const shared_t &data, const shape_t &shape)#

Creates a new multidimensional array instance by passing the shared pointer to externally-defined memory block for mutable data.

Parameters:

  • data – The shared pointer to a homogeneous data block.

  • shape – The shape of the created multidimensional array.

static ndarray wrap(shared_t &&data, const shape_t &shape)#

Creates a new multidimensional array instance by moving a shared pointer to externally-defined memory block for mutable data.

Parameters:

  • data – R-value reference to the shared pointer to a homogeneous data block.

  • shape – The shape of the created multidimensional array.

static ndarray wrap(const array_t &ary, const shape_t &shape)#

Creates a new multidimensional array instance from an immutable array. The created multidimensional array shares data ownership with the given array.

Parameters:

  • ary – The array that stores a homogeneous data block.

  • shape – The shape of the created multidimensional array.

static ndarray wrap(array_t &&ary, const shape_t &shape)#

Creates a new multidimensional array instance by moving an immutable input array.

Parameters:

  • ary – The r-value reference to array that stores a homogeneous data block.

  • shape – The shape of the created multidimensional array.

static ndarray wrap(const array_t &ary)#

Creates a 1d ndarray instance from an immutable array. The created ndarray shares data ownership with the given array.

Parameters:

ary – The array that stores a homogeneous data block.

static ndarray wrap(array_t &&ary)#

Creates a 1d ndarray instance by moving an immutable input array. The created ndarray shares data ownership with the given array.

Parameters:

ary – The r-value reference to array that stores a homogeneous data block.

static ndarray wrap_mutable(const array_t &ary, const shape_t &shape)#

Creates a new multidimensional array instance from a mutable array. The created multidimensional array shares data ownership with the given array.

Parameters:

  • ary – The array that stores a homogeneous data block.

  • shape – The shape of the created multidimensional array.

static ndarray wrap_mutable(array_t &&ary, const shape_t &shape)#

Creates a new multidimensional array instance by moving a mutable input array.

Parameters:

  • ary – The r-value reference to array that stores a homogeneous data block.

  • shape – The shape of the created multidimensional array.

static ndarray wrap_mutable(const array_t &ary)#

Creates a 1d ndarray instance from a mutable array. The created ndarray shares data ownership with the given array.

Parameters:

ary – The array that stores a homogeneous data block.

static ndarray wrap_mutable(array_t &&ary)#

Creates a 1d ndarray instance by moving a mutable input array. The created ndarray shares data ownership with the given array.

Parameters:

ary – The array that stores a homogeneous data block.

static ndarray empty(const shape_t &shape)#

Creates an uninitialized multidimensional array of a requested shape.

Parameters:

shape – The shape of the created multidimensional array.

static ndarray copy(const T *data, const shape_t &shape)#

Creates a multidimensional array of the requested shape and copies the values from the input pointer to a memory block into that multidimensional array.

Parameters:

  • data – The pointer to a homogeneous data block.

  • shape – The shape of the created multidimensional array.

static ndarray zeros(const shape_t &shape)#

Creates a multidimensional array of the requested shape and fills it with zeros.

Parameters:

shape – The shape of the created multidimensional array.

static ndarray empty(const sycl::queue &q, const shape_t &shape, const sycl::usm::alloc &alloc_kind = sycl::usm::alloc::shared)#

Creates an uninitialized multidimensional array of a requested shape with the elements stored in SYCL* USM.

Parameters:

  • q – The SYCL* queue object.

  • shape – The shape of the created multidimensional array.

  • alloc_kind – The kind of USM to be allocated.

static std::tuple<ndarray, sycl::event> copy(sycl::queue &q, const T *data, const shape_t &shape, const sycl::usm::alloc &alloc_kind = sycl::usm::alloc::shared)#

Creates a multidimensional array of the requested shape with the elements stored in SYCL* USM and copies the values from the input pointer to a memory block into that multidimensional array.

Parameters:

  • q – The SYCL* queue object.

  • data – The pointer to a homogeneous data block.

  • shape – The shape of the created multidimensional array.

  • alloc_kind – The kind of USM to be allocated.

static std::tuple<ndarray, sycl::event> full(sycl::queue &q, const shape_t &shape, const T &value, const sycl::usm::alloc &alloc_kind = sycl::usm::alloc::shared, const event_vector &deps = {})#

Creates a multidimensional array of the requested shape with the elements stored in SYCL* USM and fills it with a scalar value provided.

Parameters:

  • q – The SYCL* queue object.

  • shape – The shape of the created multidimensional array.

  • value – The scalar value to fill the array with.

  • alloc_kind – The kind of USM to be allocated.

  • deps – The vector of events that the operation depends on.

static std::tuple<ndarray, sycl::event> zeros(sycl::queue &q, const shape_t &shape, const sycl::usm::alloc &alloc_kind = sycl::usm::alloc::shared)#

Creates a multidimensional array of the requested shape with the elements stored in SYCL* USM and fills it with zeros.

Parameters:

  • q – The SYCL* queue object.

  • shape – The shape of the created multidimensional array.

  • alloc_kind – The kind of USM to be allocated.

static std::tuple<ndarray, sycl::event> ones(sycl::queue &q, const shape_t &shape, const sycl::usm::alloc &alloc_kind = sycl::usm::alloc::shared)#

Creates a multidimensional array of the requested shape with the elements stored in SYCL* USM and fills it with ones.

Parameters:

  • q – The SYCL* queue object.

  • shape – The shape of the created multidimensional array.

  • alloc_kind – The kind of USM to be allocated.

Constructors

ndarray() = default#

Public Methods

const base &get_view() const#

Get ndview sub-object of the ndarray.

array_t flatten() const#

Get 1d dal::array that shares the ownership on the data block of this ndarray.

array_t flatten(sycl::queue &q, const event_vector &deps = {}) const#

Get 1d dal::array that shares the ownership on the SYCL* USM data block of this ndarray.

Parameters:

  • q – The SYCL* queue object.

  • deps – The vector of events that the operation depends on.

auto t() const#

Get transposed multidimensional array. The shape and strides of the transposed multidimensional array are swapped.The data is not copied: The transposed ndarray shares the ownership on the data block with the original ndarray.

template<std::int64_t new_axis_count>
auto reshape(const ndshape<new_axis_count> &new_shape) const#

Get the multidimensional array reshaped to the requested shape. The total number of elements in the reshaped array must remain the same. The data is not copied: the reshaped ndarray shares the ownership on the data block with the original ndarray.

Template Parameters:

new_axis_count – The number of dimensions in the reshaped multidimensional array.

Parameters:

new_shape – The shape of the reshaped multidimensional array.

void fill(T value)#

Fill multidimensional array with a scalar value.

Parameters:

value – The scalar value to fill the array with.

sycl::event fill(sycl::queue &q, T value, const event_vector &deps = {})#

Fill multidimensional array with a scalar value.

Parameters:

  • q – The SYCL* queue object.

  • value – The scalar value to fill the array with.

  • deps – The vector of events that the operation depends on.

void arange()#

Fill multidimensional array with the values from a sequence 0, 1, 2, …, N-1, where N is the total number of elements in the array.

sycl::event arange(sycl::queue &q, const event_vector &deps = {})#

Fill multidimensional array with the values from a sequence 0, 1, 2, …, N-1, where N is the total number of elements in the array.

Parameters:

  • q – The SYCL* queue object.

  • deps – The vector of events that the operation depends on.

void assign(const T *source_ptr, std::int64_t source_count)#

Copy the values from the input pointer to a memory block into multidimensional array.

Parameters:

  • source_ptr – The pointer to a homogeneous data block.

  • source_count – The number of elements in the input memory block.

sycl::event assign(sycl::queue &q, const T *source_ptr, std::int64_t source_count, const event_vector &deps = {})#

Copy the values from the input pointer to SYCL* USM memory block into multidimensional array.

Parameters:

  • q – The SYCL* queue object.

  • source_ptr – The pointer to a homogeneous data block.

  • source_count – The number of elements in the input memory block.

  • deps – The vector of events that the operation depends on.

sycl::event assign_from_host(sycl::queue &q, const T *source_ptr, std::int64_t source_count, const event_vector &deps = {})#

Copy the values from the input pointer to a memory block allocated on host into multidimensional array.

Parameters:

  • q – The SYCL* queue object.

  • source_ptr – The pointer to a homogeneous data block allocated in host memory.

  • source_count – The number of elements in the input memory block.

  • deps – The vector of events that the operation depends on.

sycl::event assign(sycl::queue &q, const ndarray &src, const event_vector &deps = {})#

Copy the values from the input multidimensional array into this multidimensional array.

Parameters:

  • q – The SYCL* queue object.

  • src – The multidimensional array to copy data from.

  • deps – The vector of events that the operation depends on.

sycl::event assign_from_host(sycl::queue &q, const ndarray &src, const event_vector &deps = {})#

Copy the values from the input multidimensional array containing data allocated on host into this multidimensional array.

Parameters:

  • q – The SYCL* queue object.

  • src – The multidimensional array to copy data from.

  • deps – The vector of events that the operation depends on.

ndarray slice(std::int64_t offset, std::int64_t count, std::int64_t axis = 0) const#

Get a slice of the multidimensional array along the specified axis. The slice is a view into the original multidimensional array. The data is not copied: The sliced ndarray shares the ownership on the data block.

Parameters:

  • offset – The offset along the specified axis.

  • count – The number of elements along the specified axis.

  • axis – The axis to slice along. Only axis 0 is supported.

std::vector<ndarray> split(std::int64_t fold_count, std::int64_t axis = 0) const#

Split a multidimensional array into multiple slices along the specified axis. The slices are views into the original multidimensional array. The data is not copied: The sliced ndarrays share the ownership on the data block.

Parameters:

  • fold_count – The number of slices to split the multidimensional array into.

  • axis – The axis to split along. Only axis 0 is supported.