Backend Primitives#

Refer to Developer Guide: Backend Primitives.

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/backend/primitives/ndarray.hpp header file.

Multidimensional data view (ndview)#

An implementation of a multidimensional data container that provides a view of the homogeneous data stored in an externally-managed memory block.

All the ndview class methods can be divided into several groups:

  1. The group of wrap() methods that are used to create an ndview object from external, mutable or immutable memory.

  2. The group of wrap_mutable() methods that are used to create a mutable ndview object from dal::array object.

  3. The methods that are used to access the data.

  4. The methods like t() and reshape() that are used to change the shape and layout of the data view.

  5. The group of data slicing methods that are used to create a new ndview object that is a view of the original data slice along some dimension.

  6. The group of data transfering methods that are used to produce a new ndview object that contains the data copied from the original one, but at the different memory location.

Multidimensional array (ndarray)#

An implementation of multidimensional data array that provides a way to store and manipulate homogeneous data in a multidimensional structure.

All the ndarray class methods can be divided into several groups:

  1. The group of wrap() and wrap_mutable() methods that are used to create an ndarray object from external, mutable or immutable memory.

  2. The group of wrap() and wrap_mutable() methods that are used to create an ndarray that shares its data with another data object.

  3. The group of methods like zeros(), full(), arange(), etc. that are used to create an ndarray object with the specified shape and values.

  4. The methods like t() and reshape() that are used to change the shape and layout of the multidimensional array.

  5. The group of data slicing methods that are used to create a new ndarray object that is a view of the original data slice along some dimension.

  6. The group of methods like fill(), assign(), assign_from_host(), etc. that are used to fill the array with the specified values.

Table to ndarray conversion functions#

template<typename Type>
ndarray<Type, 2> table2ndarray(const table &table)#

Convert a table to a 2D ndarray.

Template Parameters:

Type – The type of the memory block elements within the ndarray.

Parameters:

table – Input table.

template<typename Type, ndorder order = ndorder::c>
ndarray<Type, 2, order> table2ndarray(sycl::queue &q, const table &table, sycl::usm::alloc alloc = sycl::usm::alloc::shared)#

Convert a table to a 2D ndarray.

Template Parameters:

  • Type – The type of the memory block elements within the ndarray.

  • order – The order of the ndarray.

Parameters:

  • q – The SYCL* queue.

  • table – Input table.

  • alloc – The USM allocation type.

template<typename Type>
ndarray<Type, 1> table2ndarray_1d(const table &table)#

Convert a table to a 1D ndarray.

Template Parameters:

Type – The type of the memory block elements within the ndarray.

Parameters:

table – Input table.

template<typename Type>
ndarray<Type, 1> table2ndarray_1d(sycl::queue &q, const table &table, sycl::usm::alloc alloc = sycl::usm::alloc::shared)#

Convert a table to a 1D ndarray.

Template Parameters:

Type – The type of the memory block elements within the ndarray.

Parameters:

  • q – The SYCL* queue.

  • table – Input table.

  • alloc – The USM allocation type.

template<typename Type>
ndarray<Type, 2, ndorder::c> table2ndarray_rm(sycl::queue &q, const table &table, sycl::usm::alloc alloc)#

Convert a table to a 2D ndarray with row-major data order.

Template Parameters:

Type – The type of the memory block elements within the ndarray.

Parameters:

  • q – The SYCL* queue.

  • table – Input table.

  • alloc – The USM allocation type.

template<typename Type>
ndarray<Type, 2, ndorder::f> table2ndarray_cm(sycl::queue &q, const table &table, sycl::usm::alloc alloc)#

Convert a table to a 2D ndarray with column-major data order.

Template Parameters:

Type – The type of the memory block elements within the ndarray.

Parameters:

  • q – The SYCL* queue.

  • table – Input table.

  • alloc – The USM allocation type.

template<typename Type>
ndarray<Type, 2, ndorder::f> homogen_table2ndarray_cm(sycl::queue &q, const table &table, sycl::usm::alloc alloc)#

Convert a homogeneous table to a 2D ndarray with column-major data order.

Template Parameters:

Type – The type of the memory block elements within the ndarray.

Parameters:

  • q – The SYCL* queue.

  • table – Input table.

  • alloc – The USM allocation type.

template<typename Type>
auto table2ndarray_variant(sycl::queue &q, const table &table, sycl::usm::alloc alloc)#

Convert a table to a 2D ndarray with the data order determined by the table layout.

Template Parameters:

Type – The type of the memory block elements within the ndarray.

Parameters:

  • q – The SYCL* queue.

  • table – Input table.

  • alloc – The USM allocation type.

Multidimensional array order#

Refers to data indexing order, or how a linear sequence is translated into a multi-dimensional array.

enum class ndorder#
ndorder::c

C-style ordering, row-major in 2D case.

ndorder::f

Fortran-style ordering, column-major in 2D case.

Multidimensional array shape#

template<std::int64_t axis_count>
class ndshape#
Template Parameters:

axis_count – The number of dimensions in the shape.

Public Static Methods

static ndshape square(std::int64_t dimension)#

Creates a shape representing a hypercube with the specified dimension.

Parameters:

dimension – The dimension of the hypercube.

Constructors

ndshape()#

Creates a new instance of the class with all dimensions set to zero.

ndshape(const ndindex<axis_count> &dimensions)#

Creates a new instance of the class with the specified dimensions.

Parameters:

dimensions – The dimensions of the shape.

template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 1>>
ndshape(std::int64_t d1)#

Creates a 1-dimensional shape with the specified dimension.

Parameters:

d1 – The dimension of the shape.

template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 2>>
ndshape(std::int64_t d1, std::int64_t d2)#

Creates a 2-dimensional shape with the specified dimensions.

Parameters:

  • d1 – The first dimension of the shape.

  • d2 – The second dimension of the shape.

template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 3>>
ndshape(std::int64_t d1, std::int64_t d2, std::int64_t d3)#

Creates a 3-dimensional shape with the specified dimensions.

Parameters:

  • d1 – The first dimension of the shape.

  • d2 – The second dimension of the shape.

  • d3 – The third dimension of the shape.

Public Methods

std::int64_t operator[](std::int64_t i) const#

Returns the i-th dimension of the shape.

Parameters:

i – The index of the dimension.

std::int64_t at(std::int64_t i) const#

Returns the i-th dimension of the shape.

Parameters:

i – The index of the dimension.

std::int64_t get_count() const#

The number of elements in the multidimensional data structure defined by this shape.

ndshape t() const#

Returns the shape with the reversed dimensions.

bool operator==(const ndshape &other) const#

Check if the shape is equal to the other shape.

bool operator!=(const ndshape &other) const#

Check if the shape is not equal to the other shape.

const ndindex<axis_count> &get_index() const#

Return the dimensions of the shape.

template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 1>>
sycl::range<1> to_range() const#

Returns 1-dimensional SYCL* range of the same size as this 1-dimensional shape.

template<std::int64_t n = axis_count, typename None = std::enable_if_t<n == 2>>
sycl::range<2> to_range() const#

Returns 2-dimensional SYCL* range of the same size as this 2-dimensional shape.