Documentation for oneAPI data management backend primitives #3008

Vika-F · 2024-12-04T12:20:50Z

ndview, ndarray and related primitives are documented.

PR completeness and readability

I have reviewed my changes thoroughly before submitting this pull request.
I have commented my code, particularly in hard-to-understand areas.
I have updated the documentation to reflect the changes or created a separate PR with update and provided its number in the description, if necessary.
Git commit message contains an appropriate signed-off-by string (see CONTRIBUTING.md for details).
I have added a respective label(s) to PR if I have a permission for that.
I have resolved any merge conflicts that might occur with the base branch.

david-cortes-intel · 2024-12-09T15:13:27Z

Would be helpful if we could merge this PR first:
#3004

So that we could then check that this one isn't introducing new warnings that might be masked by previous ones in the CI logs.

david-cortes-intel · 2024-12-16T15:20:37Z

cpp/oneapi/dal/backend/primitives/ndarray.hpp

@@ -285,11 +376,22 @@ class ndview : public ndarray_base<axis_count, order> {
    }

 #ifdef ONEDAL_DATA_PARALLEL
+    /// Returns a copy of the element of 1d immutable view located in USM at specified location.


Does it execute operations in a queue if the data depends on it?

I think I do not fully understand the question. This operation is about the same as other sycl operations, it will be included into the flow of dependencies along with the other operations.

Suppose that the array is the result of a computation like $t(X)*X$.

The operation that calculates the numbers in the array returns a queue, and might not have been completed by the time that .at is called.

Will the call to .at force calculations of the operations in the queues before returning a scalar?

Sure, in case the events triggered by $t(X) \cdot X$ are passed into the deps vector correctly.

Would be helpful to mention that in the docs.

david-cortes-intel · 2024-12-16T15:23:08Z

cpp/oneapi/dal/backend/primitives/ndarray.hpp

@@ -539,14 +712,26 @@ inline sycl::event fill(sycl::queue& q,
 }
 #endif

+/// Multidimensional array


How does it differ from sycl's own class?

I do not think sycl has own multidimensional data representations.

But it does have a 1D marray. Lots of the usage for views is as 1D containers, so I was curious about their usage over sycl's.

I think besides of multidimensionality, our data structures are interoperable in the sense one can easily view the same data block as dal::table, dal::array, dal::backend::primitives::ndview, etc.

Also here we implement convenience functions like slice, transpose, to_host, etc.

With sycl own structures the amount of code inside oneDAL algorithmic kernels would be much bigger. Anyway we would need to wrap some common operations into functions. This class groups those common operations on the data together.

Would be helpful to add a hint to prefer these custom classes instead of sycl's.

david-cortes-intel · 2024-12-16T15:25:33Z

docs/source/api/data-management/backend-primitives.rst

+
+.. toctree::
+
+   backend/ndarray.rst


What's the relationship between "tables" and "arrays"?

Good point. Will add an example on how tables and ndarrays/ndviews are used together and the description of the differences.

Short answer:

tables are user-facing API, always 2-dimensional.

ndarray is internal convenience API, not available in release headers. Multidimensional.

…xlfoundation-main

Vika-F · 2024-12-18T12:56:36Z

@rakshithgb-fujitsu, @keeranroth can you please provide the feedback?

keeranroth

The comments look good for the code that is present, so I've refrained from commenting on the code. But for my own information, is there a plan to make the views constexpr, or to have the layout separate from the data, so that the offsets into arrays / pointers / multi-dimensional arrays can be calculated at compile time? And does the implementation support arbitrary shapes and strides, e.g. having a layout of the shape (a, (b, c), d), which is a 3 dimensional object, where the second dimension is a 2-dimensional object. This is useful in terms of doing things like cache-blocking. Not for this code review, but it would be great to see functionality like this, if it doesn't already exist

keeranroth · 2024-12-20T14:16:22Z

cpp/oneapi/dal/backend/primitives/ndarray.hpp

+    /// Returns a reference to the element of 1d immutable view at specified location.
+    ///
+    /// @note This method does not perform boundary checks in release build.
+    ///       In debug build, the method asserts that the index is out of the bounds.


Suggested change

/// In debug build, the method asserts that the index is out of the bounds.

/// In debug build, the method asserts that the index is not out of bounds.

keeranroth · 2024-12-20T14:18:33Z

cpp/oneapi/dal/backend/primitives/ndarray.hpp

+    /// @note This method does not perform boundary checks in release build.
+    ///       In debug build, the method asserts that the index is out of the bounds.
+    ///
+    /// @note Should be used carefully in performance-critical parts of the code


nit: The fact that the method is in the header means that it is implicitly inline. It is likely to be inlined, but not guaranteed to be. The comment should reflect this

@note Should be used carefully in performance-critical parts of the code, as inlining is not guaranteed.

keeranroth · 2024-12-20T14:19:46Z

cpp/oneapi/dal/backend/primitives/ndarray.hpp

+    /// Returns a reference to the element of 2d immutable view at specified location.
+    ///
+    /// @note This method does not perform boundary checks in release build.
+    ///       In debug build, the method asserts that the index is out of the bounds.


Suggested change

/// In debug build, the method asserts that the index is out of the bounds.

/// In debug build, the method asserts that the index is not of bounds.

keeranroth · 2024-12-20T14:20:18Z

cpp/oneapi/dal/backend/primitives/ndarray.hpp

+    /// @note This method does not perform boundary checks in release build.
+    ///       In debug build, the method asserts that the index is out of the bounds.
+    ///
+    /// @note Should be used carefully in performance-critical parts of the code


nit: The fact that the method is in the header means that it is implicitly inline. It is likely to be inlined, but not guaranteed to be. The comment should reflect this

@note Should be used carefully in performance-critical parts of the code, as inlining is not guaranteed.

keeranroth · 2024-12-20T14:25:44Z

cpp/oneapi/dal/backend/primitives/ndarray.hpp

    sycl::event prefetch(sycl::queue& queue) const {
        return queue.prefetch(data_, this->get_count());
    }
 #endif

+    /// Returns the iterator to the first element of the 1-dimensional view.


nit: This is not returning a generic iterator, it is specifically pointers that are dealt with. Similar comments for the methods below, where iterator is mentioned

Suggested change

/// Returns the iterator to the first element of the 1-dimensional view.

/// Returns the pointer to the first element of the 1-dimensional view.

keeranroth · 2024-12-20T14:28:00Z

cpp/oneapi/dal/backend/primitives/ndarray.hpp

+/// Multidimensional array
+///
+/// @tparam T           The type of the memory block elements within the multidimensional array.
+///                     :literal:`T` can represent :expr:`float`, :expr:`double` or :expr:`std::int32_t`.


Is there a restriction on the data type? I can't see anything in this header that suggests the type of data does need to be restricted. Can this comment be removed?

Initial version of documentations for data management primitives

f5a0ec1

Vika-F added the docs Issue/PR related to oneDAL docs label Dec 4, 2024

Add API reference for ndarray

f87e7db

Add comments in ndview and ndarray classes

8b07f58

david-cortes-intel reviewed Dec 16, 2024

View reviewed changes

Vika-F added 4 commits December 18, 2024 03:31

Improve descriptions of backend primitives classes

7985c6b

Merge branch 'main' of https://github.com/uxlfoundation/oneDAL into u…

0563591

…xlfoundation-main

Merge branch 'uxlfoundation-main' into dev/data_management_doc

93e970d

Correct license

cbca096

Vika-F marked this pull request as ready for review December 18, 2024 12:54

Vika-F requested review from Alexsandruss, samir-nasibli, Alexandr-Solovev and maria-Petrova as code owners December 18, 2024 12:54

keeranroth suggested changes Dec 20, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for oneAPI data management backend primitives #3008

Documentation for oneAPI data management backend primitives #3008

Vika-F commented Dec 4, 2024 •

edited

Loading

david-cortes-intel commented Dec 9, 2024

david-cortes-intel Dec 16, 2024

Vika-F Dec 18, 2024

david-cortes-intel Dec 18, 2024

Vika-F Dec 18, 2024

david-cortes-intel Dec 18, 2024

david-cortes-intel Dec 16, 2024

Vika-F Dec 18, 2024

david-cortes-intel Dec 18, 2024

Vika-F Dec 18, 2024

david-cortes-intel Dec 18, 2024

david-cortes-intel Dec 16, 2024

Vika-F Dec 18, 2024 •

edited

Loading

Vika-F commented Dec 18, 2024

keeranroth left a comment

keeranroth Dec 20, 2024

keeranroth Dec 20, 2024

keeranroth Dec 20, 2024

keeranroth Dec 20, 2024

keeranroth Dec 20, 2024

keeranroth Dec 20, 2024

	/// In debug build, the method asserts that the index is out of the bounds.
	/// In debug build, the method asserts that the index is not out of bounds.

	/// Returns the iterator to the first element of the 1-dimensional view.
	/// Returns the pointer to the first element of the 1-dimensional view.

Documentation for oneAPI data management backend primitives #3008

Are you sure you want to change the base?

Documentation for oneAPI data management backend primitives #3008

Conversation

Vika-F commented Dec 4, 2024 • edited Loading

david-cortes-intel commented Dec 9, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Vika-F Dec 18, 2024 • edited Loading

Choose a reason for hiding this comment

Vika-F commented Dec 18, 2024

keeranroth left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Vika-F commented Dec 4, 2024 •

edited

Loading

Vika-F Dec 18, 2024 •

edited

Loading